1# (c) 2012-2014, Michael DeHaan <michael.dehaan@gmail.com> 2# 3# This file is part of Ansible 4# 5# Ansible is free software: you can redistribute it and/or modify 6# it under the terms of the GNU General Public License as published by 7# the Free Software Foundation, either version 3 of the License, or 8# (at your option) any later version. 9# 10# Ansible is distributed in the hope that it will be useful, 11# but WITHOUT ANY WARRANTY; without even the implied warranty of 12# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13# GNU General Public License for more details. 14# 15# You should have received a copy of the GNU General Public License 16# along with Ansible. If not, see <http://www.gnu.org/licenses/>. 17 18# Make coding more python3-ish 19from __future__ import (absolute_import, division, print_function) 20__metaclass__ = type 21 22import os 23 24from ansible import constants as C 25from ansible.errors import AnsibleError, AnsibleParserError, AnsibleUndefinedVariable, AnsibleAssertionError 26from ansible.module_utils._text import to_native 27from ansible.module_utils.six import iteritems, string_types 28from ansible.parsing.mod_args import ModuleArgsParser 29from ansible.parsing.yaml.objects import AnsibleBaseYAMLObject, AnsibleMapping 30from ansible.plugins.loader import lookup_loader 31from ansible.playbook.attribute import FieldAttribute 32from ansible.playbook.base import Base 33from ansible.playbook.block import Block 34from ansible.playbook.collectionsearch import CollectionSearch 35from ansible.playbook.conditional import Conditional 36from ansible.playbook.loop_control import LoopControl 37from ansible.playbook.role import Role 38from ansible.playbook.taggable import Taggable 39from ansible.utils.collection_loader import AnsibleCollectionLoader 40from ansible.utils.display import Display 41from ansible.utils.sentinel import Sentinel 42 43__all__ = ['Task'] 44 45display = Display() 46 47 48class Task(Base, Conditional, Taggable, CollectionSearch): 49 50 """ 51 A task is a language feature that represents a call to a module, with given arguments and other parameters. 52 A handler is a subclass of a task. 53 54 Usage: 55 56 Task.load(datastructure) -> Task 57 Task.something(...) 58 """ 59 60 # ================================================================================= 61 # ATTRIBUTES 62 # load_<attribute_name> and 63 # validate_<attribute_name> 64 # will be used if defined 65 # might be possible to define others 66 67 # NOTE: ONLY set defaults on task attributes that are not inheritable, 68 # inheritance is only triggered if the 'current value' is None, 69 # default can be set at play/top level object and inheritance will take it's course. 70 71 _args = FieldAttribute(isa='dict', default=dict) 72 _action = FieldAttribute(isa='string') 73 74 _async_val = FieldAttribute(isa='int', default=0, alias='async') 75 _changed_when = FieldAttribute(isa='list', default=list) 76 _delay = FieldAttribute(isa='int', default=5) 77 _delegate_to = FieldAttribute(isa='string') 78 _delegate_facts = FieldAttribute(isa='bool') 79 _failed_when = FieldAttribute(isa='list', default=list) 80 _loop = FieldAttribute() 81 _loop_control = FieldAttribute(isa='class', class_type=LoopControl, inherit=False) 82 _notify = FieldAttribute(isa='list') 83 _poll = FieldAttribute(isa='int', default=C.DEFAULT_POLL_INTERVAL) 84 _register = FieldAttribute(isa='string', static=True) 85 _retries = FieldAttribute(isa='int', default=3) 86 _until = FieldAttribute(isa='list', default=list) 87 88 # deprecated, used to be loop and loop_args but loop has been repurposed 89 _loop_with = FieldAttribute(isa='string', private=True, inherit=False) 90 91 def __init__(self, block=None, role=None, task_include=None): 92 ''' constructors a task, without the Task.load classmethod, it will be pretty blank ''' 93 94 self._role = role 95 self._parent = None 96 97 if task_include: 98 self._parent = task_include 99 else: 100 self._parent = block 101 102 super(Task, self).__init__() 103 104 def get_path(self): 105 ''' return the absolute path of the task with its line number ''' 106 107 path = "" 108 if hasattr(self, '_ds') and hasattr(self._ds, '_data_source') and hasattr(self._ds, '_line_number'): 109 path = "%s:%s" % (self._ds._data_source, self._ds._line_number) 110 elif hasattr(self._parent._play, '_ds') and hasattr(self._parent._play._ds, '_data_source') and hasattr(self._parent._play._ds, '_line_number'): 111 path = "%s:%s" % (self._parent._play._ds._data_source, self._parent._play._ds._line_number) 112 return path 113 114 def get_name(self, include_role_fqcn=True): 115 ''' return the name of the task ''' 116 117 if self._role: 118 role_name = self._role.get_name(include_role_fqcn=include_role_fqcn) 119 120 if self._role and self.name and role_name not in self.name: 121 return "%s : %s" % (role_name, self.name) 122 elif self.name: 123 return self.name 124 else: 125 if self._role: 126 return "%s : %s" % (role_name, self.action) 127 else: 128 return "%s" % (self.action,) 129 130 def _merge_kv(self, ds): 131 if ds is None: 132 return "" 133 elif isinstance(ds, string_types): 134 return ds 135 elif isinstance(ds, dict): 136 buf = "" 137 for (k, v) in iteritems(ds): 138 if k.startswith('_'): 139 continue 140 buf = buf + "%s=%s " % (k, v) 141 buf = buf.strip() 142 return buf 143 144 @staticmethod 145 def load(data, block=None, role=None, task_include=None, variable_manager=None, loader=None): 146 t = Task(block=block, role=role, task_include=task_include) 147 return t.load_data(data, variable_manager=variable_manager, loader=loader) 148 149 def __repr__(self): 150 ''' returns a human readable representation of the task ''' 151 if self.get_name() in C._ACTION_META: 152 return "TASK: meta (%s)" % self.args['_raw_params'] 153 else: 154 return "TASK: %s" % self.get_name() 155 156 def _preprocess_with_loop(self, ds, new_ds, k, v): 157 ''' take a lookup plugin name and store it correctly ''' 158 159 loop_name = k.replace("with_", "") 160 if new_ds.get('loop') is not None or new_ds.get('loop_with') is not None: 161 raise AnsibleError("duplicate loop in task: %s" % loop_name, obj=ds) 162 if v is None: 163 raise AnsibleError("you must specify a value when using %s" % k, obj=ds) 164 new_ds['loop_with'] = loop_name 165 new_ds['loop'] = v 166 # display.deprecated("with_ type loops are being phased out, use the 'loop' keyword instead", version="2.10") 167 168 def preprocess_data(self, ds): 169 ''' 170 tasks are especially complex arguments so need pre-processing. 171 keep it short. 172 ''' 173 174 if not isinstance(ds, dict): 175 raise AnsibleAssertionError('ds (%s) should be a dict but was a %s' % (ds, type(ds))) 176 177 # the new, cleaned datastructure, which will have legacy 178 # items reduced to a standard structure suitable for the 179 # attributes of the task class 180 new_ds = AnsibleMapping() 181 if isinstance(ds, AnsibleBaseYAMLObject): 182 new_ds.ansible_pos = ds.ansible_pos 183 184 # since this affects the task action parsing, we have to resolve in preprocess instead of in typical validator 185 default_collection = AnsibleCollectionLoader().default_collection 186 187 # use the parent value if our ds doesn't define it 188 collections_list = ds.get('collections', self.collections) 189 190 if collections_list is None: 191 collections_list = [] 192 193 if isinstance(collections_list, string_types): 194 collections_list = [collections_list] 195 196 if default_collection and not self._role: # FIXME: and not a collections role 197 if collections_list: 198 if default_collection not in collections_list: 199 collections_list.insert(0, default_collection) 200 else: 201 collections_list = [default_collection] 202 203 if collections_list and 'ansible.builtin' not in collections_list and 'ansible.legacy' not in collections_list: 204 collections_list.append('ansible.legacy') 205 206 if collections_list: 207 ds['collections'] = collections_list 208 209 # use the args parsing class to determine the action, args, 210 # and the delegate_to value from the various possible forms 211 # supported as legacy 212 args_parser = ModuleArgsParser(task_ds=ds, collection_list=collections_list) 213 try: 214 (action, args, delegate_to) = args_parser.parse() 215 except AnsibleParserError as e: 216 # if the raises exception was created with obj=ds args, then it includes the detail 217 # so we dont need to add it so we can just re raise. 218 if e._obj: 219 raise 220 # But if it wasn't, we can add the yaml object now to get more detail 221 raise AnsibleParserError(to_native(e), obj=ds, orig_exc=e) 222 223 # the command/shell/script modules used to support the `cmd` arg, 224 # which corresponds to what we now call _raw_params, so move that 225 # value over to _raw_params (assuming it is empty) 226 if action in C._ACTION_HAS_CMD: 227 if 'cmd' in args: 228 if args.get('_raw_params', '') != '': 229 raise AnsibleError("The 'cmd' argument cannot be used when other raw parameters are specified." 230 " Please put everything in one or the other place.", obj=ds) 231 args['_raw_params'] = args.pop('cmd') 232 233 new_ds['action'] = action 234 new_ds['args'] = args 235 new_ds['delegate_to'] = delegate_to 236 237 # we handle any 'vars' specified in the ds here, as we may 238 # be adding things to them below (special handling for includes). 239 # When that deprecated feature is removed, this can be too. 240 if 'vars' in ds: 241 # _load_vars is defined in Base, and is used to load a dictionary 242 # or list of dictionaries in a standard way 243 new_ds['vars'] = self._load_vars(None, ds.get('vars')) 244 else: 245 new_ds['vars'] = dict() 246 247 for (k, v) in iteritems(ds): 248 if k in ('action', 'local_action', 'args', 'delegate_to') or k == action or k == 'shell': 249 # we don't want to re-assign these values, which were determined by the ModuleArgsParser() above 250 continue 251 elif k.startswith('with_') and k.replace("with_", "") in lookup_loader: 252 # transform into loop property 253 self._preprocess_with_loop(ds, new_ds, k, v) 254 else: 255 # pre-2.0 syntax allowed variables for include statements at the top level of the task, 256 # so we move those into the 'vars' dictionary here, and show a deprecation message 257 # as we will remove this at some point in the future. 258 if action in C._ACTION_INCLUDE and k not in self._valid_attrs and k not in self.DEPRECATED_ATTRIBUTES: 259 display.deprecated("Specifying include variables at the top-level of the task is deprecated." 260 " Please see:\nhttps://docs.ansible.com/ansible/playbooks_roles.html#task-include-files-and-encouraging-reuse\n\n" 261 " for currently supported syntax regarding included files and variables", version="2.12") 262 new_ds['vars'][k] = v 263 elif C.INVALID_TASK_ATTRIBUTE_FAILED or k in self._valid_attrs: 264 new_ds[k] = v 265 else: 266 display.warning("Ignoring invalid attribute: %s" % k) 267 268 return super(Task, self).preprocess_data(new_ds) 269 270 def _load_loop_control(self, attr, ds): 271 if not isinstance(ds, dict): 272 raise AnsibleParserError( 273 "the `loop_control` value must be specified as a dictionary and cannot " 274 "be a variable itself (though it can contain variables)", 275 obj=ds, 276 ) 277 278 return LoopControl.load(data=ds, variable_manager=self._variable_manager, loader=self._loader) 279 280 def _validate_attributes(self, ds): 281 try: 282 super(Task, self)._validate_attributes(ds) 283 except AnsibleParserError as e: 284 e.message += '\nThis error can be suppressed as a warning using the "invalid_task_attribute_failed" configuration' 285 raise e 286 287 def post_validate(self, templar): 288 ''' 289 Override of base class post_validate, to also do final validation on 290 the block and task include (if any) to which this task belongs. 291 ''' 292 293 if self._parent: 294 self._parent.post_validate(templar) 295 296 if AnsibleCollectionLoader().default_collection: 297 pass 298 299 super(Task, self).post_validate(templar) 300 301 def _post_validate_loop(self, attr, value, templar): 302 ''' 303 Override post validation for the loop field, which is templated 304 specially in the TaskExecutor class when evaluating loops. 305 ''' 306 return value 307 308 def _post_validate_environment(self, attr, value, templar): 309 ''' 310 Override post validation of vars on the play, as we don't want to 311 template these too early. 312 ''' 313 env = {} 314 if value is not None: 315 316 def _parse_env_kv(k, v): 317 try: 318 env[k] = templar.template(v, convert_bare=False) 319 except AnsibleUndefinedVariable as e: 320 error = to_native(e) 321 if self.action in C._ACTION_FACT_GATHERING and 'ansible_facts.env' in error or 'ansible_env' in error: 322 # ignore as fact gathering is required for 'env' facts 323 return 324 raise 325 326 if isinstance(value, list): 327 for env_item in value: 328 if isinstance(env_item, dict): 329 for k in env_item: 330 _parse_env_kv(k, env_item[k]) 331 else: 332 isdict = templar.template(env_item, convert_bare=False) 333 if isinstance(isdict, dict): 334 env.update(isdict) 335 else: 336 display.warning("could not parse environment value, skipping: %s" % value) 337 338 elif isinstance(value, dict): 339 # should not really happen 340 env = dict() 341 for env_item in value: 342 _parse_env_kv(env_item, value[env_item]) 343 else: 344 # at this point it should be a simple string, also should not happen 345 env = templar.template(value, convert_bare=False) 346 347 return env 348 349 def _post_validate_changed_when(self, attr, value, templar): 350 ''' 351 changed_when is evaluated after the execution of the task is complete, 352 and should not be templated during the regular post_validate step. 353 ''' 354 return value 355 356 def _post_validate_failed_when(self, attr, value, templar): 357 ''' 358 failed_when is evaluated after the execution of the task is complete, 359 and should not be templated during the regular post_validate step. 360 ''' 361 return value 362 363 def _post_validate_until(self, attr, value, templar): 364 ''' 365 until is evaluated after the execution of the task is complete, 366 and should not be templated during the regular post_validate step. 367 ''' 368 return value 369 370 def get_vars(self): 371 all_vars = dict() 372 if self._parent: 373 all_vars.update(self._parent.get_vars()) 374 375 all_vars.update(self.vars) 376 377 if 'tags' in all_vars: 378 del all_vars['tags'] 379 if 'when' in all_vars: 380 del all_vars['when'] 381 382 return all_vars 383 384 def get_include_params(self): 385 all_vars = dict() 386 if self._parent: 387 all_vars.update(self._parent.get_include_params()) 388 if self.action in C._ACTION_ALL_INCLUDES: 389 all_vars.update(self.vars) 390 return all_vars 391 392 def copy(self, exclude_parent=False, exclude_tasks=False): 393 new_me = super(Task, self).copy() 394 395 new_me._parent = None 396 if self._parent and not exclude_parent: 397 new_me._parent = self._parent.copy(exclude_tasks=exclude_tasks) 398 399 new_me._role = None 400 if self._role: 401 new_me._role = self._role 402 403 return new_me 404 405 def serialize(self): 406 data = super(Task, self).serialize() 407 408 if not self._squashed and not self._finalized: 409 if self._parent: 410 data['parent'] = self._parent.serialize() 411 data['parent_type'] = self._parent.__class__.__name__ 412 413 if self._role: 414 data['role'] = self._role.serialize() 415 416 return data 417 418 def deserialize(self, data): 419 420 # import is here to avoid import loops 421 from ansible.playbook.task_include import TaskInclude 422 from ansible.playbook.handler_task_include import HandlerTaskInclude 423 424 parent_data = data.get('parent', None) 425 if parent_data: 426 parent_type = data.get('parent_type') 427 if parent_type == 'Block': 428 p = Block() 429 elif parent_type == 'TaskInclude': 430 p = TaskInclude() 431 elif parent_type == 'HandlerTaskInclude': 432 p = HandlerTaskInclude() 433 p.deserialize(parent_data) 434 self._parent = p 435 del data['parent'] 436 437 role_data = data.get('role') 438 if role_data: 439 r = Role() 440 r.deserialize(role_data) 441 self._role = r 442 del data['role'] 443 444 super(Task, self).deserialize(data) 445 446 def set_loader(self, loader): 447 ''' 448 Sets the loader on this object and recursively on parent, child objects. 449 This is used primarily after the Task has been serialized/deserialized, which 450 does not preserve the loader. 451 ''' 452 453 self._loader = loader 454 455 if self._parent: 456 self._parent.set_loader(loader) 457 458 def _get_parent_attribute(self, attr, extend=False, prepend=False): 459 ''' 460 Generic logic to get the attribute or parent attribute for a task value. 461 ''' 462 463 extend = self._valid_attrs[attr].extend 464 prepend = self._valid_attrs[attr].prepend 465 try: 466 value = self._attributes[attr] 467 # If parent is static, we can grab attrs from the parent 468 # otherwise, defer to the grandparent 469 if getattr(self._parent, 'statically_loaded', True): 470 _parent = self._parent 471 else: 472 _parent = self._parent._parent 473 474 if _parent and (value is Sentinel or extend): 475 if getattr(_parent, 'statically_loaded', True): 476 # vars are always inheritable, other attributes might not be for the parent but still should be for other ancestors 477 if attr != 'vars' and hasattr(_parent, '_get_parent_attribute'): 478 parent_value = _parent._get_parent_attribute(attr) 479 else: 480 parent_value = _parent._attributes.get(attr, Sentinel) 481 482 if extend: 483 value = self._extend_value(value, parent_value, prepend) 484 else: 485 value = parent_value 486 except KeyError: 487 pass 488 489 return value 490 491 def get_dep_chain(self): 492 if self._parent: 493 return self._parent.get_dep_chain() 494 else: 495 return None 496 497 def get_search_path(self): 498 ''' 499 Return the list of paths you should search for files, in order. 500 This follows role/playbook dependency chain. 501 ''' 502 path_stack = [] 503 504 dep_chain = self.get_dep_chain() 505 # inside role: add the dependency chain from current to dependent 506 if dep_chain: 507 path_stack.extend(reversed([x._role_path for x in dep_chain])) 508 509 # add path of task itself, unless it is already in the list 510 task_dir = os.path.dirname(self.get_path()) 511 if task_dir not in path_stack: 512 path_stack.append(task_dir) 513 514 return path_stack 515 516 def all_parents_static(self): 517 if self._parent: 518 return self._parent.all_parents_static() 519 return True 520 521 def get_first_parent_include(self): 522 from ansible.playbook.task_include import TaskInclude 523 if self._parent: 524 if isinstance(self._parent, TaskInclude): 525 return self._parent 526 return self._parent.get_first_parent_include() 527 return None 528