Package ganeti :: Package cmdlib :: Module base :: Class LogicalUnit
[hide private]
[frames] | no frames]

Class LogicalUnit

source code


Logical Unit base class.

Subclasses must follow these rules:

Note that all commands require root permissions.

Instance Methods [hide private]
 
__init__(self, processor, op, context, rpc_runner)
Constructor for LogicalUnit.
source code
 
CheckArguments(self)
Check syntactic validity for the opcode arguments.
source code
 
ExpandNames(self)
Expand names for this LU.
source code
 
DeclareLocks(self, level)
Declare LU locking needs for a level
source code
 
CheckPrereq(self)
Check prerequisites for this LU.
source code
 
Exec(self, feedback_fn)
Execute the LU.
source code
dict
BuildHooksEnv(self)
Build hooks environment for this LU.
source code
tuple; (list, list) or (list, list, list)
BuildHooksNodes(self)
Build list of nodes to run LU's hooks.
source code
 
HooksCallBack(self, phase, hook_results, feedback_fn, lu_result)
Notify the LU about the results of its hooks.
source code
 
_ExpandAndLockInstance(self)
Helper function to expand and lock an instance.
source code
 
_LockInstancesNodes(self, primary_only=False, level=locking.LEVEL_NODE)
Helper function to declare instances' nodes for locking.
source code

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__, __sizeof__, __str__, __subclasshook__

Class Variables [hide private]
  HPATH = None
  HTYPE = None
  REQ_BGL = True
Instance Variables [hide private]
  dry_run_result
the value (if any) that will be returned to the caller in dry-run mode (signalled by opcode dry_run parameter)
Properties [hide private]

Inherited from object: __class__

Method Details [hide private]

__init__(self, processor, op, context, rpc_runner)
(Constructor)

source code 

Constructor for LogicalUnit.

This needs to be overridden in derived classes in order to check op validity.

Overrides: object.__init__

CheckArguments(self)

source code 

Check syntactic validity for the opcode arguments.

This method is for doing a simple syntactic check and ensure validity of opcode parameters, without any cluster-related checks. While the same can be accomplished in ExpandNames and/or CheckPrereq, doing these separate is better because:

  • ExpandNames is left as as purely a lock-related function
  • CheckPrereq is run after we have acquired locks (and possible waited for them)

The function is allowed to change the self.op attribute so that later methods can no longer worry about missing parameters.

ExpandNames(self)

source code 

Expand names for this LU.

This method is called before starting to execute the opcode, and it should update all the parameters of the opcode to their canonical form (e.g. a short node name must be fully expanded after this method has successfully completed). This way locking, hooks, logging, etc. can work correctly.

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 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 (note that in this case DeclareLocks won't be called at all for that level)
  • if you need locks at a level, but you can't calculate it in this function, initialise that level with an empty list and do further processing in LogicalUnit.DeclareLocks (see that function's docstring)
  • 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 level you can modify self.share_locks, setting a true value (usually 1) for that level. By default locks are not shared.

This function can also define a list of tasklets, which then will be executed in order instead of the usual LU-level CheckPrereq and Exec functions, if those are not defined by the LU.

Examples:

 # Acquire all nodes and one instance
 self.needed_locks = {
   locking.LEVEL_NODE: locking.ALL_SET,
   locking.LEVEL_INSTANCE: ['instance1.example.com'],
 }
 # Acquire just two nodes
 self.needed_locks = {
   locking.LEVEL_NODE: ['node1-uuid', 'node2-uuid'],
 }
 # Acquire no locks
 self.needed_locks = {} # No, you can't leave it to the default value None

DeclareLocks(self, level)

source code 

Declare LU locking needs for a level

While most LUs can just declare their locking needs at ExpandNames time, sometimes there's the need to calculate some locks after having acquired the ones before. This function is called just before acquiring locks at a particular level, but after acquiring the ones at lower levels, and permits such calculations. It can be used to modify self.needed_locks, and by default it does nothing.

This function is only called if you have something already set in self.needed_locks for the level.

Parameters:

CheckPrereq(self)

source code 

Check prerequisites for this LU.

This method should check that the prerequisites for the execution of this LU are fulfilled. It can do internode communication, but it should be idempotent - no cluster or system changes are allowed.

The method should raise errors.OpPrereqError in case something is not fulfilled. Its return value is ignored.

This method should also update all the parameters of the opcode to their canonical form if it hasn't been done by ExpandNames before.

Exec(self, feedback_fn)

source code 

Execute the LU.

This method should implement the actual work. It should raise errors.OpExecError for failures that are somewhat dealt with in code, or expected.

BuildHooksEnv(self)

source code 

Build hooks environment for this LU.

Returns: dict
Dictionary containing the environment that will be used for running the hooks for this LU. The keys of the dict must not be prefixed with "GANETI_"--that'll be added by the hooks runner. The hooks runner will extend the environment with additional variables. If no environment should be defined, an empty dictionary should be returned (not None).

Note: If the HPATH attribute of the LU class is None, this function will not be called.

BuildHooksNodes(self)

source code 

Build list of nodes to run LU's hooks.

Returns: tuple; (list, list) or (list, list, list)
Tuple containing a list of node UUIDs on which the hook should run before the execution and a list of node UUIDs on which the hook should run after the execution. As it might be possible that the node UUID is not known at the time this method is invoked, an optional third list can be added which contains node names on which the hook should run after the execution (in case of node add, for instance). No nodes should be returned as an empty list (and not None).

Note: If the HPATH attribute of the LU class is None, this function will not be called.

HooksCallBack(self, phase, hook_results, feedback_fn, lu_result)

source code 

Notify the LU about the results of its hooks.

This method is called every time a hooks phase is executed, and notifies the Logical Unit about the hooks' result. The LU can then use it to alter its result based on the hooks. By default the method does nothing and the previous result is passed back unchanged but any LU can define it if it wants to use the local cluster hook-scripts somehow.

Parameters:
  • phase - one of constants.HOOKS_PHASE_POST or constants.HOOKS_PHASE_PRE; it denotes the hooks phase
  • hook_results - the results of the multi-node hooks rpc call
  • feedback_fn - function used send feedback back to the caller
  • lu_result - the previous Exec result this LU had, or None in the PRE phase
Returns:
the new Exec result, based on the previous result and hook results

_ExpandAndLockInstance(self)

source code 

Helper function to expand and lock an instance.

Many LUs that work on an instance take its name in self.op.instance_name and need to expand it and then declare the expanded name for locking. This function does it, and then updates self.op.instance_name to the expanded name. It also initializes needed_locks as a dict, if this hasn't been done before.

_LockInstancesNodes(self, primary_only=False, level=locking.LEVEL_NODE)

source code 

Helper function to declare instances' nodes for locking.

This function should be called after locking one or more instances to lock their nodes. Its effect is populating self.needed_locks[locking.LEVEL_NODE] with all primary or secondary nodes for instances already locked and present in self.needed_locks[locking.LEVEL_INSTANCE].

It should be called from DeclareLocks, and for safety only works if self.recalculate_locks[locking.LEVEL_NODE] is set.

In the future it may grow parameters to just lock some instance's nodes, or to just lock primaries or secondary nodes, if needed.

If should be called in DeclareLocks in a way similar to:

 if level == locking.LEVEL_NODE:
   self._LockInstancesNodes()
Parameters:
  • primary_only (boolean) - only lock primary nodes of locked instances
  • level - Which lock level to use for locking nodes