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"]
43 class ConfigObject(object):
44 """A generic config object.
46 It has the following properties:
48 - provides somewhat safe recursive unpickling and pickling for its classes
49 - unset attributes which are defined in slots are always returned
50 as None instead of raising an error
52 Classes derived from this must always declare __slots__ (we use many
53 config objects and the memory reduction is useful)
58 def __init__(self, **kwargs):
59 for k, v in kwargs.iteritems():
63 def __getattr__(self, name):
64 if name not in self.__slots__:
65 raise AttributeError("Invalid object attribute %s.%s" %
66 (type(self).__name__, name))
69 def __setitem__(self, key, value):
70 if key not in self.__slots__:
72 setattr(self, key, value)
74 def __getstate__(self):
76 for name in self.__slots__:
77 if hasattr(self, name):
78 state[name] = getattr(self, name)
81 def __setstate__(self, state):
83 if name in self.__slots__:
84 setattr(self, name, state[name])
87 """Convert to a dict holding only standard python types.
89 The generic routine just dumps all of this object's attributes in
90 a dict. It does not work if the class has children who are
91 ConfigObjects themselves (e.g. the nics list in an Instance), in
92 which case the object should subclass the function in order to
93 make sure all objects returned are only standard python types.
96 return dict([(k, getattr(self, k, None)) for k in self.__slots__])
99 def FromDict(cls, val):
100 """Create an object from a dictionary.
102 This generic routine takes a dict, instantiates a new instance of
103 the given class, and sets attributes based on the dict content.
105 As for `ToDict`, this does not work if the class has children
106 who are ConfigObjects themselves (e.g. the nics list in an
107 Instance), in which case the object should subclass the function
108 and alter the objects.
111 if not isinstance(val, dict):
112 raise errors.ConfigurationError("Invalid object passed to FromDict:"
113 " expected dict, got %s" % type(val))
114 val_str = dict([(str(k), v) for k, v in val.iteritems()])
119 def _ContainerToDicts(container):
120 """Convert the elements of a container to standard python types.
122 This method converts a container with elements derived from
123 ConfigData to standard python types. If the container is a dict,
124 we don't touch the keys, only the values.
127 if isinstance(container, dict):
128 ret = dict([(k, v.ToDict()) for k, v in container.iteritems()])
129 elif isinstance(container, (list, tuple, set, frozenset)):
130 ret = [elem.ToDict() for elem in container]
132 raise TypeError("Invalid type %s passed to _ContainerToDicts" %
137 def _ContainerFromDicts(source, c_type, e_type):
138 """Convert a container from standard python types.
140 This method converts a container with standard python types to
141 ConfigData objects. If the container is a dict, we don't touch the
142 keys, only the values.
145 if not isinstance(c_type, type):
146 raise TypeError("Container type %s passed to _ContainerFromDicts is"
147 " not a type" % type(c_type))
149 ret = dict([(k, e_type.FromDict(v)) for k, v in source.iteritems()])
150 elif c_type in (list, tuple, set, frozenset):
151 ret = c_type([e_type.FromDict(elem) for elem in source])
153 raise TypeError("Invalid container type %s passed to"
154 " _ContainerFromDicts" % c_type)
158 """Makes a deep copy of the current object and its children.
161 dict_form = self.ToDict()
162 clone_obj = self.__class__.FromDict(dict_form)
166 """Implement __repr__ for ConfigObjects."""
167 return repr(self.ToDict())
169 def UpgradeConfig(self):
170 """Fill defaults for missing configuration values.
172 This method will be called at object init time, and its implementation will
179 class TaggableObject(ConfigObject):
180 """An generic class supporting tags.
183 __slots__ = ConfigObject.__slots__ + ["tags"]
186 def ValidateTag(tag):
187 """Check if a tag is valid.
189 If the tag is invalid, an errors.TagError will be raised. The
190 function has no return value.
193 if not isinstance(tag, basestring):
194 raise errors.TagError("Invalid tag type (not a string)")
195 if len(tag) > constants.MAX_TAG_LEN:
196 raise errors.TagError("Tag too long (>%d characters)" %
197 constants.MAX_TAG_LEN)
199 raise errors.TagError("Tags cannot be empty")
200 if not re.match("^[\w.+*/:-]+$", tag):
201 raise errors.TagError("Tag contains invalid characters")
204 """Return the tags list.
207 tags = getattr(self, "tags", None)
209 tags = self.tags = set()
212 def AddTag(self, tag):
216 self.ValidateTag(tag)
217 tags = self.GetTags()
218 if len(tags) >= constants.MAX_TAGS_PER_OBJ:
219 raise errors.TagError("Too many tags")
220 self.GetTags().add(tag)
222 def RemoveTag(self, tag):
226 self.ValidateTag(tag)
227 tags = self.GetTags()
231 raise errors.TagError("Tag not found")
234 """Taggable-object-specific conversion to standard python types.
236 This replaces the tags set with a list.
239 bo = super(TaggableObject, self).ToDict()
241 tags = bo.get("tags", None)
242 if isinstance(tags, set):
243 bo["tags"] = list(tags)
247 def FromDict(cls, val):
248 """Custom function for instances.
251 obj = super(TaggableObject, cls).FromDict(val)
252 if hasattr(obj, "tags") and isinstance(obj.tags, list):
253 obj.tags = set(obj.tags)
257 class ConfigData(ConfigObject):
258 """Top-level config object."""
259 __slots__ = ["version", "cluster", "nodes", "instances", "serial_no"]
262 """Custom function for top-level config data.
264 This just replaces the list of instances, nodes and the cluster
265 with standard python types.
268 mydict = super(ConfigData, self).ToDict()
269 mydict["cluster"] = mydict["cluster"].ToDict()
270 for key in "nodes", "instances":
271 mydict[key] = self._ContainerToDicts(mydict[key])
276 def FromDict(cls, val):
277 """Custom function for top-level config data
280 obj = super(ConfigData, cls).FromDict(val)
281 obj.cluster = Cluster.FromDict(obj.cluster)
282 obj.nodes = cls._ContainerFromDicts(obj.nodes, dict, Node)
283 obj.instances = cls._ContainerFromDicts(obj.instances, dict, Instance)
287 class NIC(ConfigObject):
288 """Config object representing a network card."""
289 __slots__ = ["mac", "ip", "bridge"]
292 class Disk(ConfigObject):
293 """Config object representing a block device."""
294 __slots__ = ["dev_type", "logical_id", "physical_id",
295 "children", "iv_name", "size", "mode"]
297 def CreateOnSecondary(self):
298 """Test if this device needs to be created on a secondary node."""
299 return self.dev_type in (constants.LD_DRBD8, constants.LD_LV)
301 def AssembleOnSecondary(self):
302 """Test if this device needs to be assembled on a secondary node."""
303 return self.dev_type in (constants.LD_DRBD8, constants.LD_LV)
305 def OpenOnSecondary(self):
306 """Test if this device needs to be opened on a secondary node."""
307 return self.dev_type in (constants.LD_LV,)
309 def StaticDevPath(self):
310 """Return the device path if this device type has a static one.
312 Some devices (LVM for example) live always at the same /dev/ path,
313 irrespective of their status. For such devices, we return this
314 path, for others we return None.
317 if self.dev_type == constants.LD_LV:
318 return "/dev/%s/%s" % (self.logical_id[0], self.logical_id[1])
321 def ChildrenNeeded(self):
322 """Compute the needed number of children for activation.
324 This method will return either -1 (all children) or a positive
325 number denoting the minimum number of children needed for
326 activation (only mirrored devices will usually return >=0).
328 Currently, only DRBD8 supports diskless activation (therefore we
329 return 0), for all other we keep the previous semantics and return
333 if self.dev_type == constants.LD_DRBD8:
337 def GetNodes(self, node):
338 """This function returns the nodes this device lives on.
340 Given the node on which the parent of the device lives on (or, in
341 case of a top-level device, the primary node of the devices'
342 instance), this function will return a list of nodes on which this
343 devices needs to (or can) be assembled.
346 if self.dev_type in [constants.LD_LV, constants.LD_FILE]:
348 elif self.dev_type in constants.LDS_DRBD:
349 result = [self.logical_id[0], self.logical_id[1]]
350 if node not in result:
351 raise errors.ConfigurationError("DRBD device passed unknown node")
353 raise errors.ProgrammerError("Unhandled device type %s" % self.dev_type)
356 def ComputeNodeTree(self, parent_node):
357 """Compute the node/disk tree for this disk and its children.
359 This method, given the node on which the parent disk lives, will
360 return the list of all (node, disk) pairs which describe the disk
361 tree in the most compact way. For example, a drbd/lvm stack
362 will be returned as (primary_node, drbd) and (secondary_node, drbd)
363 which represents all the top-level devices on the nodes.
366 my_nodes = self.GetNodes(parent_node)
367 result = [(node, self) for node in my_nodes]
368 if not self.children:
371 for node in my_nodes:
372 for child in self.children:
373 child_result = child.ComputeNodeTree(node)
374 if len(child_result) == 1:
375 # child (and all its descendants) is simple, doesn't split
376 # over multiple hosts, so we don't need to describe it, our
377 # own entry for this node describes it completely
380 # check if child nodes differ from my nodes; note that
381 # subdisk can differ from the child itself, and be instead
382 # one of its descendants
383 for subnode, subdisk in child_result:
384 if subnode not in my_nodes:
385 result.append((subnode, subdisk))
386 # otherwise child is under our own node, so we ignore this
387 # entry (but probably the other results in the list will
391 def RecordGrow(self, amount):
392 """Update the size of this disk after growth.
394 This method recurses over the disks's children and updates their
395 size correspondigly. The method needs to be kept in sync with the
396 actual algorithms from bdev.
399 if self.dev_type == constants.LD_LV:
401 elif self.dev_type == constants.LD_DRBD8:
403 self.children[0].RecordGrow(amount)
406 raise errors.ProgrammerError("Disk.RecordGrow called for unsupported"
407 " disk type %s" % self.dev_type)
410 """Sets recursively the size to zero for the disk and its children.
414 for child in self.children:
418 def SetPhysicalID(self, target_node, nodes_ip):
419 """Convert the logical ID to the physical ID.
421 This is used only for drbd, which needs ip/port configuration.
423 The routine descends down and updates its children also, because
424 this helps when the only the top device is passed to the remote
428 - target_node: the node we wish to configure for
429 - nodes_ip: a mapping of node name to ip
431 The target_node must exist in in nodes_ip, and must be one of the
432 nodes in the logical ID for each of the DRBD devices encountered
437 for child in self.children:
438 child.SetPhysicalID(target_node, nodes_ip)
440 if self.logical_id is None and self.physical_id is not None:
442 if self.dev_type in constants.LDS_DRBD:
443 pnode, snode, port, pminor, sminor, secret = self.logical_id
444 if target_node not in (pnode, snode):
445 raise errors.ConfigurationError("DRBD device not knowing node %s" %
447 pnode_ip = nodes_ip.get(pnode, None)
448 snode_ip = nodes_ip.get(snode, None)
449 if pnode_ip is None or snode_ip is None:
450 raise errors.ConfigurationError("Can't find primary or secondary node"
451 " for %s" % str(self))
452 p_data = (pnode_ip, port)
453 s_data = (snode_ip, port)
454 if pnode == target_node:
455 self.physical_id = p_data + s_data + (pminor, secret)
456 else: # it must be secondary, we tested above
457 self.physical_id = s_data + p_data + (sminor, secret)
459 self.physical_id = self.logical_id
463 """Disk-specific conversion to standard python types.
465 This replaces the children lists of objects with lists of
466 standard python types.
469 bo = super(Disk, self).ToDict()
471 for attr in ("children",):
472 alist = bo.get(attr, None)
474 bo[attr] = self._ContainerToDicts(alist)
478 def FromDict(cls, val):
479 """Custom function for Disks
482 obj = super(Disk, cls).FromDict(val)
484 obj.children = cls._ContainerFromDicts(obj.children, list, Disk)
485 if obj.logical_id and isinstance(obj.logical_id, list):
486 obj.logical_id = tuple(obj.logical_id)
487 if obj.physical_id and isinstance(obj.physical_id, list):
488 obj.physical_id = tuple(obj.physical_id)
489 if obj.dev_type in constants.LDS_DRBD:
490 # we need a tuple of length six here
491 if len(obj.logical_id) < 6:
492 obj.logical_id += (None,) * (6 - len(obj.logical_id))
496 """Custom str() formatter for disks.
499 if self.dev_type == constants.LD_LV:
500 val = "<LogicalVolume(/dev/%s/%s" % self.logical_id
501 elif self.dev_type in constants.LDS_DRBD:
502 node_a, node_b, port, minor_a, minor_b = self.logical_id[:5]
504 if self.physical_id is None:
507 phy = ("configured as %s:%s %s:%s" %
508 (self.physical_id[0], self.physical_id[1],
509 self.physical_id[2], self.physical_id[3]))
511 val += ("hosts=%s/%d-%s/%d, port=%s, %s, " %
512 (node_a, minor_a, node_b, minor_b, port, phy))
513 if self.children and self.children.count(None) == 0:
514 val += "backend=%s, metadev=%s" % (self.children[0], self.children[1])
516 val += "no local storage"
518 val = ("<Disk(type=%s, logical_id=%s, physical_id=%s, children=%s" %
519 (self.dev_type, self.logical_id, self.physical_id, self.children))
520 if self.iv_name is None:
521 val += ", not visible"
523 val += ", visible as /dev/%s" % self.iv_name
524 if isinstance(self.size, int):
525 val += ", size=%dm)>" % self.size
527 val += ", size='%s')>" % (self.size,)
531 """Checks that this disk is correctly configured.
535 if self.mode not in constants.DISK_ACCESS_SET:
536 all_errors.append("Disk access mode '%s' is invalid" % (self.mode, ))
540 class Instance(TaggableObject):
541 """Config object representing an instance."""
542 __slots__ = TaggableObject.__slots__ + [
557 def _ComputeSecondaryNodes(self):
558 """Compute the list of secondary nodes.
560 This is a simple wrapper over _ComputeAllNodes.
563 all_nodes = set(self._ComputeAllNodes())
564 all_nodes.discard(self.primary_node)
565 return tuple(all_nodes)
567 secondary_nodes = property(_ComputeSecondaryNodes, None, None,
568 "List of secondary nodes")
570 def _ComputeAllNodes(self):
571 """Compute the list of all nodes.
573 Since the data is already there (in the drbd disks), keeping it as
574 a separate normal attribute is redundant and if not properly
575 synchronised can cause problems. Thus it's better to compute it
579 def _Helper(nodes, device):
580 """Recursively computes nodes given a top device."""
581 if device.dev_type in constants.LDS_DRBD:
582 nodea, nodeb = device.logical_id[:2]
586 for child in device.children:
587 _Helper(nodes, child)
590 all_nodes.add(self.primary_node)
591 for device in self.disks:
592 _Helper(all_nodes, device)
593 return tuple(all_nodes)
595 all_nodes = property(_ComputeAllNodes, None, None,
596 "List of all nodes of the instance")
598 def MapLVsByNode(self, lvmap=None, devs=None, node=None):
599 """Provide a mapping of nodes to LVs this instance owns.
601 This function figures out what logical volumes should belong on
602 which nodes, recursing through a device tree.
604 @param lvmap: optional dictionary to receive the
605 'node' : ['lv', ...] data.
607 @return: None if lvmap arg is given, otherwise, a dictionary
608 of the form { 'nodename' : ['volume1', 'volume2', ...], ... }
612 node = self.primary_node
615 lvmap = { node : [] }
618 if not node in lvmap:
626 if dev.dev_type == constants.LD_LV:
627 lvmap[node].append(dev.logical_id[1])
629 elif dev.dev_type in constants.LDS_DRBD:
631 self.MapLVsByNode(lvmap, dev.children, dev.logical_id[0])
632 self.MapLVsByNode(lvmap, dev.children, dev.logical_id[1])
635 self.MapLVsByNode(lvmap, dev.children, node)
639 def FindDisk(self, idx):
640 """Find a disk given having a specified index.
642 This is just a wrapper that does validation of the index.
645 @param idx: the disk index
647 @return: the corresponding disk
648 @raise errors.OpPrereqError: when the given index is not valid
653 return self.disks[idx]
654 except ValueError, err:
655 raise errors.OpPrereqError("Invalid disk index: '%s'" % str(err))
657 raise errors.OpPrereqError("Invalid disk index: %d (instace has disks"
658 " 0 to %d" % (idx, len(self.disks)))
661 """Instance-specific conversion to standard python types.
663 This replaces the children lists of objects with lists of standard
667 bo = super(Instance, self).ToDict()
669 for attr in "nics", "disks":
670 alist = bo.get(attr, None)
672 nlist = self._ContainerToDicts(alist)
679 def FromDict(cls, val):
680 """Custom function for instances.
683 obj = super(Instance, cls).FromDict(val)
684 obj.nics = cls._ContainerFromDicts(obj.nics, list, NIC)
685 obj.disks = cls._ContainerFromDicts(obj.disks, list, Disk)
689 class OS(ConfigObject):
690 """Config object representing an operating system."""
703 def FromInvalidOS(cls, err):
704 """Create an OS from an InvalidOS error.
706 This routine knows how to convert an InvalidOS error to an OS
707 object representing the broken OS with a meaningful error message.
710 if not isinstance(err, errors.InvalidOS):
711 raise errors.ProgrammerError("Trying to initialize an OS from an"
712 " invalid object of type %s" % type(err))
714 return cls(name=err.args[0], path=err.args[1], status=err.args[2])
716 def __nonzero__(self):
717 return self.status == constants.OS_VALID_STATUS
719 __bool__ = __nonzero__
722 class Node(TaggableObject):
723 """Config object representing a node."""
724 __slots__ = TaggableObject.__slots__ + [
735 class Cluster(TaggableObject):
736 """Config object representing the cluster."""
737 __slots__ = TaggableObject.__slots__ + [
745 "default_hypervisor",
751 "enabled_hypervisors",
754 "candidate_pool_size",
758 def UpgradeConfig(self):
759 """Fill defaults for missing configuration values.
762 if self.modify_etc_hosts is None:
763 self.modify_etc_hosts = True
766 """Custom function for cluster.
769 mydict = super(Cluster, self).ToDict()
770 mydict["tcpudp_port_pool"] = list(self.tcpudp_port_pool)
774 def FromDict(cls, val):
775 """Custom function for cluster.
778 obj = super(Cluster, cls).FromDict(val)
779 if not isinstance(obj.tcpudp_port_pool, set):
780 obj.tcpudp_port_pool = set(obj.tcpudp_port_pool)
784 def FillDict(defaults_dict, custom_dict):
785 """Basic function to apply settings on top a default dict.
787 @type defaults_dict: dict
788 @param defaults_dict: dictionary holding the default values
789 @type custom_dict: dict
790 @param custom_dict: dictionary holding customized value
792 @return: dict with the 'full' values
795 ret_dict = copy.deepcopy(defaults_dict)
796 ret_dict.update(custom_dict)
799 def FillHV(self, instance):
800 """Fill an instance's hvparams dict.
802 @type instance: L{objects.Instance}
803 @param instance: the instance parameter to fill
805 @return: a copy of the instance's hvparams with missing keys filled from
809 return self.FillDict(self.hvparams.get(instance.hypervisor, {}),
812 def FillBE(self, instance):
813 """Fill an instance's beparams dict.
815 @type instance: L{objects.Instance}
816 @param instance: the instance parameter to fill
818 @return: a copy of the instance's beparams with missing keys filled from
822 return self.FillDict(self.beparams.get(constants.BEGR_DEFAULT, {}),
826 class SerializableConfigParser(ConfigParser.SafeConfigParser):
827 """Simple wrapper over ConfigParse that allows serialization.
829 This class is basically ConfigParser.SafeConfigParser with two
830 additional methods that allow it to serialize/unserialize to/from a
835 """Dump this instance and return the string representation."""
838 return buf.getvalue()
842 """Load data from a string."""
844 cfp = SerializableConfigParser()