4 # Copyright (C) 2006, 2007, 2008, 2009, 2010, 2012, 2013 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
22 """Base class for all hypervisors
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}.
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
45 from ganeti import errors
46 from ganeti import utils
47 from ganeti import constants
50 def _IsCpuMaskWellFormed(cpu_mask):
51 """Verifies if the given single CPU mask is valid
53 The single CPU mask should be in the form "a,b,c,d", where each
54 letter is a positive number or range.
58 cpu_list = utils.ParseCpuMask(cpu_mask)
59 except errors.ParseError, _:
61 return isinstance(cpu_list, list) and len(cpu_list) > 0
64 def _IsMultiCpuMaskWellFormed(cpu_mask):
65 """Verifies if the given multiple CPU mask is valid
67 A valid multiple CPU mask is in the form "a:b:c:d", where each
68 letter is a single CPU mask.
72 utils.ParseMultiCpuMask(cpu_mask)
73 except errors.ParseError, _:
79 # Read the BaseHypervisor.PARAMETERS docstring for the syntax of the
83 _FILE_CHECK = (utils.IsNormAbsPath, "must be an absolute normalized path",
84 os.path.isfile, "not found or not a file")
87 _DIR_CHECK = (utils.IsNormAbsPath, "must be an absolute normalized path",
88 os.path.isdir, "not found or not a directory")
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",
96 # Multiple CPU mask must be well-formed
97 _MULTI_CPU_MASK_CHECK = (_IsMultiCpuMaskWellFormed,
98 "Multiple CPU mask definition is not well-formed",
101 # Check for validity of port number
102 _NET_PORT_CHECK = (lambda x: 0 < x < 65535, "invalid port number",
105 # Check that an integer is non negative
106 _NONNEGATIVE_INT_CHECK = (lambda x: x >= 0, "cannot be negative", None, None)
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
123 NO_CHECK = (False, None, None, None, None)
125 # required, but no other checks
126 REQUIRED_CHECK = (True, None, None, None, None)
129 MIGRATION_MODE_CHECK = (True, lambda x: x in constants.HT_MIGRATION_MODES,
130 "invalid migration mode", None, None)
133 def ParamInSet(required, my_set):
134 """Builds parameter checker for set membership.
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
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)
147 class BaseHypervisor(object):
148 """Abstract virtualisation technology interface
150 The goal is that all aspects of the virtualisation technology are
151 abstracted away from the rest of code.
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
169 ANCILLARY_FILES_OPT = []
172 def StartInstance(self, instance, block_devices, startup_paused):
173 """Start an instance."""
174 raise NotImplementedError
176 def StopInstance(self, instance, force=False, retry=False, name=None):
179 @type instance: L{objects.Instance}
180 @param instance: instance to stop
182 @param force: whether to do a "hard" stop (destroy)
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
191 raise NotImplementedError
193 def CleanupInstance(self, instance_name):
194 """Cleanup after a stopped instance
196 This is an optional method, used by hypervisors that need to cleanup after
197 an instance has been stopped.
199 @type instance_name: string
200 @param instance_name: instance name to cleanup after
205 def RebootInstance(self, instance):
206 """Reboot an instance."""
207 raise NotImplementedError
209 def ListInstances(self, hvparams=None):
210 """Get the list of running instances."""
211 raise NotImplementedError
213 def GetInstanceInfo(self, instance_name, hvparams=None):
214 """Get instance properties.
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
221 @return: tuple (name, id, memory, vcpus, state, times)
224 raise NotImplementedError
226 def GetAllInstancesInfo(self, hvparams=None):
227 """Get properties of all instances.
229 @type hvparams: dict of strings
230 @param hvparams: hypervisor parameter
231 @return: list of tuples (name, id, memory, vcpus, stat, times)
234 raise NotImplementedError
236 def GetNodeInfo(self, hvparams=None):
237 """Return information about the node.
239 @type hvparams: dict of strings
240 @param hvparams: hypervisor parameters
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
252 raise NotImplementedError
255 def GetInstanceConsole(cls, instance, primary_node, hvparams, beparams):
256 """Return information for connecting to the console of an instance.
259 raise NotImplementedError
262 def GetAncillaryFiles(cls):
263 """Return a list of ancillary files to be copied to all nodes as ancillary
266 @rtype: (list of absolute paths, list of absolute paths)
267 @return: (all files, optional files)
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"
275 return (cls.ANCILLARY_FILES, cls.ANCILLARY_FILES_OPT)
277 def Verify(self, hvparams=None):
278 """Verify the hypervisor.
280 @type hvparams: dict of strings
281 @param hvparams: hypervisor parameters to be verified against
283 @return: Problem description if something is wrong, C{None} otherwise
286 raise NotImplementedError
288 def MigrationInfo(self, instance): # pylint: disable=R0201,W0613
289 """Get instance information to perform a migration.
291 By default assume no information is needed.
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
301 def AcceptInstance(self, instance, info, target):
302 """Prepare to accept an instance.
304 By default assume no preparation is needed.
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
311 @param target: target host (usually ip), on this node
316 def BalloonInstanceMemory(self, instance, mem):
317 """Balloon an instance memory to a certain value.
319 @type instance: L{objects.Instance}
320 @param instance: instance to be accepted
322 @param mem: actual memory size to use for instance runtime
325 raise NotImplementedError
327 def FinalizeMigrationDst(self, instance, info, success):
328 """Finalize the instance migration on the target node.
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
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
343 def MigrateInstance(self, cluster_name, instance, target, live):
344 """Migrate an instance.
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
351 @param target: hostname (usually ip) of the target node
353 @param live: whether to do a live or non-live migration
356 raise NotImplementedError
358 def FinalizeMigrationSource(self, instance, success, live):
359 """Finalize the instance migration on the source node.
361 @type instance: L{objects.Instance}
362 @param instance: the instance that was migrated
364 @param success: whether the migration succeeded or not
366 @param live: whether the user requested a live migration or not
371 def GetMigrationStatus(self, instance):
372 """Get the migration status
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
382 raise NotImplementedError
384 def _InstanceStartupMemory(self, instance, hvparams=None):
385 """Get the correct startup memory for an instance
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.
391 @type instance: L{objects.Instance}
392 @param instance: the instance that is being started
394 @return: memory the instance should be started with
397 free_memory = self.GetNodeInfo(hvparams=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)
403 def CheckParameterSyntax(cls, hvparams):
404 """Check the given parameters for validity.
406 This should check the passed set of parameters for
407 validity. Classes should extend, not replace, this function.
410 @param hvparams: dictionary with parameter names/value
411 @raise errors.HypervisorError: when a parameter is not valid
415 if key not in cls.PARAMETERS:
416 raise errors.HypervisorError("Parameter '%s' is not supported" % key)
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:
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))
434 def ValidateParameters(cls, hvparams):
435 """Check the given parameters for validity.
437 This should check the passed set of parameters for
438 validity. Classes should extend, not replace, this function.
441 @param hvparams: dictionary with parameter names/value
442 @raise errors.HypervisorError: when a parameter is not valid
445 for name, (required, _, _, check_fn, errstr) in cls.PARAMETERS.items():
446 value = hvparams[name]
447 if not required and not value:
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))
455 def PowercycleNode(cls, hvparams=None):
456 """Hard powercycle a node using hypervisor specific methods.
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.
462 @type hvparams: dict of strings
463 @param hvparams: hypervisor params to be used on this node
466 raise NotImplementedError
469 def GetLinuxNodeInfo():
470 """For Linux systems, return actual OS information.
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
478 @return: a dict with the following keys (memory values in MiB):
479 - memory_total: the total memory size on the node
480 - memory_free: the available memory on the node for instances
481 - memory_dom0: the memory used by the node itself, if available
482 - cpu_total: total number of CPUs
483 - cpu_dom0: number of CPUs used by the node OS
484 - cpu_nodes: number of NUMA domains
485 - cpu_sockets: number of physical CPU sockets
489 data = utils.ReadFile("/proc/meminfo").splitlines()
490 except EnvironmentError, err:
491 raise errors.HypervisorError("Failed to list node info: %s" % (err,))
497 splitfields = line.split(":", 1)
499 if len(splitfields) > 1:
500 key = splitfields[0].strip()
501 val = splitfields[1].strip()
502 if key == "MemTotal":
503 result["memory_total"] = int(val.split()[0]) / 1024
504 elif key in ("MemFree", "Buffers", "Cached"):
505 sum_free += int(val.split()[0]) / 1024
506 elif key == "Active":
507 result["memory_dom0"] = int(val.split()[0]) / 1024
508 except (ValueError, TypeError), err:
509 raise errors.HypervisorError("Failed to compute memory usage: %s" %
511 result["memory_free"] = sum_free
515 fh = open("/proc/cpuinfo")
517 cpu_total = len(re.findall("(?m)^processor\s*:\s*[0-9]+\s*$",
521 except EnvironmentError, err:
522 raise errors.HypervisorError("Failed to list node info: %s" % (err,))
523 result["cpu_total"] = cpu_total
524 # We assume that the node OS can access all the CPUs
525 result["cpu_dom0"] = cpu_total
526 # FIXME: export correct data here
527 result["cpu_nodes"] = 1
528 result["cpu_sockets"] = 1
533 def LinuxPowercycle(cls):
534 """Linux-specific powercycle method.
538 fd = os.open("/proc/sysrq-trigger", os.O_WRONLY)
544 logging.exception("Can't open the sysrq-trigger file")
545 result = utils.RunCmd(["reboot", "-n", "-f"])
547 logging.error("Can't run shutdown: %s", result.output)
550 def _FormatVerifyResults(msgs):
551 """Formats the verification results, given a list of errors.
553 @param msgs: list of errors, possibly empty
554 @return: overall problem description if something is wrong,
559 return "; ".join(msgs)