ansible/docs/docsite/rst/user_guide
Matt Martz 445ff39f94
Become plugins (#50991)
* [WIP] become plugins

Move from hardcoded method to plugins for ease of use, expansion and overrides
  - load into connection as it is going to be the main consumer
  - play_context will also use to keep backwards compat API
  - ensure shell is used to construct commands when needed
  - migrate settings remove from base config in favor of plugin specific configs
  - cleanup ansible-doc
  - add become plugin docs
  - remove deprecated sudo/su code and keywords
  - adjust become options for cli
  - set plugin options from context
  - ensure config defs are avaialbe before instance
  - refactored getting the shell plugin, fixed tests
     - changed into regex as they were string matching, which does not work with random string generation
     - explicitly set flags for play context tests
 - moved plugin loading up front
 - now loads for basedir also
 - allow pyc/o for non m modules
 - fixes to tests and some plugins
 - migrate to play objects fro play_context
 - simiplify gathering
 -  added utf8 headers
 - moved option setting
 - add fail msg to dzdo
 - use tuple for multiple options on fail/missing
 - fix relative plugin paths
 - shift from play context to play
 - all tasks already inherit this from play directly
 - remove obsolete 'set play'
 - correct environment handling
 - add wrap_exe option to pfexec
 - fix runas to noop
 - fixed setting play context
 - added password configs
 - removed required false
 - remove from doc building till they are ready

future development:
  - deal with 'enable' and 'runas' which are not 'command wrappers' but 'state flags' and currently hardcoded in diff subsystems

* cleanup

  remove callers to removed func
  removed --sudo cli doc refs
  remove runas become_exe
  ensure keyerorr on plugin
  also fix backwards compat, missing method is attributeerror, not ansible error
  get remote_user consistently
  ignore missing system_tmpdirs on plugin load
  correct config precedence
  add deprecation
  fix networking imports
  backwards compat for plugins using BECOME_METHODS

* Port become_plugins to context.CLIARGS

This is a work in progress:
* Stop passing options around everywhere as we can use context.CLIARGS
  instead

* Refactor make_become_commands as asked for by alikins

* Typo in comment fix

* Stop loading values from the cli in more than one place

Both play and play_context were saving default values from the cli
arguments directly.  This changes things so that the default values are
loaded into the play and then play_context takes them from there.

* Rename BECOME_PLUGIN_PATH to DEFAULT_BECOME_PLUGIN_PATH

As alikins said, all other plugin paths are named
DEFAULT_plugintype_PLUGIN_PATH.  If we're going to rename these, that
should be done all at one time rather than piecemeal.

* One to throw away

This is a set of hacks to get setting FieldAttribute defaults to command
line args to work.  It's not fully done yet.

After talking it over with sivel and jimi-c this should be done by
fixing FieldAttributeBase and _get_parent_attribute() calls to do the
right thing when there is a non-None default.

What we want to be able to do ideally is something like this:

class Base(FieldAttributeBase):
    _check_mode = FieldAttribute([..] default=lambda: context.CLIARGS['check'])

class Play(Base):
    # lambda so that we have a chance to parse the command line args
    # before we get here.  In the future we might be able to restructure
    # this so that the cli parsing code runs before these classes are
    # defined.

class Task(Base):
    pass

And still have a playbook like this function:

---
- hosts:
  tasks:
  - command: whoami
    check_mode: True

(The check_mode test that is added as a separate commit in this PR will
let you test variations on this case).

There's a few separate reasons that the code doesn't let us do this or
a non-ugly workaround for this as written right now.  The fix that
jimi-c, sivel, and I talked about may let us do this or it may still
require a workaround (but less ugly) (having one class that has the
FieldAttributes with default values and one class that inherits from
that but just overrides the FieldAttributes which now have defaults)

* Revert "One to throw away"

This reverts commit 23aa883cbed11429ef1be2a2d0ed18f83a3b8064.

* Set FieldAttr defaults directly from CLIARGS

* Remove dead code

* Move timeout directly to PlayContext, it's never needed on Play

* just for backwards compat, add a static version of BECOME_METHODS to constants

* Make the become attr on the connection public, since it's used outside of the connection

* Logic fix

* Nuke connection testing if it supports specific become methods

* Remove unused vars

* Address rebase issues

* Fix path encoding issue

* Remove unused import

* Various cleanups

* Restore network_cli check in _low_level_execute_command

* type improvements for cliargs_deferred_get and swap shallowcopy to default to False

* minor cleanups

* Allow the su plugin to work, since it doesn't define a prompt the same way

* Fix up ksu become plugin

* Only set prompt if build_become_command was called

* Add helper to assist connection plugins in knowing they need to wait for a prompt

* Fix tests and code expectations

* Doc updates

* Various additional minor cleanups

* Make doas functional

* Don't change connection signature, load become plugin from TaskExecutor

* Remove unused imports

* Add comment about setting the become plugin on the playcontext

* Fix up tests for recent changes

* Support 'Password:' natively for the doas plugin

* Make default prompts raw

* wording cleanups. ci_complete

* Remove unrelated changes

* Address spelling mistake

* Restore removed test, and udpate to use new functionality

* Add changelog fragment

* Don't hard fail in set_attributes_from_cli on missing CLI keys

* Remove unrelated change to loader

* Remove internal deprecated FieldAttributes now

* Emit deprecation warnings now
2019-02-11 11:27:44 -06:00
..
shared_snippets
become.rst standardize connection variable names (#51776) 2019-02-11 10:43:10 -05:00
command_line_tools.rst Refine plugin docs (#49324) 2018-11-29 14:03:00 -06:00
index.rst
intro.rst Remove more docs build errors (#45364) 2018-09-11 17:51:47 +01:00
intro_adhoc.rst doc(user_guide): fix typos (#47425) 2018-10-24 12:01:24 -04:00
intro_bsd.rst Remove use of simplejson throughout code base (#43548) 2018-08-10 11:13:29 -05:00
intro_dynamic_inventory.rst Broken link fixed. (#51492) 2019-01-31 12:53:17 -06:00
intro_getting_started.rst Become plugins (#50991) 2019-02-11 11:27:44 -06:00
intro_inventory.rst standardize connection variable names (#51776) 2019-02-11 10:43:10 -05:00
intro_patterns.rst Prefer https:// links in the docs site 2018-08-01 08:20:40 -07:00
intro_windows.rst
modules.rst Prefer https:// links in the docs site 2018-08-01 08:20:40 -07:00
modules_intro.rst Prefer https:// links in the docs site 2018-08-01 08:20:40 -07:00
modules_support.rst link to KB article -certified modules (#50050) 2018-12-17 16:27:28 -06:00
playbook_pathing.rst doc(user_guide): fix typos (#47425) 2018-10-24 12:01:24 -04:00
playbooks.rst bad space (#47667) 2018-10-28 18:55:25 -05:00
playbooks_advanced_syntax.rst Updates variables docs: facts examples, headers, links, etc. (#47767) 2018-10-30 11:37:34 -04:00
playbooks_async.rst Fix docs syntax highlighting errors (#50836) 2019-01-24 16:09:41 -06:00
playbooks_best_practices.rst updated documentation fixing #47202 (#47267) 2018-10-31 09:36:35 -05:00
playbooks_blocks.rst updated documentation fixing #47202 (#47267) 2018-10-31 09:36:35 -05:00
playbooks_checkmode.rst
playbooks_conditionals.rst add note about register + skip (#51339) 2019-01-29 16:28:18 -05:00
playbooks_debugger.rst Add shorthand debugger method to recreate the task from the original ds (#46987) 2018-10-25 16:35:59 -05:00
playbooks_delegation.rst Update playbooks_delegation.rst (#51949) 2019-02-08 16:19:16 +05:30
playbooks_environment.rst clarify environment (#50987) 2019-01-23 13:54:05 -06:00
playbooks_error_handling.rst Update changed_when and failed_when examples (#50411) 2019-01-03 09:50:59 -05:00
playbooks_filters.rst Fix yaml indentation for from_yaml_all filter example (#51998) 2019-02-10 21:21:15 +05:30
playbooks_filters_ipaddr.rst ipaddr: Add missing documenation about network/prefix filter (#49532) 2018-12-05 12:14:13 -05:00
playbooks_intro.rst Become plugins (#50991) 2019-02-11 11:27:44 -06:00
playbooks_lookups.rst Prefer https:// links in the docs site 2018-08-01 08:20:40 -07:00
playbooks_loops.rst grammer fix and changed description to iteratively from recursively. (#50837) 2019-01-29 15:37:01 -05:00
playbooks_module_defaults.rst Add k8s module_defaults group and document (#51093) 2019-01-29 14:23:27 -06:00
playbooks_prompts.rst added unsafe toggle to vars_prompt (#49219) 2019-01-30 15:01:13 -05:00
playbooks_python_version.rst
playbooks_reuse.rst Add link to include / import module doc to discussion of include / import. (#48932) 2018-11-20 14:02:58 -06:00
playbooks_reuse_includes.rst update example to YAML style in documentation (#45968) 2018-09-21 08:42:31 -05:00
playbooks_reuse_roles.rst Correct docsite typos: it's -> its (#50812) 2019-01-11 15:49:54 -05:00
playbooks_roles.rst
playbooks_special_topics.rst clarifies FAQ answer about env vars (#48432) 2018-11-09 14:31:29 -05:00
playbooks_startnstep.rst
playbooks_strategies.rst Only one strategy_plugins page (#49442) 2018-12-03 20:35:01 +05:30
playbooks_tags.rst docs: tags: streamline indentation (#50875) 2019-01-15 15:54:38 +01:00
playbooks_templating.rst Add now() jinja2 global func for getting the date/time (#43792) 2018-12-07 11:25:53 -06:00
playbooks_tests.rst Correct match test documentation (#50229) 2018-12-21 09:38:31 -05:00
playbooks_variables.rst standardize connection variable names (#51776) 2019-02-11 10:43:10 -05:00
playbooks_vault.rst
plugin_filtering_config.rst Update plugin filter documentation (#46665) 2018-10-29 15:04:32 -04:00
quickstart.rst Update documentation based on 301 permanent redirects (#43675) 2018-08-13 14:54:14 -05:00
vault.rst Clean up Vault docs in User Guide. (#46188) 2018-09-28 10:16:58 -04:00
windows.rst
windows_dsc.rst Code example improvements in Windows documentation (#45055) 2018-11-15 16:17:29 -05:00
windows_faq.rst Fix typo 2018-12-05 03:20:10 +01:00
windows_setup.rst Update windows_setup.rst (#50941) 2019-01-15 13:24:22 -08:00
windows_usage.rst fixes typo in windows usage guide (#49672) 2018-12-08 13:42:39 -06:00
windows_winrm.rst Add a missed command (#50781) 2019-02-01 12:46:24 +10:00