4 # Copyright (C) 2006, 2007 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 """Transportable objects for Ganeti.
24 This module provides small, mostly data-only objects which are safe to
25 pass to and from external parties.
33 from cStringIO import StringIO
35 from ganeti import errors
36 from ganeti import constants
39 __all__ = ["ConfigObject", "ConfigData", "NIC", "Disk", "Instance",
40 "OS", "Node", "Cluster", "FillDict"]
42 def FillDict(defaults_dict, custom_dict):
43 """Basic function to apply settings on top a default dict.
45 @type defaults_dict: dict
46 @param defaults_dict: dictionary holding the default values
47 @type custom_dict: dict
48 @param custom_dict: dictionary holding customized value
50 @return: dict with the 'full' values
53 ret_dict = copy.deepcopy(defaults_dict)
54 ret_dict.update(custom_dict)
58 def UpgradeGroupedParams(target, defaults):
59 """Update all groups for the target parameter.
61 @type target: dict of dicts
62 @param target: {group: {parameter: value}}
64 @param defaults: default parameter values
68 target = {constants.PP_DEFAULT: defaults}
71 target[group] = FillDict(defaults, target[group])
75 class ConfigObject(object):
76 """A generic config object.
78 It has the following properties:
80 - provides somewhat safe recursive unpickling and pickling for its classes
81 - unset attributes which are defined in slots are always returned
82 as None instead of raising an error
84 Classes derived from this must always declare __slots__ (we use many
85 config objects and the memory reduction is useful)
90 def __init__(self, **kwargs):
91 for k, v in kwargs.iteritems():
95 def __getattr__(self, name):
96 if name not in self.__slots__:
97 raise AttributeError("Invalid object attribute %s.%s" %
98 (type(self).__name__, name))
101 def __setitem__(self, key, value):
102 if key not in self.__slots__:
104 setattr(self, key, value)
106 def __getstate__(self):
108 for name in self.__slots__:
109 if hasattr(self, name):
110 state[name] = getattr(self, name)
113 def __setstate__(self, state):
115 if name in self.__slots__:
116 setattr(self, name, state[name])
119 """Convert to a dict holding only standard python types.
121 The generic routine just dumps all of this object's attributes in
122 a dict. It does not work if the class has children who are
123 ConfigObjects themselves (e.g. the nics list in an Instance), in
124 which case the object should subclass the function in order to
125 make sure all objects returned are only standard python types.
128 return dict([(k, getattr(self, k, None)) for k in self.__slots__])
131 def FromDict(cls, val):
132 """Create an object from a dictionary.
134 This generic routine takes a dict, instantiates a new instance of
135 the given class, and sets attributes based on the dict content.
137 As for `ToDict`, this does not work if the class has children
138 who are ConfigObjects themselves (e.g. the nics list in an
139 Instance), in which case the object should subclass the function
140 and alter the objects.
143 if not isinstance(val, dict):
144 raise errors.ConfigurationError("Invalid object passed to FromDict:"
145 " expected dict, got %s" % type(val))
146 val_str = dict([(str(k), v) for k, v in val.iteritems()])
151 def _ContainerToDicts(container):
152 """Convert the elements of a container to standard python types.
154 This method converts a container with elements derived from
155 ConfigData to standard python types. If the container is a dict,
156 we don't touch the keys, only the values.
159 if isinstance(container, dict):
160 ret = dict([(k, v.ToDict()) for k, v in container.iteritems()])
161 elif isinstance(container, (list, tuple, set, frozenset)):
162 ret = [elem.ToDict() for elem in container]
164 raise TypeError("Invalid type %s passed to _ContainerToDicts" %
169 def _ContainerFromDicts(source, c_type, e_type):
170 """Convert a container from standard python types.
172 This method converts a container with standard python types to
173 ConfigData objects. If the container is a dict, we don't touch the
174 keys, only the values.
177 if not isinstance(c_type, type):
178 raise TypeError("Container type %s passed to _ContainerFromDicts is"
179 " not a type" % type(c_type))
181 ret = dict([(k, e_type.FromDict(v)) for k, v in source.iteritems()])
182 elif c_type in (list, tuple, set, frozenset):
183 ret = c_type([e_type.FromDict(elem) for elem in source])
185 raise TypeError("Invalid container type %s passed to"
186 " _ContainerFromDicts" % c_type)
190 """Implement __repr__ for ConfigObjects."""
191 return repr(self.ToDict())
193 def UpgradeConfig(self):
194 """Fill defaults for missing configuration values.
196 This method will be called at object init time, and its implementation will
203 class TaggableObject(ConfigObject):
204 """An generic class supporting tags.
207 __slots__ = ConfigObject.__slots__ + ["tags"]
210 def ValidateTag(tag):
211 """Check if a tag is valid.
213 If the tag is invalid, an errors.TagError will be raised. The
214 function has no return value.
217 if not isinstance(tag, basestring):
218 raise errors.TagError("Invalid tag type (not a string)")
219 if len(tag) > constants.MAX_TAG_LEN:
220 raise errors.TagError("Tag too long (>%d characters)" %
221 constants.MAX_TAG_LEN)
223 raise errors.TagError("Tags cannot be empty")
224 if not re.match("^[\w.+*/:-]+$", tag):
225 raise errors.TagError("Tag contains invalid characters")
228 """Return the tags list.
231 tags = getattr(self, "tags", None)
233 tags = self.tags = set()
236 def AddTag(self, tag):
240 self.ValidateTag(tag)
241 tags = self.GetTags()
242 if len(tags) >= constants.MAX_TAGS_PER_OBJ:
243 raise errors.TagError("Too many tags")
244 self.GetTags().add(tag)
246 def RemoveTag(self, tag):
250 self.ValidateTag(tag)
251 tags = self.GetTags()
255 raise errors.TagError("Tag not found")
258 """Taggable-object-specific conversion to standard python types.
260 This replaces the tags set with a list.
263 bo = super(TaggableObject, self).ToDict()
265 tags = bo.get("tags", None)
266 if isinstance(tags, set):
267 bo["tags"] = list(tags)
271 def FromDict(cls, val):
272 """Custom function for instances.
275 obj = super(TaggableObject, cls).FromDict(val)
276 if hasattr(obj, "tags") and isinstance(obj.tags, list):
277 obj.tags = set(obj.tags)
281 class ConfigData(ConfigObject):
282 """Top-level config object."""
283 __slots__ = ["version", "cluster", "nodes", "instances", "serial_no"]
286 """Custom function for top-level config data.
288 This just replaces the list of instances, nodes and the cluster
289 with standard python types.
292 mydict = super(ConfigData, self).ToDict()
293 mydict["cluster"] = mydict["cluster"].ToDict()
294 for key in "nodes", "instances":
295 mydict[key] = self._ContainerToDicts(mydict[key])
300 def FromDict(cls, val):
301 """Custom function for top-level config data
304 obj = super(ConfigData, cls).FromDict(val)
305 obj.cluster = Cluster.FromDict(obj.cluster)
306 obj.nodes = cls._ContainerFromDicts(obj.nodes, dict, Node)
307 obj.instances = cls._ContainerFromDicts(obj.instances, dict, Instance)
311 class NIC(ConfigObject):
312 """Config object representing a network card."""
313 __slots__ = ["mac", "ip", "bridge"]
316 def CheckParameterSyntax(cls, nicparams):
317 """Check the given parameters for validity.
319 @type nicparams: dict
320 @param nicparams: dictionary with parameter names/value
321 @raise errors.ConfigurationError: when a parameter is not valid
324 if nicparams[constants.NIC_MODE] not in constants.NIC_VALID_MODES:
325 err = "Invalid nic mode: %s" % nicparams[constants.NIC_MODE]
326 raise errors.ConfigurationError(err)
328 if (nicparams[constants.NIC_MODE] is constants.NIC_MODE_BRIDGED and
329 not nicparams[constants.NIC_LINK]):
330 err = "Missing bridged nic link"
331 raise errors.ConfigurationError(err)
334 class Disk(ConfigObject):
335 """Config object representing a block device."""
336 __slots__ = ["dev_type", "logical_id", "physical_id",
337 "children", "iv_name", "size", "mode"]
339 def CreateOnSecondary(self):
340 """Test if this device needs to be created on a secondary node."""
341 return self.dev_type in (constants.LD_DRBD8, constants.LD_LV)
343 def AssembleOnSecondary(self):
344 """Test if this device needs to be assembled on a secondary node."""
345 return self.dev_type in (constants.LD_DRBD8, constants.LD_LV)
347 def OpenOnSecondary(self):
348 """Test if this device needs to be opened on a secondary node."""
349 return self.dev_type in (constants.LD_LV,)
351 def StaticDevPath(self):
352 """Return the device path if this device type has a static one.
354 Some devices (LVM for example) live always at the same /dev/ path,
355 irrespective of their status. For such devices, we return this
356 path, for others we return None.
359 if self.dev_type == constants.LD_LV:
360 return "/dev/%s/%s" % (self.logical_id[0], self.logical_id[1])
363 def ChildrenNeeded(self):
364 """Compute the needed number of children for activation.
366 This method will return either -1 (all children) or a positive
367 number denoting the minimum number of children needed for
368 activation (only mirrored devices will usually return >=0).
370 Currently, only DRBD8 supports diskless activation (therefore we
371 return 0), for all other we keep the previous semantics and return
375 if self.dev_type == constants.LD_DRBD8:
379 def GetNodes(self, node):
380 """This function returns the nodes this device lives on.
382 Given the node on which the parent of the device lives on (or, in
383 case of a top-level device, the primary node of the devices'
384 instance), this function will return a list of nodes on which this
385 devices needs to (or can) be assembled.
388 if self.dev_type in [constants.LD_LV, constants.LD_FILE]:
390 elif self.dev_type in constants.LDS_DRBD:
391 result = [self.logical_id[0], self.logical_id[1]]
392 if node not in result:
393 raise errors.ConfigurationError("DRBD device passed unknown node")
395 raise errors.ProgrammerError("Unhandled device type %s" % self.dev_type)
398 def ComputeNodeTree(self, parent_node):
399 """Compute the node/disk tree for this disk and its children.
401 This method, given the node on which the parent disk lives, will
402 return the list of all (node, disk) pairs which describe the disk
403 tree in the most compact way. For example, a drbd/lvm stack
404 will be returned as (primary_node, drbd) and (secondary_node, drbd)
405 which represents all the top-level devices on the nodes.
408 my_nodes = self.GetNodes(parent_node)
409 result = [(node, self) for node in my_nodes]
410 if not self.children:
413 for node in my_nodes:
414 for child in self.children:
415 child_result = child.ComputeNodeTree(node)
416 if len(child_result) == 1:
417 # child (and all its descendants) is simple, doesn't split
418 # over multiple hosts, so we don't need to describe it, our
419 # own entry for this node describes it completely
422 # check if child nodes differ from my nodes; note that
423 # subdisk can differ from the child itself, and be instead
424 # one of its descendants
425 for subnode, subdisk in child_result:
426 if subnode not in my_nodes:
427 result.append((subnode, subdisk))
428 # otherwise child is under our own node, so we ignore this
429 # entry (but probably the other results in the list will
433 def RecordGrow(self, amount):
434 """Update the size of this disk after growth.
436 This method recurses over the disks's children and updates their
437 size correspondigly. The method needs to be kept in sync with the
438 actual algorithms from bdev.
441 if self.dev_type == constants.LD_LV:
443 elif self.dev_type == constants.LD_DRBD8:
445 self.children[0].RecordGrow(amount)
448 raise errors.ProgrammerError("Disk.RecordGrow called for unsupported"
449 " disk type %s" % self.dev_type)
451 def SetPhysicalID(self, target_node, nodes_ip):
452 """Convert the logical ID to the physical ID.
454 This is used only for drbd, which needs ip/port configuration.
456 The routine descends down and updates its children also, because
457 this helps when the only the top device is passed to the remote
461 - target_node: the node we wish to configure for
462 - nodes_ip: a mapping of node name to ip
464 The target_node must exist in in nodes_ip, and must be one of the
465 nodes in the logical ID for each of the DRBD devices encountered
470 for child in self.children:
471 child.SetPhysicalID(target_node, nodes_ip)
473 if self.logical_id is None and self.physical_id is not None:
475 if self.dev_type in constants.LDS_DRBD:
476 pnode, snode, port, pminor, sminor, secret = self.logical_id
477 if target_node not in (pnode, snode):
478 raise errors.ConfigurationError("DRBD device not knowing node %s" %
480 pnode_ip = nodes_ip.get(pnode, None)
481 snode_ip = nodes_ip.get(snode, None)
482 if pnode_ip is None or snode_ip is None:
483 raise errors.ConfigurationError("Can't find primary or secondary node"
484 " for %s" % str(self))
485 p_data = (pnode_ip, port)
486 s_data = (snode_ip, port)
487 if pnode == target_node:
488 self.physical_id = p_data + s_data + (pminor, secret)
489 else: # it must be secondary, we tested above
490 self.physical_id = s_data + p_data + (sminor, secret)
492 self.physical_id = self.logical_id
496 """Disk-specific conversion to standard python types.
498 This replaces the children lists of objects with lists of
499 standard python types.
502 bo = super(Disk, self).ToDict()
504 for attr in ("children",):
505 alist = bo.get(attr, None)
507 bo[attr] = self._ContainerToDicts(alist)
511 def FromDict(cls, val):
512 """Custom function for Disks
515 obj = super(Disk, cls).FromDict(val)
517 obj.children = cls._ContainerFromDicts(obj.children, list, Disk)
518 if obj.logical_id and isinstance(obj.logical_id, list):
519 obj.logical_id = tuple(obj.logical_id)
520 if obj.physical_id and isinstance(obj.physical_id, list):
521 obj.physical_id = tuple(obj.physical_id)
522 if obj.dev_type in constants.LDS_DRBD:
523 # we need a tuple of length six here
524 if len(obj.logical_id) < 6:
525 obj.logical_id += (None,) * (6 - len(obj.logical_id))
529 """Custom str() formatter for disks.
532 if self.dev_type == constants.LD_LV:
533 val = "<LogicalVolume(/dev/%s/%s" % self.logical_id
534 elif self.dev_type in constants.LDS_DRBD:
535 node_a, node_b, port, minor_a, minor_b = self.logical_id[:5]
537 if self.physical_id is None:
540 phy = ("configured as %s:%s %s:%s" %
541 (self.physical_id[0], self.physical_id[1],
542 self.physical_id[2], self.physical_id[3]))
544 val += ("hosts=%s/%d-%s/%d, port=%s, %s, " %
545 (node_a, minor_a, node_b, minor_b, port, phy))
546 if self.children and self.children.count(None) == 0:
547 val += "backend=%s, metadev=%s" % (self.children[0], self.children[1])
549 val += "no local storage"
551 val = ("<Disk(type=%s, logical_id=%s, physical_id=%s, children=%s" %
552 (self.dev_type, self.logical_id, self.physical_id, self.children))
553 if self.iv_name is None:
554 val += ", not visible"
556 val += ", visible as /dev/%s" % self.iv_name
557 if isinstance(self.size, int):
558 val += ", size=%dm)>" % self.size
560 val += ", size='%s')>" % (self.size,)
564 """Checks that this disk is correctly configured.
568 if self.mode not in constants.DISK_ACCESS_SET:
569 errors.append("Disk access mode '%s' is invalid" % (self.mode, ))
573 class Instance(TaggableObject):
574 """Config object representing an instance."""
575 __slots__ = TaggableObject.__slots__ + [
590 def _ComputeSecondaryNodes(self):
591 """Compute the list of secondary nodes.
593 This is a simple wrapper over _ComputeAllNodes.
596 all_nodes = set(self._ComputeAllNodes())
597 all_nodes.discard(self.primary_node)
598 return tuple(all_nodes)
600 secondary_nodes = property(_ComputeSecondaryNodes, None, None,
601 "List of secondary nodes")
603 def _ComputeAllNodes(self):
604 """Compute the list of all nodes.
606 Since the data is already there (in the drbd disks), keeping it as
607 a separate normal attribute is redundant and if not properly
608 synchronised can cause problems. Thus it's better to compute it
612 def _Helper(nodes, device):
613 """Recursively computes nodes given a top device."""
614 if device.dev_type in constants.LDS_DRBD:
615 nodea, nodeb = device.logical_id[:2]
619 for child in device.children:
620 _Helper(nodes, child)
623 all_nodes.add(self.primary_node)
624 for device in self.disks:
625 _Helper(all_nodes, device)
626 return tuple(all_nodes)
628 all_nodes = property(_ComputeAllNodes, None, None,
629 "List of all nodes of the instance")
631 def MapLVsByNode(self, lvmap=None, devs=None, node=None):
632 """Provide a mapping of nodes to LVs this instance owns.
634 This function figures out what logical volumes should belong on
635 which nodes, recursing through a device tree.
637 @param lvmap: optional dictionary to receive the
638 'node' : ['lv', ...] data.
640 @return: None if lvmap arg is given, otherwise, a dictionary
641 of the form { 'nodename' : ['volume1', 'volume2', ...], ... }
645 node = self.primary_node
648 lvmap = { node : [] }
651 if not node in lvmap:
659 if dev.dev_type == constants.LD_LV:
660 lvmap[node].append(dev.logical_id[1])
662 elif dev.dev_type in constants.LDS_DRBD:
664 self.MapLVsByNode(lvmap, dev.children, dev.logical_id[0])
665 self.MapLVsByNode(lvmap, dev.children, dev.logical_id[1])
668 self.MapLVsByNode(lvmap, dev.children, node)
672 def FindDisk(self, idx):
673 """Find a disk given having a specified index.
675 This is just a wrapper that does validation of the index.
678 @param idx: the disk index
680 @return: the corresponding disk
681 @raise errors.OpPrereqError: when the given index is not valid
686 return self.disks[idx]
687 except ValueError, err:
688 raise errors.OpPrereqError("Invalid disk index: '%s'" % str(err))
690 raise errors.OpPrereqError("Invalid disk index: %d (instace has disks"
691 " 0 to %d" % (idx, len(self.disks)))
694 """Instance-specific conversion to standard python types.
696 This replaces the children lists of objects with lists of standard
700 bo = super(Instance, self).ToDict()
702 for attr in "nics", "disks":
703 alist = bo.get(attr, None)
705 nlist = self._ContainerToDicts(alist)
712 def FromDict(cls, val):
713 """Custom function for instances.
716 obj = super(Instance, cls).FromDict(val)
717 obj.nics = cls._ContainerFromDicts(obj.nics, list, NIC)
718 obj.disks = cls._ContainerFromDicts(obj.disks, list, Disk)
722 class OS(ConfigObject):
723 """Config object representing an operating system."""
736 def FromInvalidOS(cls, err):
737 """Create an OS from an InvalidOS error.
739 This routine knows how to convert an InvalidOS error to an OS
740 object representing the broken OS with a meaningful error message.
743 if not isinstance(err, errors.InvalidOS):
744 raise errors.ProgrammerError("Trying to initialize an OS from an"
745 " invalid object of type %s" % type(err))
747 return cls(name=err.args[0], path=err.args[1], status=err.args[2])
749 def __nonzero__(self):
750 return self.status == constants.OS_VALID_STATUS
752 __bool__ = __nonzero__
755 class Node(TaggableObject):
756 """Config object representing a node."""
757 __slots__ = TaggableObject.__slots__ + [
768 class Cluster(TaggableObject):
769 """Config object representing the cluster."""
770 __slots__ = TaggableObject.__slots__ + [
778 "default_hypervisor",
784 "enabled_hypervisors",
788 "candidate_pool_size",
792 def UpgradeConfig(self):
793 """Fill defaults for missing configuration values.
796 if self.hvparams is None:
797 self.hvparams = constants.HVC_DEFAULTS
799 for hypervisor in self.hvparams:
800 self.hvparams[hypervisor] = FillDict(
801 constants.HVC_DEFAULTS[hypervisor], self.hvparams[hypervisor])
803 self.beparams = UpgradeGroupedParams(self.beparams,
804 constants.BEC_DEFAULTS)
805 migrate_default_bridge = not self.nicparams
806 self.nicparams = UpgradeGroupedParams(self.nicparams,
807 constants.NICC_DEFAULTS)
808 if migrate_default_bridge:
809 self.nicparams[constants.PP_DEFAULT][constants.NIC_LINK] = \
812 if self.modify_etc_hosts is None:
813 self.modify_etc_hosts = True
816 """Custom function for cluster.
819 mydict = super(Cluster, self).ToDict()
820 mydict["tcpudp_port_pool"] = list(self.tcpudp_port_pool)
824 def FromDict(cls, val):
825 """Custom function for cluster.
828 obj = super(Cluster, cls).FromDict(val)
829 if not isinstance(obj.tcpudp_port_pool, set):
830 obj.tcpudp_port_pool = set(obj.tcpudp_port_pool)
833 def FillHV(self, instance):
834 """Fill an instance's hvparams dict.
836 @type instance: object
837 @param instance: the instance parameter to fill
839 @return: a copy of the instance's hvparams with missing keys filled from
843 return FillDict(self.hvparams.get(instance.hypervisor, {}),
846 def FillBE(self, instance):
847 """Fill an instance's beparams dict.
849 @type instance: object
850 @param instance: the instance parameter to fill
852 @return: a copy of the instance's beparams with missing keys filled from
856 return FillDict(self.beparams.get(constants.PP_DEFAULT, {}),
860 class SerializableConfigParser(ConfigParser.SafeConfigParser):
861 """Simple wrapper over ConfigParse that allows serialization.
863 This class is basically ConfigParser.SafeConfigParser with two
864 additional methods that allow it to serialize/unserialize to/from a
869 """Dump this instance and return the string representation."""
872 return buf.getvalue()
876 """Load data from a string."""
878 cfp = SerializableConfigParser()