Commit e4376078 authored by Iustin Pop's avatar Iustin Pop
Browse files

Documentation updates for cmdlib.py

This makes cmdlib.py not throw epydoc errors anymore.

Reviewed-by: ultrotter
parent 975e07c6
...@@ -127,27 +127,29 @@ class LogicalUnit(object): ...@@ -127,27 +127,29 @@ class LogicalUnit(object):
LUs which implement this method must also populate the self.needed_locks LUs which implement this method must also populate the self.needed_locks
member, as a dict with lock levels as keys, and a list of needed lock names member, as a dict with lock levels as keys, and a list of needed lock names
as values. Rules: as values. Rules:
- Use an empty dict if you don't need any lock
- If you don't need any lock at a particular level omit that level - use an empty dict if you don't need any lock
- Don't put anything for the BGL level - if you don't need any lock at a particular level omit that level
- If you want all locks at a level use locking.ALL_SET as a value - don't put anything for the BGL level
- if you want all locks at a level use locking.ALL_SET as a value
If you need to share locks (rather than acquire them exclusively) at one If you need to share locks (rather than acquire them exclusively) at one
level you can modify self.share_locks, setting a true value (usually 1) for level you can modify self.share_locks, setting a true value (usually 1) for
that level. By default locks are not shared. that level. By default locks are not shared.
Examples: Examples::
# Acquire all nodes and one instance
self.needed_locks = { # Acquire all nodes and one instance
locking.LEVEL_NODE: locking.ALL_SET, self.needed_locks = {
locking.LEVEL_INSTANCE: ['instance1.example.tld'], locking.LEVEL_NODE: locking.ALL_SET,
} locking.LEVEL_INSTANCE: ['instance1.example.tld'],
# Acquire just two nodes }
self.needed_locks = { # Acquire just two nodes
locking.LEVEL_NODE: ['node1.example.tld', 'node2.example.tld'], self.needed_locks = {
} locking.LEVEL_NODE: ['node1.example.tld', 'node2.example.tld'],
# Acquire no locks }
self.needed_locks = {} # No, you can't leave it to the default value None # Acquire no locks
self.needed_locks = {} # No, you can't leave it to the default value None
""" """
# The implementation of this method is mandatory only if the new LU is # The implementation of this method is mandatory only if the new LU is
...@@ -234,11 +236,14 @@ class LogicalUnit(object): ...@@ -234,11 +236,14 @@ class LogicalUnit(object):
previous result is passed back unchanged but any LU can define it if it previous result is passed back unchanged but any LU can define it if it
wants to use the local cluster hook-scripts somehow. wants to use the local cluster hook-scripts somehow.
Args: @param phase: one of L{constants.HOOKS_PHASE_POST} or
phase: the hooks phase that has just been run L{constants.HOOKS_PHASE_PRE}; it denotes the hooks phase
hooks_results: the results of the multi-node hooks rpc call @param hook_results: the results of the multi-node hooks rpc call
feedback_fn: function to send feedback back to the caller @param feedback_fn: function used send feedback back to the caller
lu_result: the previous result this LU had, or None in the PRE phase. @param lu_result: the previous Exec result this LU had, or None
in the PRE phase
@return: the new Exec result, based on the previous result
and hook results
""" """
return lu_result return lu_result
...@@ -279,10 +284,10 @@ class LogicalUnit(object): ...@@ -279,10 +284,10 @@ class LogicalUnit(object):
In the future it may grow parameters to just lock some instance's nodes, or In the future it may grow parameters to just lock some instance's nodes, or
to just lock primaries or secondary nodes, if needed. to just lock primaries or secondary nodes, if needed.
If should be called in DeclareLocks in a way similar to: If should be called in DeclareLocks in a way similar to::
if level == locking.LEVEL_NODE: if level == locking.LEVEL_NODE:
self._LockInstancesNodes() self._LockInstancesNodes()
@type primary_only: boolean @type primary_only: boolean
@param primary_only: only lock primary nodes of locked instances @param primary_only: only lock primary nodes of locked instances
...@@ -325,8 +330,13 @@ class NoHooksLU(LogicalUnit): ...@@ -325,8 +330,13 @@ class NoHooksLU(LogicalUnit):
def _GetWantedNodes(lu, nodes): def _GetWantedNodes(lu, nodes):
"""Returns list of checked and expanded node names. """Returns list of checked and expanded node names.
Args: @type lu: L{LogicalUnit}
nodes: List of nodes (strings) or None for all @param lu: the logical unit on whose behalf we execute
@type nodes: list
@param nodes: list of node names or None for all nodes
@rtype: list
@return: the list of nodes, sorted
@raise errors.OpProgrammerError: if the nodes parameter is wrong type
""" """
if not isinstance(nodes, list): if not isinstance(nodes, list):
...@@ -349,8 +359,14 @@ def _GetWantedNodes(lu, nodes): ...@@ -349,8 +359,14 @@ def _GetWantedNodes(lu, nodes):
def _GetWantedInstances(lu, instances): def _GetWantedInstances(lu, instances):
"""Returns list of checked and expanded instance names. """Returns list of checked and expanded instance names.
Args: @type lu: L{LogicalUnit}
instances: List of instances (strings) or None for all @param lu: the logical unit on whose behalf we execute
@type instances: list
@param instances: list of instance names or None for all instances
@rtype: list
@return: the list of instances, sorted
@raise errors.OpPrereqError: if the instances parameter is wrong type
@raise errors.OpPrereqError: if any of the passed instances is not found
""" """
if not isinstance(instances, list): if not isinstance(instances, list):
...@@ -391,10 +407,30 @@ def _CheckOutputFields(static, dynamic, selected): ...@@ -391,10 +407,30 @@ def _CheckOutputFields(static, dynamic, selected):
def _BuildInstanceHookEnv(name, primary_node, secondary_nodes, os_type, status, def _BuildInstanceHookEnv(name, primary_node, secondary_nodes, os_type, status,
memory, vcpus, nics): memory, vcpus, nics):
"""Builds instance related env variables for hooks from single variables. """Builds instance related env variables for hooks
This builds the hook environment from individual variables.
@type name: string
@param name: the name of the instance
@type primary_node: string
@param primary_node: the name of the instance's primary node
@type secondary_nodes: list
@param secondary_nodes: list of secondary nodes as strings
@type os_type: string
@param os_type: the name of the instance's OS
@type status: string
@param status: the desired status of the instances
@type memory: string
@param memory: the memory size of the instance
@type vcpus: string
@param vcpus: the count of VCPUs the instance has
@type nics: list
@param nics: list of tuples (ip, bridge, mac) representing
the NICs the instance has
@rtype: dict
@return: the hook environment for this instance
Args:
secondary_nodes: List of secondary nodes as strings
""" """
env = { env = {
"OP_TARGET": name, "OP_TARGET": name,
...@@ -426,9 +462,17 @@ def _BuildInstanceHookEnv(name, primary_node, secondary_nodes, os_type, status, ...@@ -426,9 +462,17 @@ def _BuildInstanceHookEnv(name, primary_node, secondary_nodes, os_type, status,
def _BuildInstanceHookEnvByObject(lu, instance, override=None): def _BuildInstanceHookEnvByObject(lu, instance, override=None):
"""Builds instance related env variables for hooks from an object. """Builds instance related env variables for hooks from an object.
Args: @type lu: L{LogicalUnit}
instance: objects.Instance object of instance @param lu: the logical unit on whose behalf we execute
override: dict of values to override @type instance: L{objects.Instance}
@param instance: the instance for which we should build the
environment
@type override: dict
@param override: dictionary with key/values that will override
our values
@rtype: dict
@return: the hook environment dictionary
""" """
bep = lu.cfg.GetClusterInfo().FillBE(instance) bep = lu.cfg.GetClusterInfo().FillBE(instance)
args = { args = {
...@@ -516,16 +560,22 @@ class LUVerifyCluster(LogicalUnit): ...@@ -516,16 +560,22 @@ class LUVerifyCluster(LogicalUnit):
remote_version, feedback_fn): remote_version, feedback_fn):
"""Run multiple tests against a node. """Run multiple tests against a node.
Test list: Test list::
- compares ganeti version - compares ganeti version
- checks vg existance and size > 20G - checks vg existance and size > 20G
- checks config file checksum - checks config file checksum
- checks ssh to other nodes - checks ssh to other nodes
Args: @type node: string
node: name of the node to check @param node: the name of the node to check
file_list: required list of files @param file_list: required list of files
local_cksum: dictionary of local files and their checksums @param local_cksum: dictionary of local files and their checksums
@type vglist: dict
@param vglist: dictionary of volume group names and their size
@param node_result: the results from the node
@param remote_version: the RPC version from the remote node
@param feedback_fn: function used to accumulate results
""" """
# compares ganeti version # compares ganeti version
...@@ -899,14 +949,18 @@ class LUVerifyCluster(LogicalUnit): ...@@ -899,14 +949,18 @@ class LUVerifyCluster(LogicalUnit):
return not bad return not bad
def HooksCallBack(self, phase, hooks_results, feedback_fn, lu_result): def HooksCallBack(self, phase, hooks_results, feedback_fn, lu_result):
"""Analize the post-hooks' result, handle it, and send some """Analize the post-hooks' result
This method analyses the hook result, handles it, and sends some
nicely-formatted feedback back to the user. nicely-formatted feedback back to the user.
Args: @param phase: one of L{constants.HOOKS_PHASE_POST} or
phase: the hooks phase that has just been run L{constants.HOOKS_PHASE_PRE}; it denotes the hooks phase
hooks_results: the results of the multi-node hooks rpc call @param hooks_results: the results of the multi-node hooks rpc call
feedback_fn: function to send feedback back to the caller @param feedback_fn: function used send feedback back to the caller
lu_result: previous Exec result @param lu_result: previous Exec result
@return: the new Exec result, based on the previous result
and hook results
""" """
# We only really run POST phase hooks, and are only interested in # We only really run POST phase hooks, and are only interested in
...@@ -1102,11 +1156,10 @@ class LURenameCluster(LogicalUnit): ...@@ -1102,11 +1156,10 @@ class LURenameCluster(LogicalUnit):
def _RecursiveCheckIfLVMBased(disk): def _RecursiveCheckIfLVMBased(disk):
"""Check if the given disk or its children are lvm-based. """Check if the given disk or its children are lvm-based.
Args: @type disk: L{objects.Disk}
disk: ganeti.objects.Disk object @param disk: the disk to check
@rtype: booleean
Returns: @return: boolean indicating whether a LD_LV dev_type was found or not
boolean indicating whether a LD_LV dev_type was found or not
""" """
if disk.children: if disk.children:
...@@ -1344,17 +1397,16 @@ class LUDiagnoseOS(NoHooksLU): ...@@ -1344,17 +1397,16 @@ class LUDiagnoseOS(NoHooksLU):
def _DiagnoseByOS(node_list, rlist): def _DiagnoseByOS(node_list, rlist):
"""Remaps a per-node return list into an a per-os per-node dictionary """Remaps a per-node return list into an a per-os per-node dictionary
Args: @param node_list: a list with the names of all nodes
node_list: a list with the names of all nodes @param rlist: a map with node names as keys and OS objects as values
rlist: a map with node names as keys and OS objects as values
Returns: @rtype: dict
map: a map with osnames as keys and as value another map, with @returns: a dictionary with osnames as keys and as value another map, with
nodes as nodes as keys and list of OS objects as values, eg::
keys and list of OS objects as values
e.g. {"debian-etch": {"node1": [<object>,...], {"debian-etch": {"node1": [<object>,...],
"node2": [<object>,]} "node2": [<object>,]}
} }
""" """
all_os = {} all_os = {}
...@@ -2012,15 +2064,17 @@ def _AssembleInstanceDisks(lu, instance, ignore_secondaries=False): ...@@ -2012,15 +2064,17 @@ def _AssembleInstanceDisks(lu, instance, ignore_secondaries=False):
This sets up the block devices on all nodes. This sets up the block devices on all nodes.
Args: @type lu: L{LogicalUnit}
instance: a ganeti.objects.Instance object @param lu: the logical unit on whose behalf we execute
ignore_secondaries: if true, errors on secondary nodes won't result @type instance: L{objects.Instance}
in an error return from the function @param instance: the instance for whose disks we assemble
@type ignore_secondaries: boolean
@param ignore_secondaries: if true, errors on secondary nodes
won't result in an error return from the function
@return: False if the operation failed, otherwise a list of
(host, instance_visible_name, node_visible_name)
with the mapping from node devices to instance devices
Returns:
false if the operation failed
list of (host, instance_visible_name, node_visible_name) if the operation
suceeded with the mapping from node devices to instance devices
""" """
device_info = [] device_info = []
disks_ok = True disks_ok = True
...@@ -3167,11 +3221,12 @@ def _CreateDisks(lu, instance): ...@@ -3167,11 +3221,12 @@ def _CreateDisks(lu, instance):
This abstracts away some work from AddInstance. This abstracts away some work from AddInstance.
Args: @type lu: L{LogicalUnit}
instance: the instance object @param lu: the logical unit on whose behalf we execute
@type instance: L{objects.Instance}
Returns: @param instance: the instance whose disks we should create
True or False showing the success of the creation process @rtype: boolean
@return: the success of the creation
""" """
info = _GetInstanceInfoText(instance) info = _GetInstanceInfoText(instance)
...@@ -3216,11 +3271,12 @@ def _RemoveDisks(lu, instance): ...@@ -3216,11 +3271,12 @@ def _RemoveDisks(lu, instance):
be removed, the removal will continue with the other ones (compare be removed, the removal will continue with the other ones (compare
with `_CreateDisks()`). with `_CreateDisks()`).
Args: @type lu: L{LogicalUnit}
instance: the instance object @param lu: the logical unit on whose behalf we execute
@type instance: L{objects.Instance}
Returns: @param instance: the instance whose disks we should remove
True or False showing the success of the removal proces @rtype: boolean
@return: the success of the removal
""" """
logging.info("Removing block devices for instance %s", instance.name) logging.info("Removing block devices for instance %s", instance.name)
...@@ -3247,8 +3303,6 @@ def _RemoveDisks(lu, instance): ...@@ -3247,8 +3303,6 @@ def _RemoveDisks(lu, instance):
def _ComputeDiskSize(disk_template, disks): def _ComputeDiskSize(disk_template, disks):
"""Compute disk size requirements in the volume group """Compute disk size requirements in the volume group
This is currently hard-coded for the two-drive layout.
""" """
# Required free disk space as a function of disk and swap space # Required free disk space as a function of disk and swap space
req_size_dict = { req_size_dict = {
...@@ -4001,15 +4055,20 @@ class LUReplaceDisks(LogicalUnit): ...@@ -4001,15 +4055,20 @@ class LUReplaceDisks(LogicalUnit):
"""Replace a disk on the primary or secondary for dbrd8. """Replace a disk on the primary or secondary for dbrd8.
The algorithm for replace is quite complicated: The algorithm for replace is quite complicated:
- for each disk to be replaced:
- create new LVs on the target node with unique names 1. for each disk to be replaced:
- detach old LVs from the drbd device
- rename old LVs to name_replaced.<time_t> 1. create new LVs on the target node with unique names
- rename new LVs to old LVs 1. detach old LVs from the drbd device
- attach the new LVs (with the old names now) to the drbd device 1. rename old LVs to name_replaced.<time_t>
- wait for sync across all devices 1. rename new LVs to old LVs
- for each modified disk: 1. attach the new LVs (with the old names now) to the drbd device
- remove old LVs (which have the name name_replaces.<time_t>)
1. wait for sync across all devices
1. for each modified disk:
1. remove old LVs (which have the name name_replaces.<time_t>)
Failures are not very well handled. Failures are not very well handled.
...@@ -4857,10 +4916,10 @@ class LUQueryExports(NoHooksLU): ...@@ -4857,10 +4916,10 @@ class LUQueryExports(NoHooksLU):
def Exec(self, feedback_fn): def Exec(self, feedback_fn):
"""Compute the list of all the exported system images. """Compute the list of all the exported system images.
Returns: @rtype: dict
a dictionary with the structure node->(export-list) @return: a dictionary with the structure node->(export-list)
where export-list is a list of the instances exported on where export-list is a list of the instances exported on
that node. that node.
""" """
return self.rpc.call_export_list(self.nodes) return self.rpc.call_export_list(self.nodes)
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment