ganeti.cmdlib.base

57 """Logical Unit base class. 58 59 Subclasses must follow these rules: 60 - implement ExpandNames 61 - implement CheckPrereq (except when tasklets are used) 62 - implement Exec (except when tasklets are used) 63 - implement BuildHooksEnv 64 - implement BuildHooksNodes 65 - redefine HPATH and HTYPE 66 - optionally redefine their run requirements: 67 REQ_BGL: the LU needs to hold the Big Ganeti Lock exclusively 68 69 Note that all commands require root permissions. 70 71 @ivar dry_run_result: the value (if any) that will be returned to the caller 72 in dry-run mode (signalled by opcode dry_run parameter) 73 74 """ 75 HPATH = None 76 HTYPE = None 77 REQ_BGL = True 78

79 - def __init__(self, processor, op, context, rpc_runner):

80 """Constructor for LogicalUnit. 81 82 This needs to be overridden in derived classes in order to check op 83 validity. 84 85 """ 86 self.proc = processor 87 self.op = op 88 self.cfg = context.cfg 89 self.glm = context.glm 90 # readability alias 91 self.owned_locks = context.glm.list_owned 92 self.context = context 93 self.rpc = rpc_runner 94 95 # Dictionaries used to declare locking needs to mcpu 96 self.needed_locks = None 97 self.share_locks = dict.fromkeys(locking.LEVELS, 0) 98 self.opportunistic_locks = dict.fromkeys(locking.LEVELS, False) 99 100 self.add_locks = {} 101 self.remove_locks = {} 102 103 # Used to force good behavior when calling helper functions 104 self.recalculate_locks = {} 105 106 # logging 107 self.Log = processor.Log # pylint: disable=C0103 108 self.LogWarning = processor.LogWarning # pylint: disable=C0103 109 self.LogInfo = processor.LogInfo # pylint: disable=C0103 110 self.LogStep = processor.LogStep # pylint: disable=C0103 111 # support for dry-run 112 self.dry_run_result = None 113 # support for generic debug attribute 114 if (not hasattr(self.op, "debug_level") or 115 not isinstance(self.op.debug_level, int)): 116 self.op.debug_level = 0 117 118 # Tasklets 119 self.tasklets = None 120 121 # Validate opcode parameters and set defaults 122 self.op.Validate(True) 123 124 self.CheckArguments()

125

126 - def CheckArguments(self):

127 """Check syntactic validity for the opcode arguments. 128 129 This method is for doing a simple syntactic check and ensure 130 validity of opcode parameters, without any cluster-related 131 checks. While the same can be accomplished in ExpandNames and/or 132 CheckPrereq, doing these separate is better because: 133 134 - ExpandNames is left as as purely a lock-related function 135 - CheckPrereq is run after we have acquired locks (and possible 136 waited for them) 137 138 The function is allowed to change the self.op attribute so that 139 later methods can no longer worry about missing parameters. 140 141 """ 142 pass

143

144 - def ExpandNames(self):

145 """Expand names for this LU. 146 147 This method is called before starting to execute the opcode, and it should 148 update all the parameters of the opcode to their canonical form (e.g. a 149 short node name must be fully expanded after this method has successfully 150 completed). This way locking, hooks, logging, etc. can work correctly. 151 152 LUs which implement this method must also populate the self.needed_locks 153 member, as a dict with lock levels as keys, and a list of needed lock names 154 as values. Rules: 155 156 - use an empty dict if you don't need any lock 157 - if you don't need any lock at a particular level omit that 158 level (note that in this case C{DeclareLocks} won't be called 159 at all for that level) 160 - if you need locks at a level, but you can't calculate it in 161 this function, initialise that level with an empty list and do 162 further processing in L{LogicalUnit.DeclareLocks} (see that 163 function's docstring) 164 - don't put anything for the BGL level 165 - if you want all locks at a level use L{locking.ALL_SET} as a value 166 167 If you need to share locks (rather than acquire them exclusively) at one 168 level you can modify self.share_locks, setting a true value (usually 1) for 169 that level. By default locks are not shared. 170 171 This function can also define a list of tasklets, which then will be 172 executed in order instead of the usual LU-level CheckPrereq and Exec 173 functions, if those are not defined by the LU. 174 175 Examples:: 176 177 # Acquire all nodes and one instance 178 self.needed_locks = { 179 locking.LEVEL_NODE: locking.ALL_SET, 180 locking.LEVEL_INSTANCE: ['instance1.example.com'], 181 } 182 # Acquire just two nodes 183 self.needed_locks = { 184 locking.LEVEL_NODE: ['node1.example.com', 'node2.example.com'], 185 } 186 # Acquire no locks 187 self.needed_locks = {} # No, you can't leave it to the default value None 188 189 """ 190 # The implementation of this method is mandatory only if the new LU is 191 # concurrent, so that old LUs don't need to be changed all at the same 192 # time. 193 if self.REQ_BGL: 194 self.needed_locks = {} # Exclusive LUs don't need locks. 195 else: 196 raise NotImplementedError

