* excludes scenario guides from core docs, splits porting guides and roadmaps, symlinks indices to create index.html pages, and adds .gitignore entries for conf.py and the toplevel index.rst files generated by the docs build
This solution builds three types of docs:
* ansible-2.10 and earlier: all the docs. Handle this via `make webdocs
ANSIBLE_VERSION=2.10`
* ansible-3 and later: a subset of the docs for the ansible package.
Handle this via `make webdocs ANSIBLE_VERSION=3` (change the
ANSIBLE_VERSION to match the version being built for.
* ansible-core: a subset of the docs for the ansible-core package.
Handle this via `make coredocs`.
* `make webdocs` now always builds all the collection docs
* Use `make coredocs` to limit it to core plugins only
* The user specifies the desired version. If no ANSIBLE_VERSION is specified, build plugins for the latest release of ansible
Co-authored-by: Toshio Kuratomi <a.badger@gmail.com>
Co-authored-by: Matt Clay <matt@mystile.com>
* Initial import of modified version of alikins' code
* Add unit testing for new Role methods
* Fix validate_arg_spec module for sanity test. Add test_include_role_fails.yml integration test from orig PR.
* Add testing of suboptions
* Use new ArgumentSpecValidator class instead of AnsibleModule
* fix for roles with no tasks, use FQ name of new plugin
* Add role dep warning
* Ensure there is a single source of collection metadata
* Allow collection subdirs to be detected by a galaxy.yml or MANIFEST.json
* Add documentation about installing and downloading collection directories
* Add an example for downloading a git repository
* Update documented valid metadata sources for installing git repositories
Co-authored-by: Sviatoslav Sydorenko <wk.cvs.github@sydorenko.org.ua>
Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com>
##### SUMMARY
One of the parameters to the slaac filter was unquoted causing a crash:
```
template error while templating string: expected token 'end of print statement', got ':'. String: {{ fdcf:1894:23b5:d38c:0000:0000:0000:0000 | slaac('c2:31:b3:83:bf:2b') }}
```
This adds the missing quotes.
##### ISSUE TYPE
- Docs Pull Request
+label: docsite_pr
##### SUMMARY
Added `[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12` to the Powershell scripts that use a file download. If not specified the script won't be allowed to download data from the mentioned URL's.
##### ISSUE TYPE
- Docs Pull Request
+label: docsite_pr
* Allow restricting config values to enumerated list
* dont document internal entries
* also ignore private defs for ansible-config
* remove invalid value from tests
* added porting entry
##### SUMMARY
<!--- Your description here -->
single_list must be transformed to a list of pairs before feeding it into dict()
##### ISSUE TYPE
- Docs Pull Request
+label: docsite_pr
Adds a note pointing to the datetime documentation as to_datetime does not use the time library but instead uses datetime.
Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com>
The standard Port for ansible winrm is set to 5986/HTTPS.
To be able to use Kerberos, you need to set ansible_port: 5985/HTTP otherwiese you get error message or timeout.
HTTPS is not needed for environments with Kerberos, since kerberos has server identification built in to the protocoll.
FYI: HTTP traffic will by default also be encrypted when using kerberos
* ExecutionPolicy default value is RemoteSigned
##### SUMMARY
In Windows setup steps, settings `ExecutionPolicy` is restored to value `Restricted`. But actually default value for Windows server is not `Restricted` but `RemoteSigned` ([source](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_execution_policies?view=powershell-7.1#default)).
I have got issue with `win_dsc` because `ExecutionPolicy` was `Restricted`.
##### ISSUE TYPE
- Docs Pull Request
+label: docsite_pr
* Add changelog fragment
* Apply suggestions from code review
Co-authored-by: Sandra McCann <samccann@redhat.com>
* Change example to use role params to represent the documented outcome. Fixes#68922
* Add notes about how vars vs role params affect variable scoping, and how lazy evaluation and role-deduplicating is affected. Fixes#72650
* link to term
* Add link to all module and plugin indexes.
* Use glob setting for toctree.
* Explicitly include new file.
* Move all_plugins one level up.
* Revert "Move all_plugins one level up."
This reverts commit bd47e82ead.
* Revert "Explicitly include new file."
This reverts commit 74ae50a734.
* Adjust .gitignore
* Revert "Revert "Explicitly include new file.""
This reverts commit f30d99c861.
* Fix docs make clean
Now that there's a static file in rst/collections, we have to be more
explicit about how we clean the generated files out of that directory.
Co-authored-by: Toshio Kuratomi <a.badger@gmail.com>
* Update to the ansible package roadmap for 3.0.0
* Rename files for the ansible roadmap from 2.11 to 3.0
Co-authored-by: Sandra McCann <samccann@redhat.com>
Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com>
* Add a note about - data structure returned from register variables
needs to be parsed using ``to_json | from_json`` in order to
get correct result.
* Add examples for starts_with and contains
Fixes: https://github.com/ansible-collections/community.general/issues/320
Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>
Fix the order of the arguments for ansible.netcommon.reduce_on_network. Pass the network as the argument and the list of IP addresses as the filter input.
##### SUMMARY
Make clear that `ansible_play_name` is the name attribute from the play and not the file name of the playbook.
improves #57361
##### ISSUE TYPE
- Docs Pull Request
+label: docsite_pr
* Clarify collection paths in docs, fix rst syntax, rephrase docs about using collection from folder/local git
Co-authored-by: Felix Fontein <felix@fontein.de>
* Emit warning when running on the controller with a Python older than 3.8
* Add spaces
Co-authored-by: Matt Clay <matt@mystile.com>
* and more spaces
Co-authored-by: Matt Clay <matt@mystile.com>
* s/Py/Python/
Co-authored-by: Matt Clay <matt@mystile.com>
* Add note to Control node requirements about Py3.8 requirement
* Add collection_name to deprecated call
* more spaces
Co-authored-by: Sviatoslav Sydorenko <wk.cvs.github@sydorenko.org.ua>
* Clarify that we are only packaging for py3.8+
Co-authored-by: Matt Clay <matt@mystile.com>
Co-authored-by: Sviatoslav Sydorenko <wk.cvs.github@sydorenko.org.ua>
* GitHub is removing the underlying API used to implement the `login` command. Since the general consensus seems to be that relatively nobody currently uses this command (in favor of explicit token passing), support was simply removed for interactive login. If a future need arises, this command should be reimplemented via OAuth Device Auth Grants.
* login or role login commands now produce a fatal error with a descriptive message
* updated 2.10 and 2.11 porting guide entries
* remove dead code/config, update messages and porting guides
* VMware: scenario guide for vmware_tools connection plugin
Scenario doc to guide user about the usage of vmware_tools
using connection plugin.
Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>
* review comments
Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>
When validate_certs is True and user has custom SSL
certificate path, user can use ``REQUESTS_CA_PATH``
in ``environment`` parameter of task to specify this path.
Fixes: https://github.com/ansible-collections/community.vmware/issues/49
Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>
* Fixing missing hosts entry under the group dict.
* Added missing 'vars:' key
* Reordering arguments for consistency with the format displayed by "ansible-playbook --help"
* Fixing contradictory text
beside the fact that naming the variable to specify the number of machines executed in *parallel* is named *serial* - the number of hosts chosen in this example is not optimal, either: 2x2 = 4; so - 3 hosts in 2 batches should clear things up a little
* Add support for GSSAPI/Kerberos to urls.py
* Test out changes with the latest test container
* Get remote hosts working
* Fix up httptester_krb5_password reader
* Fix tests for opensuse and macOS
* Hopefully last lot of testing changes
* Dont do CBT on macOS
* Fixes from review
* Validate removal versions.
* Validate that removal collection versions and version_added collection versions conform to semver spec.
* Validate removal version numbers in meta/runtime.yml.
* Stricter validation for isodates (f.ex. YYYY-M-D is not allowed).
* Improve error reporting.
* Validate removal collection versions.
Co-authored-by: Andrew Klychkov <aaklychkov@mail.ru>
* DOCS: updates intersphinx references for docs links
* TESTS: Raise the number of bytes scanned to determine if a file is binary. The newest ansible-2.10.inv file has its first null byte at position 2261. 4096 is still a cheap chunksize to read so it still makes sense to raise this.
Co-authored-by: Alicia Cozine <acozine@users.noreply.github.com>
Co-authored-by: Toshio Kuratomi <a.badger@gmail.com>
* [docs] add porting guide for DNF GPG validation
Change:
- This was a breaking change (security fix), but I neglected to add a
porting guide entry for it previously.
Tickets:
- Refs #71537
- Refs #71539
- Refs #71540
- Refs #71541
Signed-off-by: Rick Elrod <rick@elrod.me>
* changes from sivel
Signed-off-by: Rick Elrod <rick@elrod.me>
The setup module can now filter out multiple pattern by providing a list
to the filter parameter instead of just a string. Single string sill
works. Previous behaviour remains.
(cherry picked from commit b5c36dac483fdd74d6c570d77cc8f3e396720366)
nitzmahone's blog nicely explained why Windows is not supported
as Ansible controller. Link that in documentation so users can
read about it.
Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>
This script is mostly unmaintained and relies on the deprecated and
unmaintained `boto` library. Featuring it prominently in the docs
leads to many new users using it instead of the supported `aws_ec2`
inventory plugin.
##### SUMMARY
Per #67913, when comparing dependencies, Ansible takes into account parameters, tags and the when clause in determining whether a role is a duplicate or not.
##### ISSUE TYPE
- Docs Pull Request
+label: docsite_pr
* quick fix to change main back to devel
* Update docs/docsite/rst/dev_guide/developing_collections.rst
Co-authored-by: Felix Fontein <felix@fontein.de>
Change:
- Now sends meta tasks to the task start callback
- Lets callback plugins opt-in to receiving implicit tasks
Test Plan:
- New integration tests
Tickets:
- Indirectly fixes#71007 by allowing custom callbacks with this data
Signed-off-by: Rick Elrod <rick@elrod.me>
ini-style inventory does not support Ansible Vault password.
This fixes network_best_practices_2.5 doc.
Fixes: #69039
Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>
MacOSX seems to want bare `+` whereas GNU expr wants escaped `+` (`\+`)
to mean match one or more. Use `\{1,\}` instead which will match one or
more on both MaxOSX and GNU-using systems.
Fixes#71053
* [docs] 2.7 is EOL, add 2.10 which is almost out
- Remove 2.7 support from the maintenance schedule
- Add 2.10 which is in RC and will be out soon enough.
Signed-off-by: Rick Elrod <rick@elrod.me>
* Update docs/docsite/rst/reference_appendices/release_and_maintenance.rst, fix table and separate ansible-base from ansible, fix rstcheck errors, clean up sections, explain the two packages
Co-authored-by: Sandra McCann <samccann@redhat.com>
Co-authored-by: Rick Elrod <rick@elrod.me>
* Revert "Change default file permissions so they are not world readable (#70221)"
This reverts commit 5260527c4a.
* Revert "Fix warning for new default permissions when mode is not specified (#70976)"
This reverts commit dc79528cc6.
ansible_play_batch lists the currently targeted host(s) in the serial/batch, while
ansible_play_hosts lists all the hosts which will be targeted by the play.
Co-authored-by: Klaus Frank <agowa338@users.noreply.github.com>
Co-authored-by: Felix Fontein <felix@fontein.de>
Co-authored-by: Abhijeet Kasurde <akasurde@redhat.com>
The ansible collection repository correctly renamed their default branch from `master` to `main`, which has caused a number for broken urls. This PR fixes those urls.
Change:
- Allow systems to declare multiple virt techs. For example if a system
is both a docker container, but virtualized on KVM, show both. If a
system is set up to run virtualbox and KVM VMs, show both.
- This is done by introducing new facts keys:
- virtualization_tech_guest
- virtualization_tech_host
- Backwards compatibility is preserved by keeping track of the previous
return-points and refusing to update those keys after we would have
returned, but now returning them at the end, so that the new keys can
accumulate their data.
Test Plan:
- Local
- CI
Tickets:
- Refs #66304
- Refs #17151
- Refs #17058
- Probably others
Signed-off-by: Rick Elrod <rick@elrod.me>
* Fix tty_ify bugs and refactor
* Move tty_ify() and supporting attributes to the DocCLI class as that's
the only thing using it.
* Add unittest for the code.
* Fix a bug where the substitution macros can be detected when they are
a part of another word.
* Add support for L(), R(), and HORIZONTALLINE which were added to the
website docs many years ago.
* Update test/units/cli/test_doc.py
Co-authored-by: Matt Clay <matt@mystile.com>
Co-authored-by: Matt Clay <matt@mystile.com>
Change:
- Use `chmod +a` in the fallback chain to allow MacOS to use ACLs to
allow an unprivileged user to become an unprivileged user.
Test Plan:
- CI, new tests
Tickets:
- Fixes#70648
Signed-off-by: Rick Elrod <rick@elrod.me>
Change:
- Previously CachePluginAdjudicator#flush only removed entries from the
cache backend that it knew about by using them earlier. Now it calls
the underlying plugin's flush() method.
Test Plan:
- New unit tests
Tickets:
- Fixes#68770
Signed-off-by: Rick Elrod <rick@elrod.me>
* banner should not be placed on pages with 'devel' in their titles
* Update docs/docsite/_themes/sphinx_rtd_theme/ansible_banner.html
Co-authored-by: Sviatoslav Sydorenko <wk.cvs.github@sydorenko.org.ua>
* Only match paths at the beginning
Co-authored-by: Alicia Cozine <acozine@users.noreply.github.com>
Co-authored-by: Sviatoslav Sydorenko <wk.cvs.github@sydorenko.org.ua>
Co-authored-by: Sviatoslav Sydorenko <webknjaz@redhat.com>
There are links from the scenario guides to collections but collections
docs aren't built in testing or locally when we're on the devel branch.
Due to that we need to make sure those references resolve to the
production docsite. We can use intersphinx to make sure that happens.
* The test for binary files wasn't reading enough of the file.
Checking for null bytes in the first 1024 bytes failed to diagnose the
ansible_2_10.inv file as binary
Update the docs to guide users to use `ansible-runner` instead of using Python API directly. In many use cases, executing Ansible playbooks are sufficient. In those use cases, `ansible-runner` is easier and much stable to use comparing with Python API, but there is no mention of it.
* Fix changelog link title.
* Rename Ansible 2.10 and 2.11 porting guides to Ansible-base porting guides.
* Add stub for automatically generated 2.10 porting guide.
* Move things that should not be in the ansible-base porting guide to the ansible porting guide.
* Apply changes to base porting guides.
* Add remark that ansible-base is mainly for developers.
* Ansible Base -> Ansible-base
* Fix link in base porting guide.
* Add generated porting guide.
* Use same header signs as antsibull-changelog's RST builder.
* Update generated porting guide.
* document how to migrate between collections
* Apply suggestions from code review
Co-authored-by: John R Barker <john@johnrbarker.com>
Co-authored-by: Felix Fontein <felix@fontein.de>
Follow up to #70221
Related to #67794
CVE-2020-1736
When set_mode_if_different() is called with mode of 'None', ensure we issue
a warning about the change in default permissions.
Add integration tests to ensure the warning works properly.
* Fix tests
- actually use custom module 🤦♂️
- verify file permission on created files
- use remote_tmp_dir so we're ready for split controller
- improve test module so we can skip the call to set_fs_attributes_if_different()
- fix tests for CentOS 6
Change:
- Clarify that not passing `--tags` will cause `ansible_run_tags` to
default to `["all"]`.
- Add some extra coverage around `ansible_run_tags`
Test Plan:
- New integration and unit tests
Tickets:
- Fixes#69619
Signed-off-by: Rick Elrod <rick@elrod.me>
- Combine remote and local debugging instructions.
- Update the example code to match current AnsiballZ structure and behavior
- Change reference name and update references
- Clarify how PYTHON path is modified
- Also add note about other remote debugging tools.
Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com>
* Also validate top-level version_added.
* Fix error code.
* Produce same version_added validation error in schema than in code (and stop returning it twice).
* Return correct error codes for invalid version_added for options and return values.
* Add changelog.
* Fix forgotten closing braket.
* Accept 'historical' for some top-level version_added.
PR #70446: it's a follow-up for #70445.
It includes a merge of `examples/scripts/uptime.py` and a similar
code snippet from `docs/docsite/rst/dev_guide/developing_api.rst`.
This patch also changes the docs RST file to include contents of
the example file instead of holding a copy of a similar code.
* Change default file permissions so they are not world readable
CVE-2020-1736
Set the default permissions for files we create with atomic_move() to 0o0660. Track
which files we create that did not exist and warn if the module supports 'mode'
and it was not specified and the module did not call set_mode_if_different(). This allows the user to take action and specify a mode rather than using the defaults.
A code audit is needed to find all instances of modules that call atomic_move()
but do not call set_mode_if_different(). The findings need to be documented in
a changelog since we are not warning. Warning in those instances would be frustrating
to the user since they have no way to change the module code.
- use a set for storing list of created files
- just check the argument spac and params rather than using another property
- improve the warning message to include the default permissions
* Format using `` instead of `, add line breaks for long lines, rephrase or remove useless text.
Move some text.
* Add clearer version of OpenSSh is affected by SCP bug
* Review some pages using ansible doc writing guide.
From what I have observed it is the block itself that doesn't support the name attribute rather than the tasks inside the block.
* Update docs/docsite/rst/user_guide/playbooks_blocks.rst
Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com>
* Build documentation for Ansible-2.10 (formerly known as ACD).
Builds plugin docs from collections whose source is on galaxy
The new command downloads collections from galaxy, then finds the
plugins inside of them to get the documentation for those plugins.
* Update the python syntax checks
* docs builds can now require python 3.6+.
* Move plugin formatter code out to an external tool, antsibull-docs.
Collection owners want to be able to extract docs for their own
websites as well.
* The jinja2 filters, tests, and other support code have moved to antsibull
* Remove document_plugins as that has now been integrated into antsibull-docs
* Cleanup and bugfix to other build script code:
* The Commands class needed to have its metaclass set for abstractmethod
to work correctly
* Fix lint issues in some command plugins
* Add the docs/docsite/rst/collections to .gitignore as
everything in that directory will be generated so we don't want any of
it saved in the git repository
* gitignore the build dir and remove edit docs link on module pages
* Add docs/rst/collections as a directory to remove on make clean
* Split the collections docs from the main docs
* remove version and edit on github
* remove version banner for just collections
* clarify examples need collection keyword defined
* Remove references to plugin documentation locations that no longer exist.
* Perhaps the pages in plugins/*.rst should be deprecated
altogether and their content moved?
* If not, perhaps we want to rephrase and link into the collection
documentation?
* Or perhaps we want to link to the plugins which are present in
collections/ansible/builtin?
* Remove PYTHONPATH from the build-ansible calls
One of the design goals of the build-ansible.py script was for it to
automatically set its library path to include the checkout of ansible
and the library of code to implement itself. Because it automatically
includes the checkout of ansible, we don't need to set PYTHONPATH in
the Makefile any longer.
* Create a command to only build ansible-base plugin docs
* When building docs for devel, only build the ansible-base docs for
now. This is because antsibull needs support for building a "devel
tree" of docs. This can be changed once that is implemented
* When building docs for the sanity tests, only build the ansible-base
plugin docs for now. Those are the docs which are in this repo so
that seems appropriate for now.
A little further down the page is another index, ansible_loop.index, which shares a similar description but is 1 indexed.
Its zero indexed twin has a 0 suffix.
``ansible_loop.index`` The current iteration of the loop. (1 indexed)
``ansible_loop.index0`` The current iteration of the loop. (0 indexed)
To remove ambiguity around the usage of index_var, explicitly mention that this variable is 0 indexed.
Change:
Our handling of NetBSD virtualization facts led to facts that were just
plain incorrect. One example is reporting Xen even when the system is
running on something completely different (like KVM).
As stated by the reporter of #69352, NetBSD has a better sysctl setting
to use for this information, machdep.hypervisor.
This PR does the following:
- Try to use machdep.hypervisor sysctl value if the other sysctl values
we check don't end up with enough information to be useful
- Only look for /dev/xencons and assume Xen if nothing else works
(Really this should probably return 'unknown' since the file exists on
non-Xen systems and is not very useful).
- Add a few more patterns (Xen matches and also Hyper-V) to
VirtualSysctlDetectionMixin#detect_virt_product.
This change is slightly breaking:
- If the first two attempts at using sysctl worked before,
(machdep.dmi.system-product and machdep.dmi.system-vendor), they will
continue to work.
- For cases when those values didn't work, previously the existence of
/dev/xencons was checked, and if found, we reported 'xen' (even on
non-Xen systems when the file existed). After this PR, we try the
machdep.hypervisor sysctl key before still falling back to
/dev/xencons. This means that in some cases, we might go from
(wrongly) saying "xen" to giving a more accurate value such as "kvm"
or "Hyper-V".
Test Plan:
- Tested with local NetBSD VM and got 'kvm' instead of 'xen' back.
Tickets:
- Fixes#69352
Signed-off-by: Rick Elrod <rick@elrod.me>
* Add type for options in the sample module shown in Developing Modules, as this is required to have the tests being
green
* Remove duplicated strings: the same sentence is in "Python tips" and "Module security", keeping the
latter.
Previous version initialized the `TaskQueueManager` after calling
`Play.load()` while advertising a way to inject a custom library
location path. This caused the tasks loader not to find any custom
modules because it was triggered before the path was actually added
to the module loader.
This patch changes the order of the operations to ensure that the
customized `context.CLIARGS` actually influences things.
Resolves https://github.com/ansible/ansible/issues/69758.
If a local module has no documentation, the doc command will fail without any hints of what is wrong. Add another way to confirm the presence of a local module.
* Update docs/docsite/rst/dev_guide/developing_locally.rst
Co-authored-by: Abhijeet Kasurde <akasurde@redhat.com>
* Update docs/docsite/rst/dev_guide/developing_collections.rst
* add steps to create changelogs, add sentence about not using the tool
* add note for rerunning the command
Co-authored-by: Felix Fontein <felix@fontein.de>
* Add description of collections keyword
* Update based on feedback.
- Add link to become plugins.
- Add note about how the collections keyword works with roles.
* Update guide_gce.rst
The given example is not working as a SSH connection is not possible because of #59573. Instead, in this tutorial the default network should be used which allows SSH connections in most cases.
Co-authored-by: Sandra McCann <samccann@redhat.com>
* Updated docs/docsite/rst/dev_guide/developing_modules_documenting.rst, added documentation for R()
* added link to how to add anchors, anchor, and clarification on when to use each option
Co-authored-by: John R Barker <john@johnrbarker.com>
Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com>
Toshio Kuratomi