Now that we don't need to worry about python-2.4 and 2.5, we can make
some improvements to the way AnsiballZ handles modules.
* Change AnsiballZ wrapper to use import to invoke the module
We need the module to think of itself as a script because it could be
coded as:
main()
or as:
if __name__ == '__main__':
main()
Or even as:
if __name__ == '__main__':
random_function_name()
A script will invoke all of those. Prior to this change, we invoked
a second Python interpreter on the module so that it really was
a script. However, this means that we have to run python twice (once
for the AnsiballZ wrapper and once for the module). This change makes
the module think that it is a script (because __name__ in the module ==
'__main__') but it's actually being invoked by us importing the module
code.
There's three ways we've come up to do this.
* The most elegant is to use zipimporter and tell the import mechanism
that the module being loaded is __main__:
* 5959f11c9d/lib/ansible/executor/module_common.py (L175)
* zipimporter is nice because we do not have to extract the module from
the zip file and save it to the disk when we do that. The import
machinery does it all for us.
* The drawback is that modules do not have a __file__ which points
to a real file when they do this. Modules could be using __file__
to for a variety of reasons, most of those probably have
replacements (the most common one is to find a writable directory
for temporary files. AnsibleModule.tmpdir should be used instead)
We can monkeypatch __file__ in fom AnsibleModule initialization
but that's kind of gross. There's no way I can see to do this
from the wrapper.
* Next, there's imp.load_module():
* https://github.com/abadger/ansible/blob/340edf7489/lib/ansible/executor/module_common.py#L151
* imp has the nice property of allowing us to set __name__ to
__main__ without changing the name of the file itself
* We also don't have to do anything special to set __file__ for
backwards compatibility (although the reason for that is the
drawback):
* Its drawback is that it requires the file to exist on disk so we
have to explicitly extract it from the zipfile and save it to
a temporary file
* The last choice is to use exec to execute the module:
* https://github.com/abadger/ansible/blob/f47a4ccc76/lib/ansible/executor/module_common.py#L175
* The code we would have to maintain for this looks pretty clean.
In the wrapper we create a ModuleType, set __file__ on it, read
the module's contents in from the zip file and then exec it.
* Drawbacks: We still have to explicitly extract the file's contents
from the zip archive instead of letting python's import mechanism
handle it.
* Exec also has hidden performance issues and breaks certain
assumptions that modules could be making about their own code:
http://lucumr.pocoo.org/2011/2/1/exec-in-python/
Our plan is to use imp.load_module() for now, deprecate the use of
__file__ in modules, and switch to zipimport once the deprecation
period for __file__ is over (without monkeypatching a fake __file__ in
via AnsibleModule).
* Rename the name of the AnsiBallZ wrapped module
This makes it obvious that the wrapped module isn't the module file that
we distribute. It's part of trying to mitigate the fact that the module
is now named __main)).py in tracebacks.
* Shield all wrapper symbols inside of a function
With the new import code, all symbols in the wrapper become visible in
the module. To mitigate the chance of collisions, move most symbols
into a toplevel function. The only symbols left in the global namespace
are now _ANSIBALLZ_WRAPPER and _ansiballz_main.
revised porting guide entry
Integrate code coverage collection into AnsiballZ.
ci_coverage
ci_complete
* Documentation change for resizefs
Changed documentation to match the default value of resizefs set in the code.
Added a note on the resizefs use on the example utilizing it.
* Remove test now it validates fine
* Update dnsimple-python minimum version to 1.0.0 as it supports API v2 and API v1 is deprecated.
* Update examples.
* Update documentation.
Fixes: #42495
Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>
* The module now correctly sets the timezone in both the config file and
in /etc/localtime; while hwclock is set in both the config and
/etc/adjtime.
* Module checks if the timezone is actually set by checking
/etc/localtime. Before it only checked if it was set in the config file.
* Fixed module not setting the timezone on RedHat systems if
/etc/localtime was a symbolic link.
* Fixed module failures in case of missing config files or incorrect data
in them.
* Added a lot of integrations tests to cover most of these situations.
* cs_instance: implement host migration support
* fix build
* fail fast on update if user is not admin
* improve tests a bit
* expunge it
* fix typo
* disable temporarly verify for host on starting instance.
* fixing azure sanity tests
* fixing sanity
* fixing some tags issues
* removed unnecessary things from managed disk
* fixed location problem
* more sanity fixes
* sanity test fixes
* final sanity fixes?
* final fixes again
* undo changes related to container instance
* removed container instance
* readd again
* fixed stupid mistake
* removed _azure from changes
* one more mistake
* Set encrypted as default and fix empty password reporting changed
* Starting with Postgres 10 `UNENCRYPTED` passwords are removed and
because of that this module fails with the default `encrypted=no`.
Also encrypted passwords are suported since version 7.2
(https://www.postgresql.org/docs/7.2/static/sql-createuser.html) which
went EOL in 2007 and since 7.3 it is the default. Because of this it
makes a lot more sense to make `encrypted=yes` the default. This won't
break backward compatibility, the module would just update the user's
password in the DB in the hashed format and everything else will work
like before. It's also a security bad practice to store passwords in
plain text. fixes#25823
* There was also a bug with `encrypted=yes` and an empty password always
reported as changed.
* Improved documentation for `encrypted`/`password` parameters, and
removed some obsolete notes about passlib.
* Fix clearing user's password to work with all versions of Postgres
* Add tests for clearing the user password
* Fix documentation atfer rebase
* Add changelog fragment
* Modifying cnos-facts, cnos_command and cnos-config in line with the design followed in Ansible. Adding unit test cases for these modules. Added plugins to support them.
* Removing doc fragment conflicts with other modules
* Replacing show with display
* fix problem with documentation and param definition difference
* removed some E324 from ignore.txt
* fixed mistake
* remove one more E324
* removed function app
* fixing append tags
* leaving append tags for later
This PR includes:
- Fixes to the majority of module validation issues
(deliberate inconsistencies between docs and arg_spec)
- Removal of deprecated parameters 'method' and 'protocols'
- A few typos in the documentation
There are still some left-over validation errors, some are deliberate
(like doc strings as default to indicate ranges, etc.)
* Allow subspec defaults to be processed when the parent argument is not supplied
* Allow this to be configurable via apply_defaults on the parent
* Document attributes of arguments in argument_spec
* Switch manageiq_connection to use apply_defaults
* add choices to api_version in argument_spec
* vdirect modules: fix 'import' sanity test
* Remove passing file from import skip list.
* vdirect modules: fix validate-modules warnings
- Arguments with a default should not be marked as required
- add choices in doc
* vdirect_runnable: use formatting function
* a refactor of pool member and node modules to be inline with current f5 conventions
* Added priority_group_activation to pools
* various other small convention fixes and bug fixes
* Adds gnat provisioning to bigip_provision
* Adds special handling for AFM in bigip_provision
* Add device rebooting for provisioning as necessary
* Refactored route domain module to be inline with current f5 conventions
* Minor refactors across modules
* Use arg_spec type for comparisons on default and choices
* Further improve type casting
* Make sure to capture output in more places
* Individually report invalid choices
* Update ignore.txt after resolving merge conflicts
* Clean up Grafana docs a bit
But more is needed, default values, missing choices, proper
descriptions, actual sentences :-)
* Remove validate-modules entries
Remove module from ignore lists and some documentation fix in
digital_ocean_block_storage and digital_ocean module.
Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>
* Ensure we merge doc fragments early, for comparisons
* Perform boolean conversion from arg_spec data too
* Update valdiate-modules ignore.txt due to recent changes
Enforce module deprecation.
After module has reached the end of it's deprecation cycle we will replace it with a docs stub.
* Replace deprecated modules with docs-only sub
* Use of deprecated past deprecation cycle gives meaningful message (see examples below)
* Enforce documentation.deprecation dict via `schema.py`
* Update `ansible-doc` and web docs to display documentation.deprecation
* Document that structure in `dev_guide`
* Ensure that all modules starting with `_` have a `deprecation:` block
* Ensure `deprecation:` block is only used on modules that start with `_`
* `removed_in` A string which represents when this module needs **deleting**
* CHANGELOG.md and porting_guide_2.5.rst list removed modules as well as alternatives
* CHANGELOG.md links to porting guide index
To ensure that meaningful messages are given to the user if they try to use a module at the end of it's deprecation cycle we enforce the module to contain:
```python
if __name__ == '__main__':
removed_module()
```
* Skip parameters that are being deprecated
So in most cases when parameters are deprecated, you may not want to
advertise them in the documentation. One reason for this is because
these parameters were not introduced within Ansible but predate
upstreaming them.
So this change avoids reporting parameters that are not documented and
are deprecated. It's only a small subset of the existing E322 errors.
* Add support for E323 with these changes
* Unsure about the other issues now
* Add better error message with E321
* Restore some erroneously remove files
* Readd false positives to ignore.txt
* compare arg+aliases between docs and argument_spec
* Add some special handling for the network modules provider options that also appear in the top level arg spec
* Fix error code for bigip_hostname
* Address merge conflicts due to changes in f5 modules
* Update validate-modules ignore based off a clean execution
* Address merge conflicts
* Address renamed module
* Address recent changes to modules
* Add ignore for ucs_ip_pool
* Update aci modules to get more reliable documentation comparison, but not mutating the module_utils aci_argument_spec
* Update ignore.txt after recent aci updates
* Add extra guard to ensure we handle provider special only for network modules
* Address additional changes to modules
* allow shells to have per host options, remote_tmp
added language to shell
removed module lang setting from general as plugins have it now
use get to avoid bad powershell plugin
more resilient tmp discovery, fall back to `pwd`
add shell to docs
fixed options for when frags are only options
added shell set ops in t_e and fixed option frags
normalize tmp dir usag4e
- pass tmpdir/tmp/temp options as env var to commands, making it default for tempfile
- adjusted ansiballz tmpdir
- default local tempfile usage to the configured local tmp
- set env temp in action
add options to powershell
shift temporary to internal envvar/params
ensure tempdir is set if we pass var
ensure basic and url use expected tempdir
ensure localhost uses local tmp
give /var/tmp priority, less perms issues
more consistent tempfile mgmt for ansiballz
made async_dir configurable
better action handling, allow for finally rm tmp
fixed tmp issue and no more tempdir in ballz
hostvarize world readable and admin users
always set shell tempdir
added comment to discourage use of exception/flow control
* Mostly revert expand_user as it's not quite working.
This was an additional feature anyhow.
Kept the use of pwd as a fallback but moved it to a second ssh
connection. This is not optimal but getting that to work in a single
ssh connection was part of the problem holding this up.
(cherry picked from commit 395b714120522f15e4c90a346f5e8e8d79213aca)
* fixed script and other action plugins
ensure tmpdir deletion
allow for connections that don't support new options (legacy, 3rd party)
fixed tests
* Add validation for the next to last line of a module
* Fix last error code
* Reduce to a single conditional
* Fix conditionals
* Move the final warnings statement to main() in mysql_replication
This patch is primarily a refactor to make the validate-modules arg-spec
no longer generate a traceback. It additionally includes removal of deprecated
code in the virtual server module.
The main patch is to remove the traceback generating code. There are
other small fixes that were made in addition to doing that.
* Removed re-def of cleanup_tokens.
* Changed parameter args to be keywords.
* Changed imports to include new module_util locations.
* Imports also include developing (sideband) module_util locations.
* Changed to using F5Client and plain AnsibleModule to prevent tracebacks caused by missing libraries.
* Removed init and update methods from most Parameter classes (optimization) as its now included in module_utils.
* Changed module and module param references to take into account the new self.module arg.
* Minor bug fixes made during this refactor.
The main purpose of this patch is to do the refactor that
supports replacing tracebacks with fail_json. Additionally, the
following was done.
* Removed re-def of cleanup_tokens.
* Changed parameter args to be keywords.
* Changed imports to include new module_util locations.
* Imports also include developing (sideband) module_util locations.
* Changed to using F5Client and plain AnsibleModule to prevent tracebacks caused by missing libraries.
* Removed init and update methods from most Parameter classes (optimization) as its now included in module_utils.
* Changed module and module param references to take into account the new self.module arg.
* Minor bug fixes made during this refactor.
Primarily, this patch contains refactors to remove tracebacks that
are generated when libraries are missing. There is also,
* Removed re-def of cleanup_tokens.
* Changed parameter args to be keywords.
* Changed imports to include new module_util locations.
* Imports also include developing (sideband) module_util locations.
* Changed to using F5Client and plain AnsibleModule to prevent tracebacks caused by missing libraries.
* Removed init and update methods from most Parameter classes (optimization) as its now included in module_utils.
* Changed module and module param references to take into account the new self.module arg. Minor bug fixes made during this refactor.
This patch was primarily an effort to reduce traceback errors for
work that sivel was doing. Part of (and in some cases in addition to)
that, the following was done.
* Removed re-def of cleanup_tokens.
* Changed parameter args to be keywords.
* Changed imports to include new module_util locations.
* Imports also include developing (sideband) module_util locations.
* Changed to using F5Client and plain AnsibleModule to prevent tracebacks caused by missing libraries.
* Removed init and update methods from most Parameter classes (optimization) as its now included in module_utils.
* Changed module and module param references to take into account the new self.module arg.
* Minor bug fixes made during this refactor.
* Update validate-modules arg_spec introspection to be faster, by only mocking the imports we explicitly list
* The use of types.MethodType in redhat_subscription wasn't py3 compatible, use partial instead
* Remove argument_spec import hacks, make them errors, we can ignore them with ansible-test
* Enable the --arg-spec flag for validate-modules
* Update validation test for new copyright
Ensure new modules without the new copyright header fail
validation
Ensure existing modules without copyright in top 20 lines fail
* Add documentation of 108 error
Create label in developing modules documentation so that
the validation page can point to it
* Ensure new style copyright header passes test!
* Refactor common network shared and platform specific code into package (part-1)
As per proposal #76 refactor common network shared and platform specific
code into sub-package.
https://github.com/ansible/proposals/issues/76
* ansible.module_utils.network.common - command shared functions
* ansible.module_utils.network.{{ platform }} - where platform is platform specific shared functions
* Fix review comments
* Fix review comments
* Use correct pip version in ansible-test.
* Add git fallback for validate-modules.
* Run sanity tests in a docker container.
* Use correct python version for sanity tests.
* Pin docker completion images and add default.
* Split pylint execution into multiple contexts.
* Only test .py files in use-argspec-type-path test.
* Accept identical python interpeter name or binary.
* Switch cloud tests to default container.
* Remove unused extras from pip install.
* Filter out empty pip commands.
* Don't force running of pip list.
* Support delegation for windows and network tests.
* Fix ansible-test python version usage.
* Fix ansible-test python version skipping.
* Use absolute path for log in ansible-test.
* Run vyos_command test on python 3.
* Fix windows/network instance persistence.
* Add `test/cache` dir to classification.
* Enable more python versions for network tests.
* Fix cs_router test.
* module_utils #Requires should not have .psm1 extension if "real" Powershell will ever execute them
* updated validate-modules to enforce this
* added check to disallow multi-module syntax on Ansible.ModuleUtils #Requires
* Correctly validate module name for modules with aliases
If a module has an alias (ie is a symlink) then we need to ensure that
DOCUMENTATION.module is set to the main name, not the aliased name
* formatting
* Add network value to support_by field.
* New support_by value, certified
* Deprecate curated in favor of certified
* Add conversion from 1.0 to 1.1 to metadata-tool
* Add supported by Red Hat field to ansible-doc output
We do want to allow certain from __future__ imports in modules that make
it easier to code compatible python2 and python3. Note that
unicode_literals is specifically left out and should never be allowed.
Now that python-3.4+ allows u"" there's no good reason to use
unicode_literals.
Also switch tables in the validate_modules documentation to simple table format
* Make Reporter class hold all results, move line/col into results, and out of message
* Move line/col out of message for YAML parser errors
* We have lineno for the DOC var, use it for YAML parser errors
* Remove valdiate-modules files from legacy-files
* pep8 indentation fixes
* Add todo for line/col in _validate_docs_schema
* Added test for 'RETURN' field in validate-modules
* print the field being tested.
Useful when the RETURN structure is complex.
* Fixed schema after CI traceback fail
* Fixed list_string_types
* Fixed line in 319 code for RETURN
* Big testing doc refactor
* Combine all the testing documentation in to one place to make it easier to find
* Convert everything to RST
* Create testing_network guide
* Create testing landing page
* For each section detail "how to run" and "how to extend testing"
* More examples
* Lots more detail
* Improve PEP8 compatibility
* Fix Python 3 incompatibility
Is prohibited to mutate OrderedDict during iteration through it so
is better to add records with error or warning to empty dictionary
instead of delete records from copy of dictionary during iterating.
* Decode output of subprocess from bytes to unicode.
* Add Python 3 support for validate-modules test.
Fix#18367
Made ansible-doc more plugin agnostic
We can have docs in lookup, callback, connectionm strategy, etc
Use first docstring and make pepizis happy
generalized module_docs to plugin_docs
documented cartesian, ssh, default, jsonfile, etc as examples
changed lack of docs to warning when listing
made smarter about bad docstrings
better blacklisting
added handling of options/config/envs/etc
move blacklist to find_plugins, only need once
Changes to the metadata format were approved here:
https://github.com/ansible/proposals/issues/54
* Update documentation to the new metadata format
* Changes to metadata-tool to account for new metadata
* Add GPL license header
* Add upgrade subcommand to upgrade metadata version
* Change default metadata to the new format
* Fix exclusion of non-modules from the metadata report
* Fix ansible-doc for new module metadata
* Exclude metadata version from ansible-doc output
* Fix website docs generation for the new metadata
* Update metadata schema in valiate-modules test
* Update the metadata in all modules to the new version
Raise the bar for module `DOCUMENTAION`
This validator update was used to find the issues in https://github.com/ansible/ansible/pull/22297/files
**Validation**
* Updated Validation and docs to enforce more (items fixed in https://github.com/ansible/ansible/pull/22297/files)
* Use `suboptions` to document complex options
* Validate module name
* Validate deprecated modules have correct ANSIBLE_METADATA
**Module Documentation Generation**
* Document `suboptions:` Example https://gist.github.com/gundalow/4bdc3669d696268328ccc18528cc6718
* Tidy up HTML generation (valid HTML, no empty lists, etc)
**Documentation**
* Clarify the steps for deprecating a module
* Use correct RST headings
* Document `suboptions:` (options)
* Document `contains:` (returns)
**Details**
The aim is to get this (and corresponding module updates) complete by the time `devel` becomes `2.4`, as this allows us to raise the bar for new modules
Example `suboptions` https://gist.github.com/gundalow/4bdc3669d696268328ccc18528cc6718
The aim is to get this PR integrated into `devel` *before* we branch `stable-2.3`, this will allows us to:
* Raise the bar for new modules in 2.4
* Ensure the generated module documentation for 2.3 and higher is improved, important as we will be doing versioned docs moving forward.
* Fix string formatting
* Provide better tracebacks
* When options is None and extends_documentation_fragment is in use, add an error that options must be a dict
* If options was specified and not a dict, then error
* Re-enable module comparisons, specifically for new module detection and for finding new options/arguments
* Only do new module checks in shippable, local will display warning
* Update validate-modules
* Validates ANSIBLE_METADATA
* Ensures imports happen after documentation vars
* Some pep8 cleanup
* Clean up some left over unneeded code
* Update modules for new module guidelines and validate-modules checks
* Update imports for ec2_vpc_route_table and ec2_vpc_nat_gateway