197

198 - def DeclareLocks(self, level):

199 """Declare LU locking needs for a level 200 201 While most LUs can just declare their locking needs at ExpandNames time, 202 sometimes there's the need to calculate some locks after having acquired 203 the ones before. This function is called just before acquiring locks at a 204 particular level, but after acquiring the ones at lower levels, and permits 205 such calculations. It can be used to modify self.needed_locks, and by 206 default it does nothing. 207 208 This function is only called if you have something already set in 209 self.needed_locks for the level. 210 211 @param level: Locking level which is going to be locked 212 @type level: member of L{ganeti.locking.LEVELS} 213 214 """

215

216 - def CheckPrereq(self):

217 """Check prerequisites for this LU. 218 219 This method should check that the prerequisites for the execution 220 of this LU are fulfilled. It can do internode communication, but 221 it should be idempotent - no cluster or system changes are 222 allowed. 223 224 The method should raise errors.OpPrereqError in case something is 225 not fulfilled. Its return value is ignored. 226 227 This method should also update all the parameters of the opcode to 228 their canonical form if it hasn't been done by ExpandNames before. 229 230 """ 231 if self.tasklets is not None: 232 for (idx, tl) in enumerate(self.tasklets): 233 logging.debug("Checking prerequisites for tasklet %s/%s", 234 idx + 1, len(self.tasklets)) 235 tl.CheckPrereq() 236 else: 237 pass

238

239 - def Exec(self, feedback_fn):

240 """Execute the LU. 241 242 This method should implement the actual work. It should raise 243 errors.OpExecError for failures that are somewhat dealt with in 244 code, or expected. 245 246 """ 247 if self.tasklets is not None: 248 for (idx, tl) in enumerate(self.tasklets): 249 logging.debug("Executing tasklet %s/%s", idx + 1, len(self.tasklets)) 250 tl.Exec(feedback_fn) 251 else: 252 raise NotImplementedError

253

254 - def BuildHooksEnv(self):

255 """Build hooks environment for this LU. 256 257 @rtype: dict 258 @return: Dictionary containing the environment that will be used for 259 running the hooks for this LU. The keys of the dict must not be prefixed 260 with "GANETI_"--that'll be added by the hooks runner. The hooks runner 261 will extend the environment with additional variables. If no environment 262 should be defined, an empty dictionary should be returned (not C{None}). 263 @note: If the C{HPATH} attribute of the LU class is C{None}, this function 264 will not be called. 265 266 """ 267 raise NotImplementedError

268

269 - def BuildHooksNodes(self):

270 """Build list of nodes to run LU's hooks. 271 272 @rtype: tuple; (list, list) 273 @return: Tuple containing a list of node names on which the hook 274 should run before the execution and a list of node names on which the 275 hook should run after the execution. No nodes should be returned as an 276 empty list (and not None). 277 @note: If the C{HPATH} attribute of the LU class is C{None}, this function 278 will not be called. 279 280 """ 281 raise NotImplementedError

282

