diff --git a/docs/docsite/rst/porting_guides/porting_guide_2.0.rst b/docs/docsite/rst/porting_guides/porting_guide_2.0.rst index 67a8c461c47..9efa1b810a9 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_2.0.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_2.0.rst @@ -42,7 +42,7 @@ uses key=value escaping which has not changed. The other option is to check for "{{ (ansible_version|version_compare('2.0', 'ge'))|ternary( 'test1_junk 1\\3' | regex_replace('(.*)_junk (.*)', '\\1 \\2') , 'test1_junk 1\\\\3' | regex_replace('(.*)_junk (.*)', '\\\\1 \\\\2') ) }}" * trailing newline When a string with a trailing newline was specified in the - playbook via yaml dict format, the trailing newline was stripped. When + playbook through yaml dict format, the trailing newline was stripped. When specified in key=value format, the trailing newlines were kept. In v2, both methods of specifying the string will keep the trailing newlines. If you relied on the trailing newline being stripped, you can change your playbook @@ -149,7 +149,7 @@ Should now be:: a: 1 * Setting any_errors_fatal on a task is no longer supported. This should be set at the play level only. -* Bare variables in the `environment` dictionary (for plays/tasks/etc.) are no longer supported. Variables specified there should use the full variable syntax: '{{foo}}'. +* Bare variables in the `environment` dictionary (for plays/tasks/and so on) are no longer supported. Variables specified there should use the full variable syntax: '{{foo}}'. * Tags (or any directive) should no longer be specified with other parameters in a task include. Instead, they should be specified as an option on the task. For example:: diff --git a/docs/docsite/rst/porting_guides/porting_guide_2.10.rst b/docs/docsite/rst/porting_guides/porting_guide_2.10.rst index 678c28edaa1..ff0a1eff690 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_2.10.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_2.10.rst @@ -43,8 +43,8 @@ Command Line ============ * The ``ansible-galaxy login`` command has been removed, as the underlying API it used for GitHub auth is being shut down. Publishing roles or - collections to Galaxy via ``ansible-galaxy`` now requires that a Galaxy API token be passed to the CLI via a token file (default location - ``~/.ansible/galaxy_token``) or (insecurely) via the ``--token`` argument to ``ansible-galaxy``. + collections to Galaxy through ``ansible-galaxy`` now requires that a Galaxy API token be passed to the CLI through a token file (default location + ``~/.ansible/galaxy_token``) or (insecurely) through the ``--token`` argument to ``ansible-galaxy``. Deprecated @@ -80,7 +80,7 @@ Plugins Lookup plugin names case-sensitivity ------------------------------------ -* Prior to Ansible ``2.10`` lookup plugin names passed in as an argument to the ``lookup()`` function were treated as case-insensitive as opposed to lookups invoked via ``with_``. ``2.10`` brings consistency to ``lookup()`` and ``with_`` to be both case-sensitive. +* Prior to Ansible ``2.10`` lookup plugin names passed in as an argument to the ``lookup()`` function were treated as case-insensitive as opposed to lookups invoked through ``with_``. ``2.10`` brings consistency to ``lookup()`` and ``with_`` to be both case-sensitive. Noteworthy plugin changes ------------------------- @@ -232,7 +232,7 @@ netbox.netbox - nb_inventory - Move around ``extracted_primary_ip`` to allow for ``config_context`` or ``custom_field`` to overwrite. (#377) - nb_inventory - Services are now a list of integers due to NetBox 2.10 changes. (#396) - nb_lookup - Allow ID to be passed in and use ``.get`` instead of ``.filter``. (#376) -- nb_lookup - Allow ``api_endpoint`` and ``token`` to be found via env. (#391) +- nb_lookup - Allow ``api_endpoint`` and ``token`` to be found through env. (#391) Deprecated Features ------------------- @@ -567,7 +567,7 @@ netbox.netbox ``netbox.netbox.netbox`` would be used for both inventory plugin and lookup plugin, but in different contexts so no collision will arise, but confusion will. I renamed the lookup plugin to ``nb_lookup`` so it will be used with the FQCN ``netbox.netbox.nb_lookup``. The inventory plugin will now be called within an inventory file by ``netbox.netbox.nb_inventory`` -- To pass in integers via Ansible Jinja filters for a key in ``data`` that +- To pass in integers through Ansible Jinja filters for a key in ``data`` that requires querying an endpoint is now done by making it a dictionary with an ``id`` key. The previous behavior was to just pass in an integer and it was converted when normalizing the data, but some people may have names @@ -674,7 +674,7 @@ community.kubernetes - k8s - Module migrated from Ansible 2.9 to Kubernetes collection. - k8s_auth - Module migrated from Ansible 2.9 to Kubernetes collection. - k8s_config_resource_name - Filter plugin migrated from Ansible 2.9 to Kubernetes collection. -- k8s_exec - New module for executing commands on pods via Kubernetes API (https://github.com/ansible-collections/community.kubernetes/pull/14). +- k8s_exec - New module for executing commands on pods through Kubernetes API (https://github.com/ansible-collections/community.kubernetes/pull/14). - k8s_exec - Return rc for the command executed (https://github.com/ansible-collections/community.kubernetes/pull/158). - k8s_info - Module migrated from Ansible 2.9 to Kubernetes collection. - k8s_log - New module for retrieving pod logs (https://github.com/ansible-collections/community.kubernetes/pull/16). @@ -952,7 +952,7 @@ community.vmware community.zabbix ~~~~~~~~~~~~~~~~ -- zabbix_proxy (module) - deprecates ``interface`` sub-options ``type`` and ``main`` when proxy type is set to passive via ``status=passive``. Make sure these suboptions are removed from your playbook as they were never supported by Zabbix in the first place. +- zabbix_proxy (module) - deprecates ``interface`` sub-options ``type`` and ``main`` when proxy type is set to passive through ``status=passive``. Make sure these suboptions are removed from your playbook as they were never supported by Zabbix in the first place. f5networks.f5_modules ~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/docsite/rst/porting_guides/porting_guide_2.3.rst b/docs/docsite/rst/porting_guides/porting_guide_2.3.rst index d20d74ece9e..9a66c23d0f1 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_2.3.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_2.3.rst @@ -92,7 +92,7 @@ Use of multiple tags Specifying ``--tags`` (or ``--skip-tags``) multiple times on the command line currently leads to the last specified tag overriding all the other specified tags. This behaviour is deprecated. In the future, if you specify --tags multiple times the tags will be merged together. From now on, using ``--tags`` multiple times on one command line will emit a deprecation warning. Setting the ``merge_multiple_cli_tags`` option to True in the ``ansible.cfg`` file will enable the new behaviour. -In 2.4, the default will be to merge the tags. You can enable the old overwriting behavior via the config option. +In 2.4, the default will be to merge the tags. You can enable the old overwriting behavior through the config option. In 2.5, multiple ``--tags`` options will be merged with no way to go back to the old behaviour. @@ -219,8 +219,8 @@ Will result in: transport: cli host: "{{ ansible_host }}" -delegate_to vs ProxyCommand ---------------------------- +ProxyCommand replaces delegate_to +--------------------------------- The new connection framework for Network Modules in Ansible 2.3 that uses ``cli`` transport no longer supports the use of the ``delegate_to`` directive. @@ -228,6 +228,6 @@ In order to use a bastion or intermediate jump host to connect to network device transport, network modules now support the use of ``ProxyCommand``. To use ``ProxyCommand`` configure the proxy settings in the Ansible inventory -file to specify the proxy host via ``ansible_ssh_common_args``. +file to specify the proxy host through ``ansible_ssh_common_args``. For details on how to do this see the :ref:`network proxy guide `. diff --git a/docs/docsite/rst/porting_guides/porting_guide_2.4.rst b/docs/docsite/rst/porting_guides/porting_guide_2.4.rst index 52bb0e3c914..d58ae48d138 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_2.4.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_2.4.rst @@ -25,7 +25,7 @@ Ansible will not support Python 2.4 or 2.5 on the target hosts anymore. Going fo Inventory ========= -Inventory has been refactored to be implemented via plugins and now allows for multiple sources. This change is mostly transparent to users. +Inventory has been refactored to be implemented through plugins and now allows for multiple sources. This change is mostly transparent to users. One exception is the ``inventory_dir``, which is now a host variable; previously it could only have one value so it was set globally. This means you can no longer use it early in plays to determine ``hosts:`` or similar keywords. @@ -63,7 +63,7 @@ Use of multiple tags Specifying ``--tags`` (or ``--skip-tags``) multiple times on the command line currently leads to the last one overriding all the previous ones. This behavior is deprecated. In the future, if you specify --tags multiple times the tags will be merged together. From now on, using ``--tags`` multiple times on one command line will emit a deprecation warning. Setting the ``merge_multiple_cli_tags`` option to True in the ``ansible.cfg`` file will enable the new behavior. -In 2.4, the default has change to merge the tags. You can enable the old overwriting behavior via the config option. +In 2.4, the default has change to merge the tags. You can enable the old overwriting behavior through the config option. In 2.5, multiple ``--tags`` options will be merged with no way to go back to the old behavior. @@ -124,7 +124,7 @@ The most notable difference to users is that vars plugins now get invoked on dem Inventory plugins ----------------- -Developers should start migrating from hardcoded inventory with dynamic inventory scripts to the new Inventory Plugins. The scripts will still work via the ``script`` inventory plugin but Ansible development efforts will now concentrate on writing plugins rather than enhancing existing scripts. +Developers should start migrating from hardcoded inventory with dynamic inventory scripts to the new Inventory Plugins. The scripts will still work through the ``script`` inventory plugin but Ansible development efforts will now concentrate on writing plugins rather than enhancing existing scripts. Both users and developers should look into the new plugins because they are intended to alleviate the need for many of the hacks and workarounds found in the dynamic inventory scripts. @@ -138,7 +138,7 @@ Users: Developers: -* If your callback does not inherit from ``CallbackBase`` (directly or indirectly via another callback), it will still work, but issue a deprecation notice. +* If your callback does not inherit from ``CallbackBase`` (directly or indirectly through another callback), it will still work, but issue a deprecation notice. To avoid this and ensure it works in the future change it to inherit from ``CallbackBase`` so it has the new options handling methods and properties. You can also implement the new options handling methods and properties but that won't automatically inherit changes added in the future. You can look at ``CallbackBase`` itself and/or ``AnsiblePlugin`` for details. * Any callbacks inheriting from other callbacks might need to also be updated to contain the same documented options diff --git a/docs/docsite/rst/porting_guides/porting_guide_2.7.rst b/docs/docsite/rst/porting_guides/porting_guide_2.7.rst index 27a6a99fc0b..0ab53655d08 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_2.7.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_2.7.rst @@ -40,7 +40,7 @@ One thing that this does affect is the ability to use :command:`/usr/bin/ansible a host which has Python-2.6. ``ansible-pull`` runs on the host being managed but it is a controller script, not a module so it will need an updated Python. Actively developed Linux distros which ship with Python-2.6 have some means to install newer Python versions (For instance, you can install -Python-2.7 via an SCL on RHEL-6) but you may need to also install Python bindings for many common +Python-2.7 through an SCL on RHEL-6) but you may need to also install Python bindings for many common modules to work (For RHEL-6, for instance, selinux bindings and yum would have to be installed for the updated Python install). @@ -123,8 +123,8 @@ If you are the author of a third-party module which uses ``__file__`` with ``Ans + package = os.path.join(module.tmpdir, to_native(deb.rsplit('/', 1)[1])) -Using a loop on a package module via squash_actions ---------------------------------------------------- +Using a loop on a package module through squash_actions +------------------------------------------------------- The use of ``squash_actions`` to invoke a package module, such as "yum", to only invoke the module once is deprecated, and will be removed in Ansible 2.11. diff --git a/docs/docsite/rst/porting_guides/porting_guide_2.8.rst b/docs/docsite/rst/porting_guides/porting_guide_2.8.rst index 4e0669410dd..1f3903476e8 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_2.8.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_2.8.rst @@ -347,7 +347,7 @@ Deprecated removed in 2.12. If you need the old behavior switch to ``FactCache.first_order_merge()`` instead. -* Supporting file-backed caching via self.cache is deprecated and will +* Supporting file-backed caching through self.cache is deprecated and will be removed in Ansible 2.12. If you maintain an inventory plugin, update it to use ``self._cache`` as a dictionary. For implementation details, see the :ref:`developer guide on inventory plugins`. @@ -543,7 +543,7 @@ Plugins * ``osx_say`` callback plugin was renamed into :ref:`say `. -* Inventory plugins now support caching via cache plugins. To start using a cache plugin with your inventory see the section on caching in the :ref:`inventory guide`. To port a custom cache plugin to be compatible with inventory see :ref:`developer guide on cache plugins`. +* Inventory plugins now support caching through cache plugins. To start using a cache plugin with your inventory see the section on caching in the :ref:`inventory guide`. To port a custom cache plugin to be compatible with inventory see :ref:`developer guide on cache plugins`. Porting custom scripts ====================== diff --git a/docs/docsite/rst/porting_guides/porting_guide_3.rst b/docs/docsite/rst/porting_guides/porting_guide_3.rst index 2f387bb9035..12ec21cd08e 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_3.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_3.rst @@ -262,7 +262,7 @@ community.general - The Google cloud inventory script ``gce.py`` has been migrated to the ``community.google`` collection. Install the ``community.google`` collection in order to continue using it. - archive - remove path folder itself when ``remove`` parameter is true (https://github.com/ansible-collections/community.general/issues/1041). - log_plays callback - add missing information to the logs generated by the callback plugin. This changes the log message format (https://github.com/ansible-collections/community.general/pull/442). -- passwordstore lookup plugin - now parsing a password store entry as YAML if possible, skipping the first line (which by convention only contains the password and nothing else). If it cannot be parsed as YAML, the old ``key: value`` parser will be used to process the entry. Can break backwards compatibility if YAML formatted code was parsed in a non-YAML interpreted way, e.g. ``foo: [bar, baz]`` will become a list with two elements in the new version, but a string ``'[bar, baz]'`` in the old (https://github.com/ansible-collections/community.general/issues/1673). +- passwordstore lookup plugin - now parsing a password store entry as YAML if possible, skipping the first line (which by convention only contains the password and nothing else). If it cannot be parsed as YAML, the old ``key: value`` parser will be used to process the entry. Can break backwards compatibility if YAML formatted code was parsed in a non-YAML interpreted way, for example ``foo: [bar, baz]``, will become a list with two elements in the new version, but a string ``'[bar, baz]'`` in the old (https://github.com/ansible-collections/community.general/issues/1673). - pkgng - passing ``name: *`` with ``state: absent`` will no longer remove every installed package from the system. It is now a noop. (https://github.com/ansible-collections/community.general/pull/569). - pkgng - passing ``name: *`` with ``state: latest`` or ``state: present`` will no longer install every package from the configured package repositories. Instead, ``name: *, state: latest`` will upgrade all already-installed packages, and ``name: *, state: present`` is a noop. (https://github.com/ansible-collections/community.general/pull/569). - proxmox_kvm - recognize ``force=yes`` in conjunction with ``state=absent`` to forcibly remove a running VM (https://github.com/ansible-collections/community.general/pull/849). @@ -314,7 +314,7 @@ dellemc.os10 ngine_io.cloudstack ~~~~~~~~~~~~~~~~~~~ -- Authentication option using INI files e.g. ``cloudstack.ini`` has been removed. The only supported option to authenticate is by using the module params with fallback to the ENV variables. +- Authentication option using INI files for example ``cloudstack.ini``, has been removed. The only supported option to authenticate is by using the module params with fallback to the ENV variables. - default zone deprecation - The `zone` param default value, across multiple modules, has been deprecated due to unreliable API (https://github.com/ngine-io/ansible-collection-cloudstack/pull/62). Major Changes @@ -392,7 +392,7 @@ kubernetes.core - k8s_* - Add support for vaulted kubeconfig and src (https://github.com/ansible-collections/kubernetes.core/pull/193). - k8s_auth - Module migrated from Ansible 2.9 to Kubernetes collection. - k8s_config_resource_name - Filter plugin migrated from Ansible 2.9 to Kubernetes collection. -- k8s_exec - New module for executing commands on pods via Kubernetes API (https://github.com/ansible-collections/kubernetes.core/pull/14). +- k8s_exec - New module for executing commands on pods through Kubernetes API (https://github.com/ansible-collections/kubernetes.core/pull/14). - k8s_exec - Return rc for the command executed (https://github.com/ansible-collections/kubernetes.core/pull/158). - k8s_info - Module migrated from Ansible 2.9 to Kubernetes collection. - k8s_log - New module for retrieving pod logs (https://github.com/ansible-collections/kubernetes.core/pull/16). @@ -409,7 +409,7 @@ netbox.netbox - nb_inventory - Move around ``extracted_primary_ip`` to allow for ``config_context`` or ``custom_field`` to overwrite. (#377) - nb_inventory - Services are now a list of integers due to NetBox 2.10 changes. (#396) - nb_lookup - Allow ID to be passed in and use ``.get`` instead of ``.filter``. (#376) -- nb_lookup - Allow ``api_endpoint`` and ``token`` to be found via env. (#391) +- nb_lookup - Allow ``api_endpoint`` and ``token`` to be found through env. (#391) ovirt.ovirt ~~~~~~~~~~~ diff --git a/docs/docsite/rst/porting_guides/porting_guide_4.rst b/docs/docsite/rst/porting_guides/porting_guide_4.rst index 003faba37f4..4e91a30d63e 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_4.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_4.rst @@ -194,7 +194,7 @@ Breaking Changes community.zabbix ~~~~~~~~~~~~~~~~ -- all roles now reference other roles and modules via their fully qualified collection names, which makes Ansible 2.10 minimum supported version for roles (see `issue 477 `_). +- all roles now reference other roles and modules through their fully qualified collection names, which makes Ansible 2.10 minimum supported version for roles (see `issue 477 `_). Deprecated Features ------------------- @@ -464,7 +464,7 @@ fortinet.fortios netbox.netbox ~~~~~~~~~~~~~ -- packages is now a required Python package and gets installed via Ansible 2.10+. +- packages is now a required Python package and gets installed through Ansible 2.10+. Removed Features ---------------- diff --git a/docs/docsite/rst/porting_guides/porting_guide_5.rst b/docs/docsite/rst/porting_guides/porting_guide_5.rst index f26d7fb2a17..6257ccd1f2c 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_5.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_5.rst @@ -114,7 +114,7 @@ Plugins * ``unique`` filter with Jinja2 < 2.10 is case-sensitive and now raise coherently an error if ``case_sensitive=False`` instead of when ``case_sensitive=True``. * Set theory filters (``intersect``, ``difference``, ``symmetric_difference`` and ``union``) are now case-sensitive. Explicitly use ``case_sensitive=False`` to keep previous behavior. Note: with Jinja2 < 2.10, the filters were already case-sensitive by default. -* ``password_hash``` now uses ``passlib`` defaults when an option is unspecified, e.g. ``bcrypt_sha256`` now default to the "2b" format and if the "2a" format is required it must be specified. +* ``password_hash``` now uses ``passlib`` defaults when an option is unspecified, for example ``bcrypt_sha256``, now default to the "2b" format and if the "2a" format is required it must be specified. Porting custom scripts ====================== @@ -572,7 +572,7 @@ community.routeros community.zabbix ~~~~~~~~~~~~~~~~ -- all roles now reference other roles and modules via their fully qualified collection names, which makes Ansible 2.10 minimum supported version for roles (See `issue 477 `_). +- all roles now reference other roles and modules through their fully qualified collection names, which makes Ansible 2.10 minimum supported version for roles (See `issue 477 `_). kubernetes.core ~~~~~~~~~~~~~~~ @@ -784,7 +784,7 @@ netapp.cloudmanager netbox.netbox ~~~~~~~~~~~~~ -- packages is now a required Python package and gets installed via Ansible 2.10+. +- packages is now a required Python package and gets installed through Ansible 2.10+. openvswitch.openvswitch ~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/docsite/rst/porting_guides/porting_guide_base_2.10.rst b/docs/docsite/rst/porting_guides/porting_guide_base_2.10.rst index 5a1bdb0b7ed..275de7250ef 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_base_2.10.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_base_2.10.rst @@ -36,8 +36,8 @@ Command Line ============ * The ``ansible-galaxy login`` command has been removed, as the underlying API it used for GitHub auth is being shut down. Publishing roles or - collections to Galaxy via ``ansible-galaxy`` now requires that a Galaxy API token be passed to the CLI via a token file (default location - ``~/.ansible/galaxy_token``) or (insecurely) via the ``--token`` argument to ``ansible-galaxy``. + collections to Galaxy through ``ansible-galaxy`` now requires that a Galaxy API token be passed to the CLI through a token file (default location + ``~/.ansible/galaxy_token``) or (insecurely) through the ``--token`` argument to ``ansible-galaxy``. Deprecated @@ -73,7 +73,7 @@ Plugins Lookup plugin names case-sensitivity ------------------------------------ -* Prior to Ansible ``2.10`` lookup plugin names passed in as an argument to the ``lookup()`` function were treated as case-insensitive as opposed to lookups invoked via ``with_``. ``2.10`` brings consistency to ``lookup()`` and ``with_`` to be both case-sensitive. +* Prior to Ansible ``2.10`` lookup plugin names passed in as an argument to the ``lookup()`` function were treated as case-insensitive as opposed to lookups invoked through ``with_``. ``2.10`` brings consistency to ``lookup()`` and ``with_`` to be both case-sensitive. Noteworthy plugin changes ------------------------- diff --git a/docs/docsite/rst/porting_guides/porting_guide_core_2.12.rst b/docs/docsite/rst/porting_guides/porting_guide_core_2.12.rst index 2d60bf26b0a..4e33e84247f 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_core_2.12.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_core_2.12.rst @@ -112,7 +112,7 @@ Plugins * ``unique`` filter with Jinja2 < 2.10 is case-sensitive and now raise coherently an error if ``case_sensitive=False`` instead of when ``case_sensitive=True``. * Set theory filters (``intersect``, ``difference``, ``symmetric_difference`` and ``union``) are now case-sensitive. Explicitly use ``case_sensitive=False`` to keep previous behavior. Note: with Jinja2 < 2.10, the filters were already case-sensitive by default. -* ``password_hash``` now uses ``passlib`` defaults when an option is unspecified, e.g. ``bcrypt_sha256`` now default to the "2b" format and if the "2a" format is required it must be specified. +* ``password_hash``` now uses ``passlib`` defaults when an option is unspecified, for example ``bcrypt_sha256`` now default to the "2b" format and if the "2a" format is required it must be specified. Porting custom scripts ======================