283 - def HooksCallBack(self, phase, hook_results, feedback_fn, lu_result):

284 """Notify the LU about the results of its hooks. 285 286 This method is called every time a hooks phase is executed, and notifies 287 the Logical Unit about the hooks' result. The LU can then use it to alter 288 its result based on the hooks. By default the method does nothing and the 289 previous result is passed back unchanged but any LU can define it if it 290 wants to use the local cluster hook-scripts somehow. 291 292 @param phase: one of L{constants.HOOKS_PHASE_POST} or 293 L{constants.HOOKS_PHASE_PRE}; it denotes the hooks phase 294 @param hook_results: the results of the multi-node hooks rpc call 295 @param feedback_fn: function used send feedback back to the caller 296 @param lu_result: the previous Exec result this LU had, or None 297 in the PRE phase 298 @return: the new Exec result, based on the previous result 299 and hook results 300 301 """ 302 # API must be kept, thus we ignore the unused argument and could 303 # be a function warnings 304 # pylint: disable=W0613,R0201 305 return lu_result

306

307 - def _ExpandAndLockInstance(self):

308 """Helper function to expand and lock an instance. 309 310 Many LUs that work on an instance take its name in self.op.instance_name 311 and need to expand it and then declare the expanded name for locking. This 312 function does it, and then updates self.op.instance_name to the expanded 313 name. It also initializes needed_locks as a dict, if this hasn't been done 314 before. 315 316 """ 317 if self.needed_locks is None: 318 self.needed_locks = {} 319 else: 320 assert locking.LEVEL_INSTANCE not in self.needed_locks, \ 321 "_ExpandAndLockInstance called with instance-level locks set" 322 self.op.instance_name = ExpandInstanceName(self.cfg, 323 self.op.instance_name) 324 self.needed_locks[locking.LEVEL_INSTANCE] = self.op.instance_name

325

326 - def _LockInstancesNodes(self, primary_only=False, 327 level=locking.LEVEL_NODE):

328 """Helper function to declare instances' nodes for locking. 329 330 This function should be called after locking one or more instances to lock 331 their nodes. Its effect is populating self.needed_locks[locking.LEVEL_NODE] 332 with all primary or secondary nodes for instances already locked and 333 present in self.needed_locks[locking.LEVEL_INSTANCE]. 334 335 It should be called from DeclareLocks, and for safety only works if 336 self.recalculate_locks[locking.LEVEL_NODE] is set. 337 338 In the future it may grow parameters to just lock some instance's nodes, or 339 to just lock primaries or secondary nodes, if needed. 340 341 If should be called in DeclareLocks in a way similar to:: 342 343 if level == locking.LEVEL_NODE: 344 self._LockInstancesNodes() 345 346 @type primary_only: boolean 347 @param primary_only: only lock primary nodes of locked instances 348 @param level: Which lock level to use for locking nodes 349 350 """ 351 assert level in self.recalculate_locks, \ 352 "_LockInstancesNodes helper function called with no nodes to recalculate" 353 354 # TODO: check if we're really been called with the instance locks held 355 356 # For now we'll replace self.needed_locks[locking.LEVEL_NODE], but in the 357 # future we might want to have different behaviors depending on the value 358 # of self.recalculate_locks[locking.LEVEL_NODE] 359 wanted_nodes = [] 360 locked_i = self.owned_locks(locking.LEVEL_INSTANCE) 361 for _, instance in self.cfg.GetMultiInstanceInfo(locked_i): 362 wanted_nodes.append(instance.primary_node) 363 if not primary_only: 364 wanted_nodes.extend(instance.secondary_nodes) 365 366 if self.recalculate_locks[level] == constants.LOCKS_REPLACE: 367 self.needed_locks[level] = wanted_nodes 368 elif self.recalculate_locks[level] == constants.LOCKS_APPEND: 369 self.needed_locks[level].extend(wanted_nodes) 370 else: 371 raise errors.ProgrammerError("Unknown recalculation mode") 372 373 del self.recalculate_locks[level]

Source Code for Module ganeti.cmdlib.base