ja/LC_MESSAGES/dev_guide.po

6 msgid ""
20 msgid "Collection Galaxy metadata structure"
24 msgid "A key component of an Ansible collection is the ``galaxy.yml`` file placed in the root direc…
28 msgid "Structure"
32 msgid "The ``galaxy.yml`` file must contain the following keys in valid YAML:"
36 msgid "Key"
40 msgid "Comment"
44 msgid "namespace |br|"
57 msgid "string |_|"
65 msgid "/ |_|"
75 msgid "required"
79 msgid "The namespace of the collection."
83 msgid "This can be a company/brand/organization or product namespace under which all content lives."
87 msgid "May only contain alphanumeric lowercase characters and underscores. Namespaces cannot start …
91 msgid "name |br|"
95 msgid "The name of the collection."
99 msgid "Has the same character restrictions as ``namespace``."
103 msgid "version |br|"
107 msgid "The version of the collection."
111 msgid "Must be compatible with semantic versioning."
115 msgid "readme |br|"
119 msgid "The path to the Markdown (.md) readme file."
124 msgid "This path is relative to the root of the collection."
128 msgid "authors |br|"
135 msgid "list |_|"
139 msgid "A list of the collection's content authors."
143 msgid "Can be just the name or in the format 'Full Name <email> (url) @nicks:irc/im.site#channel'."
147 msgid "description |br|"
151 msgid "A short summary description of the collection."
155 msgid "license |br|"
159 msgid "Either a single license or a list of licenses for content inside of a collection."
163 msgid "Ansible Galaxy currently only accepts `SPDX <https://spdx.org/licenses/>`_ licenses"
167 msgid "This key is mutually exclusive with ``license_file``."
171 msgid "license_file |br|"
175 msgid "The path to the license file for the collection."
179 msgid "This key is mutually exclusive with ``license``."
183 msgid "tags |br|"
187 msgid "A list of tags you want to associate with the collection for indexing/searching."
191 msgid "A tag name has the same character requirements as ``namespace`` and ``name``."
195 msgid "dependencies |br|"
199 msgid "dictionary |_|"
203 msgid "Collections that this collection requires to be installed for it to be usable."
207 msgid "The key of the dict is the collection label ``namespace.name``."
211 msgid "The value is a version range `specifiers <https://python-semanticversion.readthedocs.io/en/l…
215 msgid "Multiple version range specifiers can be set and are separated by ``,``."
219 msgid "repository |br|"
223 msgid "The URL of the originating SCM repository."
227 msgid "documentation |br|"
231 msgid "The URL to any online docs."
235 msgid "homepage |br|"
239 msgid "The URL to the homepage of the collection/project."
243 msgid "issues |br|"
247 msgid "The URL to the collection issue tracker."
251 msgid "build_ignore |br|"
255 msgid "|br| version_added: 2.10"
259 msgid "|_|"
263 msgid "A list of file glob-like patterns used to filter any files or directories that should not be…
267 msgid "A pattern is matched from the relative path of the file or directory of the collection direc…
271 msgid "This uses ``fnmatch`` to match the files or directories."
275 msgid "Some directories and files like ``galaxy.yml``, ``*.pyc``, ``*.retry``, and ``.git`` are alw…
279 msgid "Examples"
283 msgid ":ref:`developing_collections`"
287 msgid "Develop or modify a collection."
295 msgid ":ref:`developing_modules_general`"
300 msgid "Learn about how to write Ansible modules"
311 msgid ":ref:`collections`"
321 msgid "Learn how to install and use collections."
337 msgid "`Mailing List <https://groups.google.com/group/ansible-devel>`_"
352 msgid "The development mailing list"
367 msgid "`irc.libera.chat <https://libera.chat/>`_"
384 msgid "#ansible IRC chat channel"
388 msgid "Debugging modules"
392 msgid "Detailed debugging steps"
396 msgid "Ansible modules are put together as a zip file consisting of the module file and the various…
400 msgid "The following steps use ``localhost`` as the target host, but you can use the same steps to …
404 msgid "Set :envvar:`ANSIBLE_KEEP_REMOTE_FILES` to ``1`` on the control host so Ansible will keep th…
408 msgid "Navigate to the temporary directory from the previous step. If the previous command was run …
412 msgid "Run the wrapper's ``explode`` command to turn the string into some Python files that you can…
416 msgid "If you want to examine the wrapper file you can. It will show a small Python script with a l…
420 msgid "When you look into the temporary directory you'll see a structure like this:"
424 msgid "``AnsiballZ_ping.py`` is the Python script with the module code stored in a base64 encoded s…
428 msgid "``ping.py`` is the code for the module itself. You can modify this code to see what effect i…
432 msgid "The ``args`` file contains a JSON string. The string is a dictionary containing the module a…
436 msgid "The ``ansible`` directory contains the module code in ``modules`` as well as code from :mod:…
440 msgid "You can modify files in this directory if you suspect that the module is having a problem in…
444 msgid "Once you edit the code or arguments in the exploded tree, use the ``execute`` subcommand to …
448 msgid "This subcommand inserts the absolute path to ``debug_dir`` as the first item in ``sys.path``…
452 msgid "Simple debugging"
456 msgid "The easiest way to run a debugger in a module, either local or remote, is to use `epdb <http…
460 msgid "This technique should work with any remote debugger, but we do not guarantee any particular …
464 msgid "The `q <https://pypi.org/project/q/>`_ library is another very useful debugging tool."
468 msgid "Since ``print()`` statements do not work inside modules, raising an exception is a good appr…
472 msgid "Python API"
487 msgid "Topics"
491 msgid "This API is intended for internal Ansible use. Ansible may make changes to this API at any t…
495 msgid "There are several ways to use Ansible from an API perspective.   You can use the Ansible Pyt…
499 msgid "If you would like to use Ansible programmatically from a language other than Python, trigger…
503 msgid "Because Ansible relies on forking processes, this API is not thread safe."
507 msgid "Python API example"
511 msgid "This example is a simple demonstration that shows how to minimally run a couple of tasks:"
515 msgid "Ansible emits warnings and errors via the display object, which prints directly to stdout, s…
519 msgid "The source code for the ``ansible`` command line tools (``lib/ansible/cli/``) is `available …
524 msgid ":ref:`developing_inventory`"
528 msgid "Developing dynamic inventory integrations"
532 msgid "Getting started on developing a module"
538 msgid ":ref:`developing_plugins`"
543 msgid "How to develop plugins"
549 msgid "`Development Mailing List <https://groups.google.com/group/ansible-devel>`_"
555 msgid "Mailing list for development topics"
562 msgid "`irc.libera.chat <https://libera.chat>`_"
566 msgid "Developing new collections"
570 msgid "Working with existing collections"
574 msgid "Collections references"
578 msgid "Developing collections"
582 msgid "Collections are a distribution format for Ansible content. You can package and distribute pl…
586 msgid "You can create a collection and publish it to `Ansible Galaxy <https://galaxy.ansible.com>`_…
590 msgid "For instructions on developing modules, see :ref:`developing_modules_general`."
594 msgid "Learn how to install and use collections in playbooks and roles"
604 msgid ":ref:`contributing_maintained_collections`"
614 msgid "Guidelines for contributing to selected collections"
618 msgid "`Ansible Collections Overview and FAQ <https://github.com/ansible-collections/overview/blob/…
622 msgid "Current development status of community collections and FAQ"
626 msgid "Generating changelogs and porting guide entries in a collection"
630 msgid "You can create and share changelog and porting guide entries for your collection. If your co…
634 msgid "Ansible here refers to the Ansible 2.10 or later release that includes a curated set of coll…
638 msgid "Understanding antsibull-changelog"
642 msgid "The ``antsibull-changelog`` tool allows you to create and update changelogs for Ansible coll…
646 msgid "See :ref:`changelogs_how_to` and the `antsibull-changelog documentation <https://github.com/…
650 msgid "The collection maintainers set the changelog policy for their collections. See the individua…
654 msgid "Generating changelogs"
658 msgid "To initialize changelog generation:"
662 msgid "Install ``antsibull-changelog``: :code:`pip install antsibull-changelog`."
666 msgid "Initialize changelogs for your repository: :code:`antsibull-changelog init <path/to/your/col…
670 msgid "Optionally, edit the ``changelogs/config.yaml`` file to customize the location of the genera…
674 msgid "To generate changelogs from the changelog fragments you created:"
678 msgid "Optionally, validate your changelog fragments: :code:`antsibull-changelog lint`."
682 msgid "Generate the changelog for your release: :code:`antsibull-changelog release [--version versi…
686 msgid "Add the  ``--reload-plugins`` option if you ran the ``antsibull-changelog release`` command …
690 msgid "Porting Guide entries from changelog fragments"
694 msgid "The Ansible changelog generator automatically adds several changelog fragment categories to …
698 msgid "``major_changes``"
702 msgid "``breaking_changes``"
706 msgid "``deprecated_features``"
710 msgid "``removed_features``"
714 msgid "Including collection changelogs into Ansible"
718 msgid "If your collection is part of Ansible, use one of the following three options  to include yo…
722 msgid "Use the ``antsibull-changelog`` tool."
726 msgid "If are not using this tool, include the properly formatted ``changelog.yaml`` file  into you…
730 msgid "Add a link to own changelogs or release notes in any format by opening an issue at https://g…
734 msgid "For the first two options, Ansible pulls the changelog details from Galaxy so your changelog…
738 msgid "Contributing to collections"
742 msgid "If you want to add functionality to an existing collection, modify a collection you are usin…
746 msgid "Contributing to a collection: community.general"
750 msgid "These instructions apply to collections hosted in the `ansible_collections GitHub org <https…
754 msgid "This example uses the `community.general collection <https://github.com/ansible-collections/…
759 msgid "Prerequisites"
763 msgid "Include ``~/dev/ansible/collections/`` in :ref:`COLLECTIONS_PATHS`"
767 msgid "If that path mentions multiple directories, make sure that no other directory earlier in the…
771 msgid "Creating a PR"
775 msgid "Create the directory ``~/dev/ansible/collections/ansible_collections/community``::"
779 msgid "Clone `the community.general Git repository <https://github.com/ansible-collections/communit…
783 msgid "If you clone from a fork, add the original repository as a remote ``upstream``::"
787 msgid "Create a branch and commit your changes on the branch."
791 msgid "Remember to add tests for your changes, see :ref:`testing_collections`."
795 msgid "Push your changes to your fork of the collection and create a Pull Request."
799 msgid "You can test your changes by using this checkout of ``community.general`` in playbooks and r…
803 msgid "Creating collections"
807 msgid "To create a collection:"
811 msgid "Create a :ref:`collection skeleton<creating_collections_skeleton>` with the ``collection ini…
815 msgid "Add modules and other content to the collection."
819 msgid "Build the collection into a collection artifact with :ref:`ansible-galaxy collection build<b…
823 msgid "Publish the collection artifact to Galaxy with :ref:`ansible-galaxy collection publish<publi…
827 msgid "A user can then install your collection on their systems."
831 msgid "Creating a collection skeleton"
835 msgid "To start a new collection:"
839 msgid "Both the namespace and collection names use the same strict set of requirements. See `Galaxy…
843 msgid "Once the skeleton exists, you can populate the directories with the content you want inside …
847 msgid "Reference: the ``ansible-galaxy collection`` command"
851 msgid "Currently the ``ansible-galaxy collection`` command implements the following sub commands:"
855 msgid "``init``: Create a basic collection skeleton based on the default template included with Ans…
859 msgid "``build``: Create a collection artifact that can be uploaded to Galaxy or your own repositor…
863 msgid "``publish``: Publish a built collection artifact to Galaxy."
867 msgid "``install``: Install one or more collections."
871 msgid "To learn more about the ``ansible-galaxy`` command-line tool, see the :ref:`ansible-galaxy` …
875 msgid ":ref:`collection_structure`"
879 msgid "Directories and files included in the collection skeleton"
883 msgid "Distributing collections"
887 msgid "You can distribute your collections by publishing them on a distribution server. Distributio…
891 msgid "Distributing collections involves three major steps: #. Configuring your distribution server…
895 msgid "Configuring your distribution server or servers"
899 msgid "Get a namespace on each distribution server you want to use (Galaxy, private Automation Hub,…
903 msgid "Get an API token for each distribution server you want to use."
907 msgid "Specify the API token for each distribution server you want to use."
911 msgid "Getting a namespace"
915 msgid "You need a namespace on Galaxy and/or Automation Hub to upload your collection. To get a nam…
919 msgid "For Galaxy, see `Galaxy namespaces <https://galaxy.ansible.com/docs/contributing/namespaces.…
923 msgid "For Automation Hub, see the `Ansible Certified Content FAQ <https://access.redhat.com/articl…
927 msgid "Getting your API token"
931 msgid "You need an API token for Galaxy and/or Automation Hub to upload your collection. Use the AP…
935 msgid "To get your API token:"
939 msgid "For Galaxy, go to the `Galaxy profile preferences <https://galaxy.ansible.com/me/preferences…
943 msgid "For Automation Hub, go to `the token page <https://cloud.redhat.com/ansible/automation-hub/t…
947 msgid "Specifying your API token"
951 msgid "Once you have retrieved your API token, you can specify the correct token for each distribut…
955 msgid "Pass the token to  the ``ansible-galaxy`` command using the ``--token``."
959 msgid "Configure the token within a Galaxy server list in your :file:`ansible.cfg` file."
963 msgid "Specifying your API token with the ``--token`` argument"
967 msgid "You can use the ``--token`` argument with the ``ansible-galaxy`` command (in conjunction wit…
971 msgid "Specifying your API token with a Galaxy server list"
975 msgid "You can configure one or more distribution servers for Galaxy in your :file:`ansible.cfg` fi…
979 msgid "See :ref:`galaxy_server_config` for complete details."
983 msgid "Building a collection tarball"
987 msgid "Once you have configured one or more distribution servers, you must build a collection tarba…
991 msgid "This creates a tarball of the built collection in the current directory which can be uploade…
995 msgid "Certain files and folders are excluded when building the collection artifact. See :ref:`igno…
999 msgid "If you used the now-deprecated ``Mazer`` tool for any of your collections, delete any and al…
1003 msgid "The current Galaxy maximum tarball size is 2 MB."
1007 msgid "This tarball is mainly intended to upload to Galaxy as a distribution method, but you can us…
1011 msgid "Ignoring files and folders"
1015 msgid "By default the build step will include all the files in the collection directory in the fina…
1019 msgid "``galaxy.yml``"
1023 msgid "``*.pyc``"
1027 msgid "``*.retry``"
1031 msgid "``tests/output``"
1035 msgid "previously built artifacts in the root directory"
1039 msgid "various version control directories like ``.git/``"
1043 msgid "To exclude other files and folders when building the collection, you can set a list of file …
1047 msgid "``*``: Matches everything"
1051 msgid "``?``: Matches any single character"
1055 msgid "``[seq]``: Matches and character in seq"
1059 msgid "``[!seq]``:Matches any character not in seq"
1063 msgid "For example, if you wanted to exclude the :file:`sensitive` folder within the ``playbooks`` …
1067 msgid "This feature is only supported when running ``ansible-galaxy collection build`` with Ansible…
1071 msgid "Collection versions"
1075 msgid "Each time you publish your collection, you create a new version. Once you publish a version …
1079 msgid "Collection versions use `Semantic Versioning <https://semver.org/>`_ for version numbers. Pl…
1083 msgid "Increment major (for example: x in `x.y.z`) version number for an incompatible API change."
1087 msgid "Increment minor (for example: y in `x.y.z`) version number for new functionality in a backwa…
1091 msgid "Increment patch (for example: z in `x.y.z`) version number for backwards compatible bug fixe…
1095 msgid "Trying collections locally"
1099 msgid "Before you publish your collection, test it out locally. Every time you publish a tarball, y…
1103 msgid "Trying your collection from the tarball"
1107 msgid "You can try your collection locally by installing it from the tarball. The following will en…
1111 msgid "You should use one of the values configured in :ref:`COLLECTIONS_PATHS` for your path. This …
1115 msgid "If you want to use a collection directly out of a checked out git repository, see :ref:`hack…
1119 msgid "Next, try using the local collection inside a playbook. For examples and more details see :r…
1123 msgid "Trying your collection from a git repository"
1127 msgid "You can also test a version of your collection in development by installing it from a git re…
1131 msgid "You can install a collection in a git repository by providing the URI to the repository inst…
1135 msgid "Embedding credentials into a git URI is not secure. Make sure to use safe auth options for s…
1139 msgid "In a ``requirements.yml`` file, you can also use the ``type`` and ``version`` keys in additi…
1143 msgid "Git repositories can be used for collection dependencies as well. This can be helpful for lo…
1147 msgid "Default repository search locations"
1151 msgid "There are two paths searched in a repository for collections by default."
1155 msgid "The first is the ``galaxy.yml`` or ``MANIFEST.json`` file in the top level of the repository…
1159 msgid "The second is a ``galaxy.yml`` or ``MANIFEST.json`` file in each directory in the repository…
1163 msgid "Specifying the location to search for collections"
1167 msgid "If you have a different repository structure or only want to install a subset of collections…
1171 msgid "Publishing a collection"
1175 msgid "Once you have a namespace and an API token for each distribution server you want to use, and…
1179 msgid "Each time you add features or make changes to your collection, you must create a new collect…
1183 msgid "Publish a collection using ``ansible-galaxy``"
1187 msgid "By default, ``ansible-galaxy`` uses https://galaxy.ansible.com as the Galaxy server (as list…
1191 msgid "To upload the collection artifact with the ``ansible-galaxy`` command:"
1195 msgid "The above command assumes you have retrieved and stored your API token as part of a Galaxy s…
1199 msgid "The ``ansible-galaxy collection publish`` command triggers an import process, just as if you…
1203 msgid "Publishing a collection using the Galaxy website"
1207 msgid "To publish your collection directly on the Galaxy website:"
1211 msgid "Go to the `My Content <https://galaxy.ansible.com/my-content/namespaces>`_ page, and click t…
1215 msgid "From the **Add Content** dialogue, click **Upload New Collection**, and select the collectio…
1219 msgid "When you upload a collection, it always uploads to the namespace specified in the collection…
1223 msgid "Once Galaxy uploads and accepts a collection, you will be redirected to the **My Imports** p…
1227 msgid "Migrating Ansible content to a different collection"
1231 msgid "When you move content from one collection to another, for example to extract a set of relate…
1235 msgid "Migrating content"
1239 msgid "Before you start migrating content from one collection to another, look at `Ansible Collecti…
1243 msgid "To migrate content from one collection to another, if the collections are parts of `Ansible …
1247 msgid "Copy content from the source (old) collection to the target (new) collection."
1251 msgid "Deprecate the module/plugin with ``removal_version`` scheduled for the next major version in…
1255 msgid "When the next major release of the old collection is prepared:"
1259 msgid "remove the module/plugin from the old collection"
1263 msgid "remove the symlink stored in ``plugin/modules`` directory if appropriate (mainly when removi…
1267 msgid "remove related unit and integration tests"
1271 msgid "remove specific module utils"
1275 msgid "remove specific documentation fragments if there are any in the old collection"
1279 msgid "add a changelog fragment containing entries for ``removed_features`` and ``breaking_changes`…
1283 msgid "change ``meta/runtime.yml`` in the old collection:"
1287 msgid "add ``redirect`` to the corresponding module/plugin's entry"
1291 msgid "in particular, add ``redirect`` for the removed module utils and documentation fragments if …
1295 msgid "remove ``removal_version`` from there"
1299 msgid "remove related entries from ``tests/sanity/ignore.txt`` files if exist"
1303 msgid "remove changelog fragments for removed content that are not yet part of the changelog (in ot…
1307 msgid "remove requirements that are no longer required in ``tests/unit/requirements.txt``, ``tests/…
1311 msgid "To implement these changes, you need to create at least three PRs:"
1315 msgid "Create a PR against the new collection to copy the content."
1319 msgid "Deprecate the module/plugin in the old collection."
1323 msgid "Later create a PR against the old collection to remove the content according to the schedule…
1327 msgid "Adding the content to the new collection"
1331 msgid "Create a PR in the new collection to:"
1335 msgid "Copy ALL the related files from the old collection."
1339 msgid "If it is an action plugin, include the corresponding module with documentation."
1343 msgid "If it is a module, check if it has a corresponding action plugin that should move with it."
1347 msgid "Check ``meta/`` for relevant updates to ``runtime.yml`` if it exists."
1351 msgid "Carefully check the moved ``tests/integration`` and ``tests/units`` and update for FQCN."
1355 msgid "Review ``tests/sanity/ignore-*.txt`` entries in the old collection."
1359 msgid "Update ``meta/runtime.yml`` in the old collection."
1363 msgid "Removing the content from the old collection"
1367 msgid "Create a PR against the source collection repository to remove the modules, module_utils, pl…
1371 msgid "If you are removing an action plugin, remove the corresponding module that contains the docu…
1375 msgid "If you are removing a module, remove any corresponding action plugin that should stay with i…
1379 msgid "Remove any entries about removed plugins from ``meta/runtime.yml``. Ensure they are added in…
1383 msgid "Remove sanity ignore lines from ``tests/sanity/ignore\\*.txt``"
1387 msgid "Remove associated integration tests from ``tests/integrations/targets/`` and unit tests from…
1391 msgid "if you are removing from content from ``community.general`` or ``community.network``, remove…
1395 msgid "Carefully review ``meta/runtime.yml`` for any entries you may need to remove or update, in p…
1399 msgid "Update ``meta/runtime.yml`` to contain redirects for EVERY PLUGIN, pointing to the new colle…
1403 msgid "Maintainers for the old collection have to make sure that the PR is merged in a way that it …
1407 msgid "A new version containing the merged PR must not be released before the collection the conten…
1411 msgid "Once 1.0.0 of the collection from which the content has been removed has been released, such…
1415 msgid "Updating BOTMETA.yml"
1419 msgid "The ``BOTMETA.yml``, for example in `community.general collection repository <https://github…
1423 msgid "ansibullbot"
1427 msgid "If the old and/or new collection has ``ansibullbot``, its ``BOTMETA.yml`` must be updated co…
1431 msgid "Ansibulbot will know how to redirect existing issues and PRs to the new repo. The build proc…
1435 msgid "`Example PR <https://github.com/ansible/ansible/pull/66981/files>`_"
1439 msgid "The ``migrated_to:`` key must be added explicitly for every *file*. You cannot add ``migrate…
1443 msgid "``migrated_to:`` MUST be added for every:"
1448 msgid "module"
1452 msgid "plugin"
1457 msgid "module_utils"
1461 msgid "contrib/inventory script"
1465 msgid "You do NOT need to add ``migrated_to`` for:"
1469 msgid "Unit tests"
1474 msgid "Integration tests"
1478 msgid "ReStructured Text docs (anything under ``docs/docsite/rst/``)"
1482 msgid "Files that never existed in ``ansible/ansible:devel``"
1486 msgid "Using shared resources in collections"
1490 msgid "Although developing Ansible modules contained in collections is similar to developing standa…
1494 msgid "Using documentation fragments in collections"
1498 msgid "To include documentation fragments in your collection:"
1502 msgid "Create the documentation fragment: ``plugins/doc_fragments/fragment_name``."
1506 msgid "Refer to the documentation fragment with its FQCN."
1510 msgid ":ref:`module_docs_fragments` covers the basics for documentation fragments. The `kubernetes.…
1514 msgid "If you use FQCN, you can use documentation fragments from one collection in another collecti…
1518 msgid "Leveraging optional module utilities in collections"
1522 msgid "Optional module utilities let you adopt the latest features from the most recent ansible-cor…
1526 msgid "This implementation, widely used in Python programming, wraps optional imports in conditiona…
1530 msgid "For example, the `ansible.module_utils.common.respawn` package is only available in Ansible …
1534 msgid "By wrapping the import statement in a ``try`` block, the payload builder will omit the Pytho…
1538 msgid "The optional import behavior also applies to module_utils imported from collections."
1542 msgid "Collection structure"
1546 msgid "A collection is a simple data structure. None of the directories are required unless you hav…
1550 msgid "Collection directories and files"
1554 msgid "A collection can contain these directories and files::"
1558 msgid "Ansible only accepts ``.md`` extensions for the :file:`README` file and any files in the :fi…
1562 msgid "See the `ansible-collections <https://github.com/ansible-collections/>`_ GitHub Org for exam…
1566 msgid "Not all directories are currently in use. Those are placeholders for future features."
1570 msgid "galaxy.yml"
1574 msgid "A collection must have a ``galaxy.yml`` file that contains the necessary information to buil…
1578 msgid "docs directory"
1582 msgid "Put general documentation for the collection here. Keep the specific documentation for plugi…
1586 msgid "Use ``ansible-doc`` to view documentation for plugins inside a collection:"
1590 msgid "The ``ansible-doc`` command requires the fully qualified collection name (FQCN) to display s…
1594 msgid "The Galaxy namespace of an Ansible collection is defined in the ``galaxy.yml`` file. It can …
1598 msgid "plugins directory"
1602 msgid "Add a 'per plugin type' specific subdirectory here, including ``module_utils`` which is usab…
1606 msgid "Vars plugins are unsupported in collections. Cache plugins may be used in collections for fa…
1610 msgid "When coding with ``module_utils`` in a collection, the Python ``import`` statement needs to …
1614 msgid "The following example snippets show a Python and PowerShell module using both default Ansibl…
1618 msgid "Note that importing something from an ``__init__.py`` file requires using the file name:"
1622 msgid "In the PowerShell example the ``module_util`` in question is called ``hyperv`` such that the…
1626 msgid "roles directory"
1630 msgid "Collection roles are mostly the same as existing roles, but with a couple of limitations:"
1634 msgid "Role names are now limited to contain only lowercase alphanumeric characters, plus ``_`` and…
1638 msgid "Roles in a collection cannot contain plugins any more. Plugins must live in the collection `…
1642 msgid "The directory name of the role is used as the role name. Therefore, the directory name must …
1646 msgid "You can migrate 'traditional roles' into a collection but they must follow the rules above. …
1650 msgid "For roles imported into Galaxy directly from a GitHub repository, setting the ``role_name`` …
1654 msgid "playbooks directory"
1658 msgid "TBD."
1662 msgid "tests directory"
1666 msgid "Ansible Collections are tested much like Ansible itself, by using the `ansible-test` utility…
1670 msgid "See :ref:`testing_collections` for specific information on how to test collections with ``an…
1674 msgid "When reading the :ref:`developing_testing` documentation, there will be content that applies…
1678 msgid "meta directory"
1682 msgid "A collection can store some additional metadata in a ``runtime.yml`` file in the collection'…
1686 msgid "*requires_ansible*:"
1690 msgid "The version of Ansible required to use the collection. Multiple versions can be separated wi…
1694 msgid "although the version is a `PEP440 Version Specifier <https://www.python.org/dev/peps/pep-044…
1698 msgid "*plugin_routing*:"
1702 msgid "Content in a collection that Ansible needs to load from another location or that has been de…
1706 msgid "*import_redirection*"
1710 msgid "A mapping of names for Python import statements and their redirected locations."
1714 msgid ":ref:`distributing_collections`"
1718 msgid "Learn how to package and publish your collection"
1722 msgid "Testing collections"
1726 msgid "Testing your collection ensures that your code works well and integrates well with the rest …
1730 msgid "Testing tools"
1734 msgid "The main tool for testing collections is ``ansible-test``, Ansible's testing tool described …
1738 msgid "You must always execute ``ansible-test`` from the root directory of a collection. You can ru…
1742 msgid "Compile and sanity tests"
1746 msgid "To run all compile and sanity tests::"
1750 msgid "See :ref:`testing_compile` and :ref:`testing_sanity` for more information. See the :ref:`ful…
1755 msgid "Adding unit tests"
1759 msgid "You must place unit tests in the appropriate ``tests/unit/plugins/`` directory. For example,…
1763 msgid "To run all unit tests for all supported Python versions::"
1767 msgid "To run all unit tests only for a specific Python version::"
1771 msgid "To run only a specific unit test::"
1775 msgid "You can specify Python requirements in the ``tests/unit/requirements.txt`` file. See :ref:`t…
1779 msgid "Adding integration tests"
1783 msgid "You must place integration tests in the appropriate ``tests/integration/targets/`` directory…
1787 msgid "You can write two different kinds of integration tests:"
1791 msgid "Ansible role tests run with ``ansible-playbook`` and validate various aspects of the module.…
1795 msgid "``runme.sh`` tests run directly as scripts. They can set up inventory files, and execute ``a…
1799 msgid "For examples, see the `integration tests in community.general <https://github.com/ansible-co…
1803 msgid "Since integration tests can install requirements, and set-up, start and stop services, we re…
1807 msgid "To execute all integration tests for a collection::"
1811 msgid "If you want more detailed output, run the command with ``-vvv`` instead of ``-v``. Alternati…
1815 msgid "To execute only the integration tests in a specific directory::"
1819 msgid "You can specify multiple target names. Each target name is the name of a directory in ``test…
1823 msgid ":ref:`developing_testing`"
1827 msgid "More resources on testing Ansible"
1831 msgid "Developing ``ansible-core``"
1835 msgid "Although ``ansible-core`` (the code hosted in the `ansible/ansible repository <https://githu…
1841 msgid ":ref:`developing_api`"
1846 msgid "Learn about the Python API for task execution"
1850 msgid "Learn about developing plugins"
1854 msgid "#ansible-devel IRC chat channel"
1858 msgid "Developing dynamic inventory"
1862 msgid "Ansible can pull inventory information from dynamic sources, including cloud sources, by usi…
1866 msgid "In previous versions, you had to create a script or program that could output JSON in the co…
1870 msgid "Inventory sources"
1874 msgid "Inventory sources are the input strings that inventory plugins work with. An inventory sourc…
1878 msgid "The table below shows some examples of inventory plugins and the source types that you can p…
1882 msgid "Plugin"
1886 msgid "Source"
1890 msgid ":ref:`host list <host_list_inventory>`"
1894 msgid "A comma-separated list of hosts"
1898 msgid ":ref:`yaml <yaml_inventory>`"
1902 msgid "Path to a YAML format data file"
1906 msgid ":ref:`constructed <constructed_inventory>`"
1911 msgid "Path to a YAML configuration file"
1915 msgid ":ref:`ini <ini_inventory>`"
1919 msgid "Path to an INI formatted data file"
1923 msgid ":ref:`virtualbox <virtualbox_inventory>`"
1927 msgid ":ref:`script plugin <script_inventory>`"
1931 msgid "Path to an executable that outputs JSON"
1936 msgid "Inventory plugins"
1940 msgid "Like most plugin types (except modules), inventory plugins must be developed in Python. They…
1944 msgid "Most of the documentation in :ref:`developing_plugins` also applies here. You should read th…
1948 msgid "Normally, inventory plugins are executed at the start of a run, and before the playbooks, pl…
1952 msgid "If you use the persistent cache, inventory plugins can also use the configured cache plugin …
1956 msgid "Developing an inventory plugin"
1960 msgid "The first thing you want to do is use the base class:"
1964 msgid "If the inventory plugin is in a collection, the NAME should be in the 'namespace.collection_…
1968 msgid "After you have the basic plugin working, you can incorporate other features by adding more b…
1972 msgid "For the bulk of the work in a plugin, we mostly want to deal with 2 methods ``verify_file`` …
1976 msgid "verify_file method"
1980 msgid "Ansible uses this method to quickly determine if the inventory source is usable by the plugi…
1984 msgid "In the above example, from the :ref:`virtualbox inventory plugin <virtualbox_inventory>`, we…
1988 msgid "The following is another example that does not use a 'file' but the inventory source string …
1992 msgid "This method is just to expedite the inventory process and avoid unnecessary parsing of sourc…
1996 msgid "parse method"
2000 msgid "This method does the bulk of the work in the plugin. It takes the following parameters:"
2004 msgid "inventory: inventory object with existing data and the methods to add hosts/groups/variables…
2008 msgid "loader: Ansible's DataLoader. The DataLoader can read files, auto load JSON/YAML and decrypt…
2012 msgid "path: string with inventory source (this is usually a path, but is not required)"
2016 msgid "cache: indicates whether the plugin should use or avoid caches (cache plugin and/or loader)"
2020 msgid "The base class does some minimal assignment for reuse in other methods."
2024 msgid "It is up to the plugin now to parse the provided inventory source and translate it into Ansi…
2028 msgid "The specifics will vary depending on API and structure returned. Remember that if you get an…
2032 msgid "For examples on how to implement an inventory plugin, see the source code here: `lib/ansible…
2036 msgid "inventory cache"
2040 msgid "To cache the inventory, extend the inventory plugin documentation with the inventory_cache d…
2044 msgid "Next, load the cache plugin specified by the user to read from and update the cache. If your…
2048 msgid "Before using the cache plugin, you must retrieve a unique cache key by using the ``get_cache…
2052 msgid "Now that you've enabled caching, loaded the correct plugin, and retrieved a unique cache key…
2056 msgid "After the ``parse`` method is complete, the contents of ``self._cache`` is used to set the c…
2060 msgid "You have three other cache methods available:"
2064 msgid "``set_cache_plugin`` forces the cache plugin to be set with the contents of ``self._cache``,…
2068 msgid "``update_cache_if_changed`` sets the cache plugin only if ``self._cache`` has been modified,…
2072 msgid "``clear_cache`` flushes the cache, ultimately by calling the cache plugin's ``flush()`` meth…
2076 msgid "constructed features"
2080 msgid "Inventory plugins can create host variables and groups from Jinja2 expressions and variables…
2084 msgid "The three main options from the ``constructed`` documentation fragment are ``compose``, ``ke…
2088 msgid "By default, group names created with ``_add_host_to_composed_groups()`` and ``_add_host_to_k…
2092 msgid "Common format for inventory sources"
2096 msgid "To simplify development, most plugins use a standard YAML-based configuration file as the in…
2100 msgid "The 'auto' plugin"
2104 msgid "From Ansible 2.5 onwards, we include the :ref:`auto inventory plugin <auto_inventory>` and e…
2108 msgid "Inventory scripts"
2112 msgid "Even though we now have inventory plugins, we still support inventory scripts, not only for …
2116 msgid "Inventory script conventions"
2120 msgid "Inventory scripts must accept the ``--list`` and ``--host <hostname>`` arguments. Although o…
2124 msgid "When the script is called with the single argument ``--list``, the script must output to std…
2128 msgid "If any of the elements of a group are empty, they may be omitted from the output."
2132 msgid "When called with the argument ``--host <hostname>`` (where <hostname> is a host from above),…
2136 msgid "Printing variables is optional. If the script does not print variables, it should print an e…
2140 msgid "Tuning the external inventory script"
2144 msgid "The stock inventory script system mentioned above works for all versions of Ansible, but cal…
2148 msgid "To avoid this inefficiency, if the inventory script returns a top-level element called \"_me…
2152 msgid "The data to be added to the top-level JSON object looks like this::"
2156 msgid "To satisfy the requirements of using ``_meta``, to prevent ansible from calling your invento…
2160 msgid "If you intend to replace an existing static inventory file with an inventory script, it must…
2164 msgid "An easy way to see how this should look is using :ref:`ansible-inventory`, which also suppor…
2168 msgid "Python API to Playbooks and Ad Hoc Task Execution"
2172 msgid "Get started with developing a module"
2176 msgid "`AWX <https://github.com/ansible/awx>`_"
2180 msgid "REST API endpoint and GUI for Ansible, syncs with dynamic inventory"
2184 msgid "Adding modules and plugins locally"
2188 msgid "The easiest, quickest, and the most popular way to extend Ansible is to use a local module o…
2192 msgid "If you are using an existing module or plugin but Ansible can't find it, this page is all yo…
2196 msgid "Extending Ansible with local modules and plugins offers lots of shortcuts such as:"
2200 msgid "You can copy other people's modules and plugins."
2204 msgid "When writing a new module, you can choose any programming language you like."
2208 msgid "You do not have to clone any repositories."
2212 msgid "You do not have to open a pull request."
2216 msgid "You do not have to add tests (though we recommend that you do!)."
2220 msgid "To save a local module or plugin such that Ansible can find and use it, add the module or pl…
2224 msgid "Modules and plugins: what is the difference?"
2228 msgid "If you are looking to add local functionality to Ansible, you might wonder whether you need …
2232 msgid "Modules are reusable, standalone scripts that can be used by the Ansible API, the :command:`…
2236 msgid ":ref:`Plugins <plugins_lookup>` augment Ansible's core functionality and execute on the cont…
2240 msgid "Adding a module locally"
2244 msgid "Ansible automatically loads all executable files found in certain directories as modules."
2248 msgid "For local modules, use the name of the file as the module name: for example, if the module f…
2252 msgid "To load your local modules automatically and make them available to all playbooks and roles,…
2256 msgid "any directory added to the ``ANSIBLE_LIBRARY`` environment variable (``$ANSIBLE_LIBRARY`` ta…
2260 msgid "``~/.ansible/plugins/modules/``"
2264 msgid "``/usr/local/share/py38-ansible/plugins/modules/``"
2268 msgid "After you save your module file in one of these locations, Ansible loads it and you can use …
2272 msgid "To confirm that ``my_custom_module`` is available:"
2276 msgid "type ``ansible localhost -m my_custom_module``. You should see the output for that module."
2280 msgid "or"
2284 msgid "type ``ansible-doc -t module my_custom_module``. You should see the documentation for that m…
2288 msgid "Currently, the ``ansible-doc`` command can parse module documentation only from modules writ…
2292 msgid "You can limit the availability of your local module. If you want to use a local module only …
2296 msgid "In a selected playbook or playbooks: Store the module in a subdirectory called ``library`` i…
2300 msgid "In a single role: Store the module in a subdirectory called ``library`` within that role."
2304 msgid "Adding a plugin locally"
2308 msgid "Ansible loads plugins automatically too, and loads each type of plugin separately from a dir…
2312 msgid "action_plugins*"
2316 msgid "cache_plugins"
2320 msgid "callback_plugins"
2324 msgid "connection_plugins"
2328 msgid "filter_plugins*"
2332 msgid "inventory_plugins"
2336 msgid "lookup_plugins"
2340 msgid "shell_plugins"
2344 msgid "strategy_plugins"
2348 msgid "test_plugins*"
2352 msgid "vars_plugins"
2356 msgid "After you add the plugins and verify that they are available for use, you can see the docume…
2360 msgid "To load your local plugins automatically, add them in any of these locations:"
2364 msgid "any directory added to the relevant ``ANSIBLE_plugin_type_PLUGINS`` environment variable (th…
2368 msgid "the directory named for the correct ``plugin_type`` within ``~/.ansible/plugins/`` - for exa…
2372 msgid "the directory named for the correct ``plugin_type`` within ``/usr/local/share/py38-ansible/p…
2376 msgid "After your plugin file is in one of these locations, Ansible loads it and you can use it in …
2380 msgid "To confirm that ``plugins/plugin_type/my_custom_plugin`` is available:"
2384 msgid "type ``ansible-doc -t <plugin_type> my_custom_lookup_plugin``. For example, ``ansible-doc -t…
2388 msgid "You can limit the availability of your local plugin. If you want to use a local plugin only …
2392 msgid "In a selected playbook or playbooks: Store the plugin in a subdirectory for the correct ``pl…
2396 msgid "In a single role: Store the plugin in a subdirectory for the correct ``plugin_type`` (for ex…
2400 msgid "Using and developing module utilities"
2404 msgid "Ansible provides a number of module utilities, or snippets of shared code, that provide help…
2408 msgid "The ``ansible.module_utils`` namespace is not a plain Python package: it is constructed dyna…
2412 msgid "To reduce the maintenance burden in a collection or in local modules, you can extract duplic…
2416 msgid "When you run ``ansible-playbook``, Ansible will merge any files in your local ``module_utils…
2420 msgid "Naming and finding module utilities"
2424 msgid "You can generally tell what a module utility does from its name and/or its location. Generic…
2428 msgid "``lib/ansible/module_utils/urls.py`` contains shared code for parsing URLs"
2432 msgid "``openstack.cloud.plugins.module_utils.openstack.py`` contains utilities for modules that wo…
2436 msgid "``ansible.netcommon.plugins.module_utils.network.common.config.py`` contains utility functio…
2440 msgid "Following this pattern with your own module utilities makes everything easy to find and use."
2444 msgid "Standard module utilities"
2448 msgid "Ansible ships with an extensive library of ``module_utils`` files. You can find the module u…
2452 msgid "**LICENSING REQUIREMENTS**  Ansible enforces the following licensing requirements:"
2456 msgid "Utilities (files in ``lib/ansible/module_utils/``) may have one of two licenses:"
2460 msgid "A file in ``module_utils`` used **only** for a specific vendor's hardware, provider, or serv…
2464 msgid "All other ``module_utils`` must be licensed under BSD, so GPL-licensed third-party and Galax…
2468 msgid "If there's doubt about the appropriate license for a file in ``module_utils``, the Ansible C…
2472 msgid "All other files shipped with Ansible, including all modules, must be licensed under the GPL …
2476 msgid "``api.py`` - Supports generic API modules"
2480 msgid "``basic.py`` - General definitions and helper utilities for Ansible modules"
2484 msgid "``common/dict_transformations.py`` - Helper functions for dictionary transformations"
2488 msgid "``common/file.py`` - Helper functions for working with files"
2492 msgid "``common/text/`` - Helper functions for converting and formatting text"
2496 msgid "``common/parameters.py`` - Helper functions for dealing with module parameters"
2500 msgid "``common/sys_info.py`` - Functions for getting distribution and platform information"
2504 msgid "``common/validation.py`` - Helper functions for validating module parameters against a modul…
2508 msgid "``facts/`` - Directory of utilities for modules that return facts. See `PR 23012 <https://gi…
2512 msgid "``json_utils.py`` - Utilities for filtering unrelated output around module JSON output, like…
2516 msgid "``powershell/`` - Directory of definitions and helper functions for Windows PowerShell modul…
2520 msgid "``pycompat24.py`` - Exception workaround for Python 2.4"
2524 msgid "``service.py`` - Utilities to enable modules to work with Linux services (placeholder, not i…
2528 msgid "``six/__init__.py`` - Bundled copy of the `Six Python library <https://pypi.org/project/six/…
2532 msgid "``splitter.py`` - String splitting and manipulation utilities for working with Jinja2 templa…
2536 msgid "``urls.py`` - Utilities for working with http and https requests"
2540 msgid "Several commonly-used utilities migrated to collections in Ansible 2.10, including:"
2544 msgid "``ismount.py`` migrated to ``ansible.posix.plugins.module_utils.mount.py`` - Single helper f…
2548 msgid "``known_hosts.py`` migrated to ``community.general.plugins.module_utils.known_hosts.py`` - u…
2552 msgid "For a list of migrated content with destination collections, see https://github.com/ansible/…
2556 msgid "Should you develop a module?"
2560 msgid "Developing Ansible modules is easy, but often it is not necessary. Before you start writing …
2564 msgid "Does a similar module already exist?"
2568 msgid "An existing module may cover the functionality you want. Ansible collections include thousan…
2572 msgid "Should you use or develop an action plugin instead of a module?"
2576 msgid "An action plugin may be the best way to get the functionality you want. Action plugins run o…
2580 msgid "Should you use a role instead of a module?"
2584 msgid "A combination of existing modules may cover the functionality you want. You can write a role…
2588 msgid "Should you create a collection instead of a single module?"
2592 msgid "The functionality you want may be too large for a single module. If you want to connect Ansi…
2596 msgid "Each module should have a concise and well defined functionality. Basically, follow the UNIX…
2600 msgid "A module should not require that a user know all the underlying options of an API/tool to be…
2604 msgid "Modules should typically encompass much of the logic for interacting with a resource. A ligh…
2608 msgid "If your use case isn't covered by an existing module, an action plugin, or a role, and you d…
2612 msgid "I want to :ref:`get started on a new module <developing_modules_general>`."
2616 msgid "I want to review :ref:`tips and conventions for developing good modules <developing_modules_…
2620 msgid "I want to :ref:`write a Windows module <developing_modules_general_windows>`."
2624 msgid "I want :ref:`an overview of Ansible's architecture <developing_program_flow_modules>`."
2628 msgid "I want to :ref:`document my module <developing_modules_documenting>`."
2632 msgid "I want to :ref:`contribute my module back to Ansible Core <developing_modules_checklist>`."
2636 msgid "I want to :ref:`add unit and integration tests to my module <developing_testing>`."
2640 msgid "I want to :ref:`add Python 3 support to my module <developing_python_3>`."
2644 msgid "I want to :ref:`write multiple modules <developing_modules_in_groups>`."
2649 msgid ":ref:`list_of_collections`"
2654 msgid "Browse existing collections, modules, and plugins"
2658 msgid "Development mailing list"
2662 msgid "Conventions, tips, and pitfalls"
2666 msgid "As you design and develop modules, follow these basic conventions and tips for clean, usable…
2670 msgid "Scoping your module(s)"
2674 msgid "Especially if you want to contribute your module(s) to an existing Ansible Collection, make …
2678 msgid "Each module should have a concise and well-defined functionality. Basically, follow the UNIX…
2682 msgid "Do not add ``get``, ``list`` or ``info`` state options to an existing module - create a new …
2686 msgid "Modules should not require that a user know all the underlying options of an API/tool to be …
2690 msgid "Modules should encompass much of the logic for interacting with a resource. A lightweight wr…
2694 msgid "Avoid creating a module that does the work of other modules; this leads to code duplication …
2698 msgid "Designing module interfaces"
2702 msgid "If your module is addressing an object, the option for that object should be called ``name``…
2706 msgid "Modules accepting boolean status should accept ``yes``, ``no``, ``true``, ``false``, or anyt…
2710 msgid "Avoid ``action``/``command``, they are imperative and not declarative, there are other ways …
2714 msgid "General guidelines & tips"
2718 msgid "Each module should be self-contained in one file, so it can be auto-transferred by ``ansible…
2722 msgid "Module name MUST use underscores instead of hyphens or spaces as a word separator. Using hyp…
2726 msgid "Always use the ``hacking/test-module.py`` script when developing modules - it will warn you …
2730 msgid "If you have a local module that returns information specific to your installations, a good n…
2734 msgid "Eliminate or minimize dependencies. If your module has dependencies, document them at the to…
2738 msgid "Don't write to files directly; use a temporary file and then use the ``atomic_move`` functio…
2742 msgid "Avoid creating caches. Ansible is designed without a central server or authority, so you can…
2746 msgid "If you package your module(s) in an RPM, install the modules on the control machine in ``/us…
2750 msgid "Functions and Methods"
2754 msgid "Each function should be concise and should describe a meaningful amount of work."
2758 msgid "\"Don't repeat yourself\" is generally a good philosophy."
2762 msgid "Function names should use underscores: ``my_function_name``."
2766 msgid "The name of each function should describe what the function does."
2770 msgid "Each function should have a docstring."
2774 msgid "If your code is too nested, that's usually a sign the loop body could benefit from being a f…
2778 msgid "Python tips"
2782 msgid "Include a ``main`` function that wraps the normal execution."
2786 msgid "Call your ``main`` function from a conditional so you can import it into unit tests - for ex…
2790 msgid "Importing and using shared code"
2794 msgid "Use shared code whenever possible - don't reinvent the wheel. Ansible offers the ``AnsibleMo…
2798 msgid "Import ``ansible.module_utils`` code in the same place as you import other libraries."
2802 msgid "Do NOT use wildcards (*) for importing other python modules; instead, list the function(s) y…
2806 msgid "Import custom packages in ``try``/``except``, capture any import errors, and handle them wit…
2810 msgid "Then in ``main()``, just after the argspec, do"
2814 msgid "And document the dependency in the ``requirements`` section of your module's :ref:`documenta…
2818 msgid "Handling module failures"
2822 msgid "When your module fails, help users understand what went wrong. If you are using the ``Ansibl…
2826 msgid "Include a key of ``failed`` along with a string explanation in ``msg``. If you don't do this…
2830 msgid "Don't raise a traceback (stacktrace). Ansible can deal with stacktraces and automatically co…
2834 msgid "Do not use ``sys.exit()``. Use ``fail_json()`` from the module object."
2838 msgid "Handling exceptions (bugs) gracefully"
2842 msgid "Validate upfront--fail fast and return useful and clear error messages."
2846 msgid "Use defensive programming--use a simple design for your module, handle errors gracefully, an…
2850 msgid "Fail predictably--if we must fail, do it in a way that is the most expected. Either mimic th…
2854 msgid "Give out a useful message on what you were doing and add exception messages to that."
2858 msgid "Avoid catchall exceptions, they are not very useful unless the underlying API gives very goo…
2862 msgid "Creating correct and informative module output"
2866 msgid "Modules must output valid JSON only. Follow these guidelines for creating correct, useful mo…
2870 msgid "Make your top-level return type a hash (dictionary)."
2874 msgid "Nest complex return values within the top-level hash."
2878 msgid "Incorporate any lists or simple scalar values within the top-level return hash."
2882 msgid "Do not send module output to standard error, because the system will merge standard out with…
2886 msgid "Capture standard error and return it as a variable in the JSON on standard out. This is how …
2890 msgid "Never do ``print(\"some status message\")`` in a module, because it will not produce valid J…
2894 msgid "Always return useful data, even when there is no change."
2898 msgid "Be consistent about returns (some modules are too random), unless it is detrimental to the s…
2902 msgid "Make returns reusable--most of the time you don't want to read it, but you do want to proces…
2906 msgid "Return diff if in diff mode. This is not required for all modules, as it won't make sense fo…
2910 msgid "Enable your return values to be serialized as JSON with Python's standard `JSON encoder and …
2914 msgid "Do not return an object using exit_json(). Instead, convert the fields you need from the obj…
2918 msgid "Results from many hosts will be aggregated at once, so your module should return only releva…
2922 msgid "If a module returns stderr or otherwise fails to produce valid JSON, the actual output will …
2926 msgid "Following Ansible conventions"
2930 msgid "Ansible conventions offer a predictable user interface across all modules, playbooks, and ro…
2934 msgid "Use consistent names across modules (yes, we have many legacy deviations - don't make the pr…
2938 msgid "Use consistent options (arguments) within your module(s)."
2942 msgid "Do not use 'message' or 'syslog_facility' as an option name, because this is used internally…
2946 msgid "Normalize options with other modules - if Ansible and the API your module connects to use di…
2950 msgid "Return facts from ``*_facts`` modules in the ``ansible_facts`` field of the :ref:`result dic…
2954 msgid "Implement ``check_mode`` in all ``*_info`` and ``*_facts`` modules. Playbooks which conditio…
2958 msgid "Use module-specific environment variables. For example, if you use the helpers in ``module_u…
2962 msgid "Keep module options simple and focused - if you're loading a lot of choices/states on an exi…
2966 msgid "Keep options small when possible. Passing a large data structure to an option might save us …
2970 msgid "If you want to pass complex data to an option, write an expert module that allows this, alon…
2974 msgid "Implement declarative operations (not CRUD) so the user can ignore existing state and focus …
2978 msgid "Strive for a consistent final state (aka idempotency). If running your module twice in a row…
2982 msgid "Provide consistent return values within the standard Ansible return structure, even if NA/No…
2986 msgid "Follow additional guidelines that apply to families of modules if applicable. For example, A…
2990 msgid "Module Security"
2994 msgid "Avoid passing user input from the shell."
2998 msgid "Always check return codes."
3002 msgid "You must always use ``module.run_command``, not ``subprocess`` or ``Popen`` or ``os.system``…
3006 msgid "Avoid using the shell unless absolutely necessary."
3010 msgid "If you must use the shell, you must pass ``use_unsafe_shell=True`` to ``module.run_command``…
3014 msgid "If any variables in your module can come from user input with ``use_unsafe_shell=True``, you…
3018 msgid "When fetching URLs, use ``fetch_url`` or ``open_url`` from ``ansible.module_utils.urls``. Do…
3022 msgid "Sensitive values marked with ``no_log=True`` will automatically have that value stripped fro…
3026 msgid "Contributing your module to an existing Ansible collection"
3030 msgid "If you want to contribute a module to an existing collection, you must meet the community's …
3034 msgid "Modules accepted into certain collections are included in every Ansible release on PyPI. How…
3038 msgid "Contributing modules: objective requirements"
3042 msgid "To contribute a module to most Ansible collections, you must:"
3046 msgid "write your module in either Python or Powershell for Windows"
3050 msgid "use the ``AnsibleModule`` common code"
3054 msgid "support Python 2.6 and Python 3.5 - if your module cannot support Python 2.6, explain the re…
3058 msgid "use proper :ref:`Python 3 syntax <developing_python_3>`"
3062 msgid "follow `PEP 8 <https://www.python.org/dev/peps/pep-0008/>`_ Python style conventions - see :…
3066 msgid "license your module under the GPL license (GPLv3 or later)"
3070 msgid "understand the :ref:`license agreement <contributor_license_agreement>`, which applies to al…
3074 msgid "conform to Ansible's :ref:`formatting and documentation <developing_modules_documenting>` st…
3078 msgid "include comprehensive :ref:`tests <developing_testing>` for your module"
3082 msgid "minimize module dependencies"
3086 msgid "support :ref:`check_mode <check_mode_dry>` if possible"
3090 msgid "ensure your code is readable"
3094 msgid "if a module is named ``<something>_facts``, it should be because its main purpose is returni…
3098 msgid "Modules that query/return general information (and not ``ansible_facts``) should be named ``…
3102 msgid "Additional requirements may apply for certain collections. Review the individual collection …
3106 msgid "Please make sure your module meets these requirements before you submit your PR/proposal. If…
3110 msgid "Contributing to Ansible: subjective requirements"
3114 msgid "If your module meets these objective requirements, collection maintainers will review your c…
3118 msgid "Other checklists"
3122 msgid ":ref:`Tips for module development <developing_modules_best_practices>`."
3126 msgid ":ref:`Amazon development checklist <AWS_module_development>`."
3130 msgid ":ref:`Windows development checklist <developing_modules_general_windows>`."
3134 msgid "Module format and documentation"
3138 msgid "If you want to contribute your module to most Ansible collections, you must write your modul…
3142 msgid "Every Ansible module written in Python must begin with seven standard sections in a particul…
3146 msgid "Why don't the imports go first?"
3150 msgid "Keen Python programmers may notice that contrary to PEP 8's advice we don't put ``imports`` …
3154 msgid "**Copy old modules with care!**"
3158 msgid "Some older Ansible modules have ``imports`` at the bottom of the file, ``Copyright`` notices…
3162 msgid "Python shebang & UTF-8 coding"
3166 msgid "Begin your Ansible module with ``#!/usr/bin/python`` - this \"shebang\" allows ``ansible_pyt…
3170 msgid "Copyright and license"
3174 msgid "After the shebang and UTF-8 coding, add a `copyright line <https://www.gnu.org/licenses/gpl-…
3178 msgid "Major additions to the module (for instance, rewrites) may add additional copyright lines. A…
3182 msgid "ANSIBLE_METADATA block"
3186 msgid "Since we moved to collections we have deprecated the METADATA functionality, it is no longer…
3190 msgid "DOCUMENTATION block"
3194 msgid "After the shebang, the UTF-8 coding, the copyright line, and the license section comes the `…
3198 msgid "Module documentation should briefly and accurately define what each module and option does, …
3202 msgid "Descriptions should always start with a capital letter and end with a full stop. Consistency…
3206 msgid "Verify that arguments in doc and module spec dict are identical."
3210 msgid "For password / secret arguments ``no_log=True`` should be set."
3214 msgid "For arguments that seem to contain sensitive information but **do not** contain secrets, suc…
3219 msgid "If an option is only sometimes required, describe the conditions. For example, \"Required wh…
3223 msgid "If your module allows ``check_mode``, reflect this fact in the documentation."
3227 msgid "To create clear, concise, consistent, and useful documentation, follow the :ref:`style guide…
3231 msgid "Each documentation field is described below. Before committing your module documentation, pl…
3235 msgid "As long as your module file is :ref:`available locally <local_modules>`, you can use ``ansib…
3239 msgid "You should also :ref:`test the HTML output <testing_module_documentation>` of your module do…
3243 msgid "Documentation fields"
3247 msgid "All fields in the ``DOCUMENTATION`` block are lower-case. All fields are required unless spe…
3251 msgid "The name of the module."
3255 msgid "Must be the same as the filename, without the ``.py`` extension."
3259 msgid "short_description"
3263 msgid "A short description which is displayed on the :ref:`list_of_collections` page and ``ansible-…
3267 msgid "The ``short_description`` is displayed by ``ansible-doc -l`` without any category grouping, …
3271 msgid "Unlike ``description:``, ``short_description`` should not have a trailing period/full stop."
3275 msgid "description"
3279 msgid "A detailed description (generally two or more sentences)."
3283 msgid "Must be written in full sentences, in other words, with capital letters and periods/full sto…
3287 msgid "Shouldn't mention the module name."
3291 msgid "Make use of multiple entries rather than using one long paragraph."
3295 msgid "Don't quote complete values unless it is required by YAML."
3299 msgid "version_added"
3303 msgid "The version of Ansible when the module was added."
3307 msgid "This is a string, and not a float, for example, ``version_added: '2.1'``."
3311 msgid "In collections, this must be the collection version the module was added to, not the Ansible…
3315 msgid "author"
3319 msgid "Name of the module author in the form ``First Last (@GitHubID)``."
3323 msgid "Use a multi-line list if there is more than one author."
3327 msgid "Don't use quotes as it should not be required by YAML."
3331 msgid "deprecated"
3335 msgid "Marks modules that will be removed in future releases. See also :ref:`module_lifecycle`."
3340 msgid "options"
3344 msgid "Options are often called `parameters` or `arguments`. Because the documentation field is cal…
3348 msgid "If the module has no options (for example, it's a ``_facts`` module), all you need is one li…
3352 msgid "If your module has options (in other words, accepts arguments), each option should be docume…
3356 msgid "option-name"
3360 msgid "Declarative operation (not CRUD), to focus on the final state, for example `online:`, rather…
3364 msgid "The name of the option should be consistent with the rest of the module, as well as other mo…
3368 msgid "When in doubt, look for other modules to find option names that are used for the same purpos…
3372 msgid "Detailed explanation of what this option does. It should be written in full sentences."
3376 msgid "The first entry is a description of the option itself; subsequent entries detail its use, de…
3380 msgid "Should not list the possible values (that's what ``choices:`` is for, though it should expla…
3384 msgid "Mutually exclusive options must be documented as the final sentence on each of the options."
3388 msgid "Only needed if ``true``."
3392 msgid "If missing, we assume the option is not required."
3397 msgid "default"
3401 msgid "If ``required`` is false/missing, ``default`` may be specified (assumed 'null' if missing)."
3405 msgid "Ensure that the default value in the docs matches the default value in the code."
3409 msgid "The default field must not be listed as part of the description, unless it requires addition…
3413 msgid "If the option is a boolean value, you can use any of the boolean values recognized by Ansibl…
3418 msgid "choices"
3422 msgid "List of option values."
3426 msgid "Should be absent if empty."
3431 msgid "type"
3435 msgid "Specifies the data type that option accepts, must match the ``argspec``."
3439 msgid "If an argument is ``type='bool'``, this field should be set to ``type: bool`` and no ``choic…
3443 msgid "If an argument is ``type='list'``, ``elements`` should be specified."
3448 msgid "elements"
3452 msgid "Specifies the data type for list elements in case ``type='list'``."
3457 msgid "aliases"
3461 msgid "List of optional name aliases."
3465 msgid "Generally not needed."
3469 msgid "Only needed if this option was extended after initial Ansible release, in other words, this …
3473 msgid "This is a string, and not a float, for example, ``version_added: '2.3'``."
3477 msgid "In collections, this must be the collection version the option was added to, not the Ansible…
3481 msgid "suboptions"
3485 msgid "If this option takes a dict or list of dicts, you can define the structure here."
3489 msgid "See :ref:`ansible_collections.azure.azcollection.azure_rm_securitygroup_module`, :ref:`ansib…
3493 msgid "requirements"
3497 msgid "List of requirements (if applicable)."
3501 msgid "Include minimum versions."
3505 msgid "seealso"
3509 msgid "A list of references to other modules, documentation or Internet resources"
3513 msgid "In Ansible 2.10 and later, references to modules must use  the FQCN or ``ansible.builtin`` f…
3517 msgid "A reference can be one of the following formats:"
3521 msgid "notes"
3525 msgid "Details of any important information that doesn't fit in one of the above sections."
3529 msgid "For example, whether ``check_mode`` is or is not supported."
3533 msgid "Linking and other format macros within module documentation"
3537 msgid "You can link from your module documentation to other module docs, other resources on docs.an…
3541 msgid "``L()`` for links with a heading. For example: ``See L(Ansible Automation Platform,https://w…
3545 msgid "``U()`` for URLs. For example: ``See U(https://www.ansible.com/products/automation-platform)…
3549 msgid "``R()`` for cross-references with a heading (added in Ansible 2.10). For example: ``See R(Ci…
3553 msgid "``M()`` for module names. For example: ``See also M(ansible.builtin.yum) or M(community.gene…
3557 msgid "There are also some macros which do not create links but we use them to display certain type…
3561 msgid "``I()`` for option names. For example: ``Required if I(state=present).``  This is italicized…
3565 msgid "``C()`` for files, option values, and inline code. For example: ``If not set the environment…
3569 msgid "``B()`` currently has no standardized usage.  It is displayed in boldface in the documentati…
3573 msgid "``HORIZONTALLINE`` is used sparingly as a separator in long descriptions.  It becomes a hori…
3577 msgid "For links between modules and documentation within a collection, you can use any of the opti…
3581 msgid "To refer to a group of modules in a collection, use ``R()``.  When a collection is not the r…
3585 msgid "``Refer to the R(kubernetes.core collection, plugins_in_kubernetes.core) for information on …
3589 msgid "``The C(win_*) modules (spread across several collections) allow you to manage various aspec…
3593 msgid "Because it stands out better, use ``seealso`` for general references over the use of notes o…
3597 msgid "Documentation fragments"
3601 msgid "If you are writing multiple related modules, they may share common documentation, such as au…
3605 msgid "Modules should only use items from a doc fragment if the module will implement all of the in…
3609 msgid "By default, only the ``DOCUMENTATION`` property from a doc fragment is inserted into the mod…
3613 msgid "Here is an example doc fragment named ``example_fragment.py``:"
3617 msgid "To insert the contents of ``OTHER`` in a module:"
3621 msgid "Or use both :"
3625 msgid "Since Ansible 2.8, you can have user-supplied doc_fragments by using a ``doc_fragments`` dir…
3629 msgid "For example, all AWS modules should include:"
3633 msgid ":ref:`docfragments_collections` describes how to incorporate documentation fragments in a co…
3637 msgid "EXAMPLES block"
3641 msgid "After the shebang, the UTF-8 coding, the copyright line, the license section, and the ``DOCU…
3645 msgid "Per playbook best practices, each example should include a ``name:`` line::"
3649 msgid "The ``name:`` line should be capitalized and not include a trailing dot."
3653 msgid "Use a fully qualified collection name (FQCN) as a part of the module's name like in the exam…
3657 msgid "If your examples use boolean options, use yes/no values. Since the documentation generates b…
3661 msgid "If your module returns facts that are often needed, an example of how to use them can be hel…
3665 msgid "RETURN block"
3669 msgid "After the shebang, the UTF-8 coding, the copyright line, the license section, ``DOCUMENTATIO…
3673 msgid "If your module doesn't return anything (apart from the standard returns), this section of yo…
3677 msgid "return name"
3681 msgid "Name of the returned field."
3685 msgid "Detailed description of what this value represents. Capitalized and with trailing dot."
3689 msgid "returned"
3693 msgid "When this value is returned, such as ``always``, ``changed`` or ``success``. This is a strin…
3697 msgid "Data type."
3701 msgid "If ``type='list'``, specifies the data type of the list's elements."
3705 msgid "sample"
3709 msgid "One or more examples."
3713 msgid "Only needed if this return was extended after initial Ansible release, in other words, this …
3717 msgid "contains"
3721 msgid "Optional. To describe nested return values, set ``type: dict``, or ``type: list``/``elements…
3725 msgid "Here are two example ``RETURN`` sections, one with three simple fields and one with a comple…
3729 msgid "Python imports"
3733 msgid "After the shebang, the UTF-8 coding, the copyright line, the license, and the sections for `…
3737 msgid "The use of \"wildcard\" imports such as ``from module_utils.basic import *`` is no longer al…
3742 msgid "Testing module documentation"
3746 msgid "To test Ansible documentation locally please :ref:`follow instruction<testing_module_documen…
3750 msgid "Developing Ansible modules"
3754 msgid "A module is a reusable, standalone script that Ansible runs on your behalf, either locally o…
3758 msgid "If you need functionality that is not available in any of the thousands of Ansible modules f…
3762 msgid "Preparing an environment for developing Ansible modules"
3766 msgid "Installing prerequisites via apt (Ubuntu)"
3771 msgid "Due to dependencies (for example ansible -> paramiko -> pynacl -> libffi):"
3775 msgid "Installing prerequisites via yum (CentOS)"
3779 msgid "Creating a development environment (platform-agnostic steps)"
3783 msgid "Clone the Ansible repository: ``$ git clone https://github.com/ansible/ansible.git``"
3787 msgid "Change directory into the repository root dir: ``$ cd ansible``"
3791 msgid "Create a virtual environment: ``$ python3 -m venv venv`` (or for Python 2 ``$ virtualenv ven…
3795 msgid "Activate the virtual environment: ``$ . venv/bin/activate``"
3799 msgid "Install development requirements: ``$ pip install -r requirements.txt``"
3803 msgid "Run the environment setup script for each new dev shell process: ``$ . hacking/env-setup``"
3807 msgid "After the initial setup above, every time you are ready to start developing Ansible you shou…
3811 msgid "Creating an info or a facts module"
3815 msgid "Ansible gathers information about the target machines using facts modules, and gathers infor…
3819 msgid "In Ansible 2.8 and onwards, we have two type of information modules, they are ``*_info`` and…
3823 msgid "If a module is named ``<something>_facts``, it should be because its main purpose is returni…
3827 msgid "Modules that query/return general information (and not ``ansible_facts``) should be named ``…
3831 msgid "Info and facts modules, are just like any other Ansible Module, with a few minor requirement…
3835 msgid "They MUST be named ``<something>_info`` or ``<something>_facts``, where <something> is singu…
3839 msgid "Info ``*_info`` modules MUST return in the form of the :ref:`result dictionary<common_return…
3843 msgid "Fact ``*_facts`` modules MUST return in the ``ansible_facts`` field of the :ref:`result dict…
3847 msgid "They MUST support :ref:`check_mode <check_mode_dry>`."
3851 msgid "They MUST NOT make any changes to the system."
3855 msgid "They MUST document the :ref:`return fields<return_block>` and :ref:`examples<examples_block>…
3859 msgid "To create an info module:"
3863 msgid "Navigate to the correct directory for your new module: ``$ cd lib/ansible/modules/``. If you…
3867 msgid "Create your new module file: ``$ touch my_test_info.py``."
3871 msgid "Paste the content below into your new info module file. It includes the :ref:`required Ansib…
3875 msgid "Modify and extend the code to do what you want your new info module to do. See the :ref:`pro…
3879 msgid "Use the same process to create a facts module."
3883 msgid "Creating a module"
3887 msgid "To create a module:"
3891 msgid "Navigate to the correct directory for your new module: ``$ cd lib/ansible/modules/``. If you…
3895 msgid "Create your new module file: ``$ touch my_test.py``."
3899 msgid "Paste the content below into your new module file. It includes the :ref:`required Ansible fo…
3903 msgid "Modify and extend the code to do what you want your new module to do. See the :ref:`programm…
3907 msgid "Verifying your module code"
3911 msgid "After you modify the sample code above to do what you want, you can try out your module. Our…
3915 msgid "Verifying your module code locally"
3919 msgid "If your module does not need to target a remote host, you can quickly and easily exercise yo…
3923 msgid "Create an arguments file, a basic JSON config file that passes parameters to your module so …
3927 msgid "If you are using a virtual environment (which is highly recommended for development) activat…
3931 msgid "Set up the environment for development: ``$ . hacking/env-setup``"
3935 msgid "Run your test module locally and directly: ``$ python -m ansible.modules.my_test /tmp/args.j…
3939 msgid "This should return output like this:"
3943 msgid "Verifying your module code in a playbook"
3947 msgid "The next step in verifying your new module is to consume it with an Ansible playbook."
3951 msgid "Create a playbook in any directory: ``$ touch testmod.yml``"
3956 msgid "Add the following to the new playbook file::"
3960 msgid "Run the playbook and analyze the output: ``$ ansible-playbook ./testmod.yml``"
3964 msgid "Testing your newly-created module"
3968 msgid "The following two examples will get you started with testing your module code. Please review…
3973 msgid "Every new module and plugin should have integration tests, even if the tests cannot be run o…
3977 msgid "Performing sanity tests"
3981 msgid "You can run through Ansible's sanity checks in a container:"
3985 msgid "``$ ansible-test sanity -v --docker --python 2.7 MODULE_NAME``"
3989 msgid "Note that this example requires Docker to be installed and running. If you'd rather not use …
3993 msgid "You can add unit tests for your module in ``./test/units/modules``. You must first set up yo…
3997 msgid "Install the requirements (outside of your virtual environment): ``$ pip3 install -r ./test/l…
4001 msgid "Run ``. hacking/env-setup``"
4005 msgid "To run all tests do the following: ``$ ansible-test units --python 3.5``. If you are using a…
4009 msgid "Ansible uses pytest for unit testing."
4013 msgid "To run pytest against a single test module, you can run the following command. Ensure that y…
4017 msgid "``$ pytest -r a --cov=. --cov-report=html --fulltrace --color yes test/units/modules/.../tes…
4021 msgid "Contributing back to Ansible"
4025 msgid "If you would like to contribute to ``ansible-core`` by adding a new feature or fixing a bug,…
4029 msgid "If you want to contribute a module to an :ref:`Ansible collection <contributing_maintained_c…
4033 msgid "The :ref:`Community Guide <ansible_community_guide>` covers how to open a pull request and w…
4037 msgid "Communication and development support"
4041 msgid "Join the IRC channel ``#ansible-devel`` on `irc.libera.chat <https://libera.chat/>`_ for dis…
4046 msgid "For questions and discussions pertaining to using the Ansible product, use the ``#ansible`` …
4050 msgid "For more specific IRC channels look at :ref:`Community Guide, Communicating <communication_i…
4054 msgid "Credit"
4058 msgid "Thank you to Thomas Stringer (`@trstringer <https://github.com/trstringer>`_) for contributi…
4062 msgid "Developing Cisco ACI modules"
4066 msgid "This is a brief walk-through of how to create new Cisco ACI modules for Ansible."
4070 msgid "For more information about Cisco ACI, look at the :ref:`Cisco ACI user guide <aci_guide>`."
4075 msgid "What's covered in this section:"
4080 msgid "Introduction"
4084 msgid "The `cisco.aci collection <https://galaxy.ansible.com/cisco/aci>`_ already includes a large …
4088 msgid "If you need specific functionality, you have 2 options:"
4092 msgid "Learn the ACI object model and use the low-level APIC REST API using the :ref:`aci_rest <aci…
4096 msgid "Write your own dedicated modules, which is actually quite easy"
4100 msgid "`ACI Fundamentals: ACI Policy Model <https://www.cisco.com/c/en/us/td/docs/switches/datacent…
4104 msgid "A good introduction to the ACI object model."
4108 msgid "`APIC Management Information Model reference <https://developer.cisco.com/docs/apic-mim-ref/…
4112 msgid "Complete reference of the APIC object model."
4116 msgid "`APIC REST API Configuration Guide <https://www.cisco.com/c/en/us/td/docs/switches/datacente…
4120 msgid "Detailed guide on how the APIC REST API is designed and used, incl. many examples."
4124 msgid "So let's look at how a typical ACI module is built up."
4128 msgid "ACI module structure"
4132 msgid "Importing objects from Python libraries"
4136 msgid "The following imports are standard across ACI modules:"
4140 msgid "Defining the argument spec"
4144 msgid "The first line adds the standard connection parameters to the module. After that, the next s…
4148 msgid "the object_id (usually the name)"
4152 msgid "the configurable properties of the object"
4156 msgid "the parent object IDs (all parents up to the root)"
4160 msgid "only child classes that are a 1-to-1 relationship (1-to-many/many-to-many require their own …
4164 msgid "the state"
4168 msgid "``state: absent`` to ensure object does not exist"
4172 msgid "``state: present`` to ensure the object and configs exist; this is also the default"
4176 msgid "``state: query`` to retrieve information about objects in the class"
4180 msgid "Do not provide default values for configuration arguments. Default values could cause uninte…
4184 msgid "Using the AnsibleModule object"
4188 msgid "The following section creates an AnsibleModule instance. The module should support check-mod…
4192 msgid "Mapping variable definition"
4196 msgid "Once the AnsibleModule object has been initiated, the necessary parameter values should be e…
4200 msgid "Using the ACIModule object"
4204 msgid "The ACIModule class handles most of the logic for the ACI modules. The ACIModule extends fun…
4208 msgid "The ACIModule has six main methods that are used by the modules:"
4212 msgid "construct_url"
4216 msgid "get_existing"
4220 msgid "payload"
4224 msgid "get_diff"
4228 msgid "post_config"
4232 msgid "delete_config"
4236 msgid "The first two methods are used regardless of what value is passed to the ``state`` parameter…
4240 msgid "Constructing URLs"
4244 msgid "The ``construct_url()`` method is used to dynamically build the appropriate URL to interact …
4248 msgid "When the ``state`` is not ``query``, the URL is the base URL to access the APIC plus the dis…
4252 msgid "When ``state`` is ``query``, the URL and filter string used depends on what parameters are p…
4256 msgid "Our design goal is to take all ID parameters that have values, and return the most specific …
4260 msgid "The ``construct_url()`` method takes 2 required arguments:"
4264 msgid "**self** - passed automatically with the class instance"
4268 msgid "**root_class** - A dictionary consisting of ``aci_class``, ``aci_rn``, ``target_filter``, an…
4272 msgid "**aci_class**: The name of the class used by the APIC, for example ``fvTenant``"
4276 msgid "**aci_rn**: The relative name of the object, for example ``tn-ACME``"
4280 msgid "**target_filter**: A dictionary with key-value pairs that make up the query string for selec…
4284 msgid "**module_object**: The particular object for this class, for example ``ACME``"
4298 msgid "Example:"
4302 msgid "Some modules, like ``aci_tenant``, are the root class and so they would not need to pass any…
4306 msgid "The ``construct_url()`` method takes 4 optional arguments, the first three imitate the root …
4310 msgid "subclass_1 - A dictionary consisting of ``aci_class``, ``aci_rn``, ``target_filter``, and ``…
4314 msgid "Example: Application Profile Class (AP)"
4318 msgid "subclass_2 - A dictionary consisting of ``aci_class``, ``aci_rn``, ``target_filter``, and ``…
4322 msgid "Example: End Point Group (EPG)"
4326 msgid "subclass_3 - A dictionary consisting of ``aci_class``, ``aci_rn``, ``target_filter``, and ``…
4330 msgid "Example: Binding a Contract to an EPG"
4334 msgid "child_classes - The list of APIC names for the child classes supported by the modules."
4338 msgid "This is a list, even if it is a list of one"
4342 msgid "These are the unfriendly names used by the APIC"
4346 msgid "These are used to limit the returned child_classes when possible"
4350 msgid "Example: ``child_classes=['fvRsBDSubnetToProfile', 'fvRsNdPfxPol']``"
4354 msgid "Sometimes the APIC will require special characters ([, ], and -) or will use object metadata…
4358 msgid "Getting the existing configuration"
4362 msgid "Once the URL and filter string have been built, the module is ready to retrieve the existing…
4366 msgid "``state: present`` retrieves the configuration to use as a comparison against what was enter…
4370 msgid "``state: absent`` uses the existing configuration to see if the item exists and needs to be …
4374 msgid "``state: query`` uses this to perform the query for the task and report back the existing da…
4378 msgid "When state is present"
4382 msgid "When ``state: present``, the module needs to perform a diff against the existing configurati…
4386 msgid "Building the ACI payload"
4390 msgid "The ``aci.payload()`` method is used to build a dictionary of the proposed object configurat…
4394 msgid "The ``aci.payload()`` method takes two required arguments and 1 optional argument, depending…
4398 msgid "``aci_class`` is the APIC name for the object's class, for example ``aci_class='fvBD'``"
4402 msgid "``class_config`` is the appropriate dictionary to be used as the payload for the POST reques…
4406 msgid "The keys should match the names used by the APIC."
4410 msgid "The values should be the corresponding value in ``module.params``; these are the variables d…
4414 msgid "``child_configs`` is optional, and is a list of child config dictionaries."
4418 msgid "The child configs include the full child object dictionary, not just the attributes configur…
4422 msgid "The configuration portion is built the same way as the object."
4426 msgid "Performing the request"
4430 msgid "The ``get_diff()`` method is used to perform the diff, and takes only one required argument,…
4434 msgid "The ``post_config()`` method is used to make the POST request to the APIC if needed. This me…
4438 msgid "Example code"
4442 msgid "When state is absent"
4446 msgid "If the task sets the state to absent, then the ``delete_config()`` method is all that is nee…
4450 msgid "Exiting the module"
4454 msgid "To have the module exit, call the ACIModule method ``exit_json()``. This method automaticall…
4458 msgid "Testing ACI library functions"
4462 msgid "You can test your ``construct_url()`` and ``payload()`` arguments without accessing APIC har…
4466 msgid "This will result in:"
4470 msgid "Testing for sanity checks"
4474 msgid "You can run from your fork something like:"
4479 msgid ":ref:`testing_sanity`"
4483 msgid "Information on how to build sanity tests."
4487 msgid "Testing ACI integration tests"
4492 msgid "You can run this:"
4496 msgid "You may need to add ``--python 2.7`` or ``--python 3.6`` in order to use the correct python …
4500 msgid "You may want to edit the used inventory at *test/integration/inventory.networking* and add s…
4505 msgid ":ref:`testing_integration`"
4509 msgid "Information on how to build integration tests."
4513 msgid "Testing for test coverage"
4517 msgid "Windows module development walkthrough"
4521 msgid "In this section, we will walk through developing, testing, and debugging an Ansible Windows …
4525 msgid "Because Windows modules are written in Powershell and need to be run on a Windows host, this…
4529 msgid "Windows environment setup"
4533 msgid "Unlike Python module development which can be run on the host that runs Ansible, Windows mod…
4538 msgid "This guide will use the Vagrant boxes created by the `packer-windoze <https://github.com/jbo…
4542 msgid "Before you can get started, the following programs must be installed (please consult the Vag…
4546 msgid "Vagrant"
4550 msgid "VirtualBox"
4554 msgid "Create a Windows server in a VM"
4558 msgid "To create a single Windows Server 2016 instance, run the following:"
4562 msgid "This will download the Vagrant box from Vagrant Cloud and add it to the local boxes on your …
4566 msgid "Create an Ansible inventory"
4570 msgid "The following Ansible inventory file can be used to connect to the newly created Windows VM:"
4574 msgid "The port ``55986`` is automatically forwarded by Vagrant to the Windows host that was create…
4578 msgid "The OS that is created is based on the image set. The following images can be used:"
4582 msgid "`jborean93/WindowsServer2008-x86 <https://app.vagrantup.com/jborean93/boxes/WindowsServer200…
4586 msgid "`jborean93/WindowsServer2008-x64 <https://app.vagrantup.com/jborean93/boxes/WindowsServer200…
4590 msgid "`jborean93/WindowsServer2008R2 <https://app.vagrantup.com/jborean93/boxes/WindowsServer2008R…
4594 msgid "`jborean93/WindowsServer2012 <https://app.vagrantup.com/jborean93/boxes/WindowsServer2012>`_"
4598 msgid "`jborean93/WindowsServer2012R2 <https://app.vagrantup.com/jborean93/boxes/WindowsServer2012R…
4602 msgid "`jborean93/WindowsServer2016 <https://app.vagrantup.com/jborean93/boxes/WindowsServer2016>`_"
4606 msgid "`jborean93/WindowsServer2019 <https://app.vagrantup.com/jborean93/boxes/WindowsServer2019>`_"
4610 msgid "When the host is online, it can accessible by RDP on ``127.0.0.1:3389`` but the port may dif…
4614 msgid "While this is useful when testing modules on a single Windows instance, these host won't wor…
4618 msgid "``Vagrantfile``: The Vagrant file that reads the inventory setup of ``inventory.yml`` and pr…
4622 msgid "``inventory.yml``: Contains the hosts that are required and other connection information suc…
4626 msgid "``main.yml``: Ansible playbook called by Vagrant to provision the domain controller and join…
4630 msgid "By default, these files will create the following environment:"
4634 msgid "A single domain controller running on Windows Server 2016"
4638 msgid "Five child hosts for each major Windows Server version joined to that domain"
4642 msgid "A domain with the DNS name ``domain.local``"
4646 msgid "A local administrator account on each host with the username ``vagrant`` and password ``vagr…
4650 msgid "A domain admin account ``vagrant-domain@domain.local`` with the password ``VagrantPass1``"
4654 msgid "The domain name and accounts can be modified by changing the variables ``domain_*`` in the `…
4658 msgid "Provisioning the environment"
4662 msgid "To provision the environment as is, run the following:"
4666 msgid "Vagrant provisions each host sequentially so this can take some time to complete. If any err…
4670 msgid "Unlike setting up a single Windows instance with Vagrant, these hosts can also be accessed u…
4674 msgid "``RDP``: 295xx"
4678 msgid "``SSH``: 296xx"
4682 msgid "``WinRM HTTP``: 297xx"
4686 msgid "``WinRM HTTPS``: 298xx"
4690 msgid "``SMB``: 299xx"
4694 msgid "Replace ``xx`` with the entry number in the inventory file where the domain controller start…
4698 msgid "While an SSH server is available on all Windows hosts but Server 2008 (non R2), it is not a …
4702 msgid "Windows new module development"
4706 msgid "When creating a new module there are a few things to keep in mind:"
4710 msgid "Module code is in Powershell (.ps1) files while the documentation is contained in Python (.p…
4714 msgid "Avoid using ``Write-Host/Debug/Verbose/Error`` in the module and add what needs to be return…
4718 msgid "To fail a module, call ``$module.FailJson(\"failure message here\")``, an Exception or Error…
4722 msgid "You can pass in the exception or ErrorRecord as a second argument to ``FailJson(\"failure\",…
4726 msgid "Most new modules require check mode and integration tests before they are merged into the ma…
4730 msgid "Avoid using try/catch statements over a large code block, rather use them for individual cal…
4734 msgid "Try and catch specific exceptions when using try/catch statements"
4738 msgid "Avoid using PSCustomObjects unless necessary"
4742 msgid "Look for common functions in ``./lib/ansible/module_utils/powershell/`` and use the code the…
4746 msgid "As well as PowerShell module utils, C# module utils are stored in ``./lib/ansible/module_uti…
4750 msgid "C# and PowerShell module utils achieve the same goal but C# allows a developer to implement …
4754 msgid "Ensure the code runs under Powershell v3 and higher on Windows Server 2008 and higher; if hi…
4758 msgid "Ansible runs modules under strictmode version 2.0. Be sure to test with that enabled by putt…
4762 msgid "Favor native Powershell cmdlets over executable calls if possible"
4766 msgid "Use the full cmdlet name instead of aliases, for example ``Remove-Item`` over ``rm``"
4770 msgid "Use named parameters with cmdlets, for example ``Remove-Item -Path C:\\temp`` over ``Remove-…
4774 msgid "A very basic Powershell module `win_environment <https://github.com/ansible-collections/ansi…
4778 msgid "A slightly more advanced module is `win_uri <https://github.com/ansible-collections/ansible.…
4782 msgid "As part of the new ``AnsibleModule`` wrapper, the input parameters are defined and validated…
4786 msgid "``mutually_exclusive``: A list of lists, where the inner list contains module options that c…
4790 msgid "``no_log``: Stops the module from emitting any logs to the Windows Event log"
4794 msgid "``options``: A dictionary where the key is the module option and the value is the spec for t…
4798 msgid "``required_by``: A dictionary where the option(s) specified by the value must be set if the …
4802 msgid "``required_if``: A list of lists where the inner list contains 3 or 4 elements;"
4806 msgid "The first element is the module option to check the value against"
4810 msgid "The second element is the value of the option specified by the first element, if matched the…
4814 msgid "The third element is a list of required module options when the above is matched"
4818 msgid "An optional fourth element is a boolean that states whether all module options in the third …
4822 msgid "``required_one_of``: A list of lists, where the inner list contains module options where at …
4826 msgid "``required_together``: A list of lists, where the inner list contains module options that mu…
4830 msgid "``supports_check_mode``: Whether the module supports check mode, by default this is ``$false…
4834 msgid "The actual input options for a module are set within the ``options`` value as a dictionary. …
4838 msgid "``aliases``: A list of aliases for the module option"
4842 msgid "``choices``: A list of valid values for the module option, if ``type=list`` then each list v…
4846 msgid "``default``: The default value for the module option if not set"
4850 msgid "``deprecated_aliases``: A list of hashtables that define aliases that are deprecated and the…
4854 msgid "``elements``: When ``type=list``, this sets the type of each list value, the values are the …
4858 msgid "``no_log``: Will sanitise the input value before being returned in the ``module_invocation``…
4862 msgid "``removed_in_version``: States when a deprecated module option is to be removed, a warning i…
4866 msgid "``removed_at_date``: States the date (YYYY-MM-DD) when a deprecated module option will be re…
4870 msgid "``removed_from_collection``: States from which collection the deprecated module option will …
4874 msgid "``required``: Will fail when the module option is not set"
4878 msgid "``type``: The type of the module option, if not set then it defaults to ``str``. The valid t…
4882 msgid "``bool``: A boolean value"
4886 msgid "``dict``: A dictionary value, if the input is a JSON or key=value string then it is converte…
4890 msgid "``float``: A float or `Single <https://docs.microsoft.com/en-us/dotnet/api/system.single?vie…
4894 msgid "``int``: An Int32 value"
4898 msgid "``json``: A string where the value is converted to a JSON string if the input is a dictionar…
4902 msgid "``list``: A list of values, ``elements=<type>`` can convert the individual list value types …
4906 msgid "``path``: A string where values likes ``%TEMP%`` are expanded based on environment values. I…
4910 msgid "``raw``: No conversions occur on the value passed in by Ansible"
4914 msgid "``sid``: Will convert Windows security identifier values or Windows account names to a `Secu…
4918 msgid "``str``: The value is converted to a string"
4922 msgid "When ``type=dict``, or ``type=list`` and ``elements=dict``, the following keys can also be s…
4926 msgid "``apply_defaults``: The value is based on the ``options`` spec defaults for that key if ``Tr…
4930 msgid "``mutually_exclusive``: Same as the root level ``mutually_exclusive`` but validated against …
4934 msgid "``options``: Same as the root level ``options`` but contains the valid options for the sub o…
4938 msgid "``required_if``: Same as the root level ``required_if`` but validated against the values in …
4942 msgid "``required_by``: Same as the root level ``required_by`` but validated against the values in …
4946 msgid "``required_together``: Same as the root level ``required_together`` but validated against th…
4950 msgid "``required_one_of``: Same as the root level ``required_one_of`` but validated against the va…
4954 msgid "A module type can also be a delegate function that converts the value to whatever is require…
4958 msgid "When in doubt, look at some of the other core modules and see how things have been implement…
4962 msgid "Sometimes there are multiple ways that Windows offers to complete a task; this is the order …
4966 msgid "Native Powershell cmdlets like ``Remove-Item -Path C:\\temp -Recurse``"
4970 msgid ".NET classes like ``[System.IO.Path]::GetRandomFileName()``"
4974 msgid "WMI objects through the ``New-CimInstance`` cmdlet"
4978 msgid "COM objects through ``New-Object -ComObject`` cmdlet"
4982 msgid "Calls to native executables like ``Secedit.exe``"
4986 msgid "PowerShell modules support a small subset of the ``#Requires`` options built into PowerShell…
4990 msgid "These are the checks that can be used within Ansible modules:"
4994 msgid "``#Requires -Module Ansible.ModuleUtils.<module_util>``: Added in Ansible 2.4, specifies a m…
4998 msgid "``#Requires -Version x.y``: Added in Ansible 2.5, specifies the version of PowerShell that i…
5002 msgid "``#AnsibleRequires -OSVersion x.y``: Added in Ansible 2.5, specifies the OS build version th…
5006 msgid "``#AnsibleRequires -Become``: Added in Ansible 2.5, forces the exec runner to run the module…
5010 msgid "``#AnsibleRequires -CSharpUtil Ansible.<module_util>``: Added in Ansible 2.8, specifies a C#…
5014 msgid "C# module utils can reference other C# utils by adding the line ``using Ansible.<module_util…
5018 msgid "Windows module utilities"
5022 msgid "Like Python modules, PowerShell modules also provide a number of module utilities that provi…
5026 msgid "This will import the module_util at ``./lib/ansible/module_utils/powershell/Ansible.ModuleUt…
5030 msgid "This will import the module_util at ``./lib/ansible/module_utils/csharp/Ansible.Basic.cs`` a…
5034 msgid "There are special comments that can be set in a C# file for controlling the compilation para…
5038 msgid "``//AssemblyReference -Name <assembly dll> [-CLR [Core|Framework]]``: The assembly DLL to re…
5042 msgid "``//NoWarn -Name <error id> [-CLR [Core|Framework]]``: A compiler warning ID to ignore when …
5046 msgid "As well as this, the following pre-processor symbols are defined;"
5050 msgid "``CORECLR``: This symbol is present when PowerShell is running through .NET Core"
5054 msgid "``WINDOWS``: This symbol is present when PowerShell is running on Windows"
5058 msgid "``UNIX``: This symbol is present when PowerShell is running on Unix"
5062 msgid "A combination of these flags help to make a module util interoperable on both .NET Framework…
5066 msgid "The following is a list of module_utils that are packaged with Ansible and a general descrip…
5070 msgid "ArgvParser: Utility used to convert a list of arguments to an escaped string compliant with …
5074 msgid "CamelConversion: Utility used to convert camelCase strings/lists/dicts to snake_case."
5078 msgid "CommandUtil: Utility used to execute a Windows process and return the stdout/stderr and rc a…
5082 msgid "FileUtil: Utility that expands on the ``Get-ChildItem`` and ``Test-Path`` to work with speci…
5086 msgid "Legacy: General definitions and helper utilities for Ansible module."
5090 msgid "LinkUtil: Utility to create, remove, and get information about symbolic links, junction poin…
5094 msgid "SID: Utilities used to convert a user or group to a Windows SID and vice versa."
5098 msgid "For more details on any specific module utility and their requirements, please see the `Ansi…
5102 msgid "PowerShell module utilities can be stored outside of the standard Ansible distribution for u…
5106 msgid "C# module utilities can also be stored outside of the standard Ansible distribution for use …
5110 msgid "The below example is a role structure that contains two PowerShell custom module_utils calle…
5114 msgid "Each PowerShell module_util must contain at least one function that has been exported with `…
5118 msgid "Exposing shared module options"
5122 msgid "PowerShell module utils can easily expose common module options that a module can use when b…
5126 msgid "An example of this would be to have a module util that handles authentication and communicat…
5130 msgid "The standard convention for a module util that has a shared argument spec would have"
5134 msgid "A ``Get-<namespace.name.util name>Spec`` function that outputs the common spec for a module"
5138 msgid "It is highly recommended to make this function name be unique to the module to avoid any con…
5142 msgid "The format of the output spec is a Hashtable in the same format as the ``$spec`` used for no…
5146 msgid "A function that takes in an ``AnsibleModule`` object called under the ``-Module`` parameter …
5150 msgid "Because these options can be shared across various module it is highly recommended to keep t…
5154 msgid "Failure to have a unique option name or alias can prevent the util being used by module that…
5158 msgid "The following is an example module util called ``ServiceAuth.psm1`` in a collection that imp…
5162 msgid "For a module to take advantage of this common argument spec it can be set out like"
5166 msgid "Options defined in the module spec will always have precedence over a util spec. Any list va…
5170 msgid "To document these shared util options for a module, create a doc fragment plugin that docume…
5174 msgid "Windows playbook module testing"
5178 msgid "You can test a module with an Ansible playbook. For example:"
5182 msgid "Create a playbook in any directory ``touch testmodule.yml``."
5186 msgid "Create an inventory file in the same directory ``touch hosts``."
5190 msgid "Populate the inventory file with the variables required to connect to a Windows host(s)."
5194 msgid "Run the playbook ``ansible-playbook -i hosts testmodule.yml``"
5198 msgid "This can be useful for seeing how Ansible runs with the new module end to end. Other possibl…
5202 msgid "Windows debugging"
5206 msgid "Debugging a module currently can only be done on a Windows host. This can be useful when dev…
5210 msgid "Copy the module script to the Windows server"
5214 msgid "Copy the folders ``./lib/ansible/module_utils/powershell`` and ``./lib/ansible/module_utils/…
5218 msgid "Add an extra ``#`` to the start of any ``#Requires -Module`` lines in the module code, this …
5222 msgid "Add the following to the start of the module script that was copied to the server:"
5226 msgid "You can add more args to ``$complex_args`` as required by the module or define the module op…
5230 msgid "There are multiple IDEs that can be used to debug a Powershell script, two of the most popul…
5234 msgid "`Powershell ISE`_"
5238 msgid "`Visual Studio Code`_"
5242 msgid "To be able to view the arguments as passed by Ansible to the module follow these steps."
5246 msgid "Prefix the Ansible command with :envvar:`ANSIBLE_KEEP_REMOTE_FILES=1<ANSIBLE_KEEP_REMOTE_FIL…
5250 msgid "Log onto the Windows server using the same user account that Ansible used to execute the mod…
5254 msgid "Navigate to ``%TEMP%\\..``. It should contain a folder starting with ``ansible-tmp-``."
5258 msgid "Inside this folder, open the PowerShell script for the module."
5262 msgid "In this script is a raw JSON script under ``$json_raw`` which contains the module arguments …
5266 msgid "Windows unit testing"
5270 msgid "Currently there is no mechanism to run unit tests for Powershell modules under Ansible CI."
5274 msgid "Windows integration testing"
5278 msgid "Integration tests for Ansible modules are typically written as Ansible roles. These test rol…
5282 msgid "In this example we will set up a test inventory to connect to two hosts and run the integrat…
5286 msgid "Run the command ``source ./hacking/env-setup`` to prepare environment."
5290 msgid "Create a copy of ``./test/integration/inventory.winrm.template`` and name it ``inventory.win…
5294 msgid "Fill in entries under ``[windows]`` and set the required variables that are needed to connec…
5298 msgid ":ref:`Install the required Python modules <windows_winrm>` to support WinRM and a configured…
5302 msgid "To execute the integration tests, run ``ansible-test windows-integration win_stat``; you can…
5306 msgid "This will execute all the tests currently defined for that role. You can set the verbosity l…
5310 msgid "When developing tests for a new module, it is recommended to test a scenario once in check m…
5314 msgid "Windows communication and development support"
5318 msgid "Join the ``#ansible-devel`` or ``#ansible-windows`` irc channels on `irc.libera.chat <https:…
5322 msgid "Creating a new collection"
5326 msgid "Starting with Ansible 2.10, related modules should be developed in a collection. The Ansible…
5330 msgid "Before you start coding"
5334 msgid "This list of prerequisites is designed to help ensure that you develop high-quality modules …
5338 msgid "Read though all the pages linked off :ref:`developing_modules_general`; paying particular fo…
5342 msgid "We encourage PEP 8 compliance. See :ref:`testing_pep8` for more information."
5346 msgid "We encourage supporting :ref:`Python 2.6+ and Python 3.5+ <developing_python_3>`."
5350 msgid "Look at Ansible Galaxy and review the naming conventions in your functional area (such as cl…
5354 msgid "With great power comes great responsibility: Ansible collection maintainers have a duty to h…
5358 msgid "We strongly recommend unit and/or integration tests. Unit tests are especially valuable when…
5362 msgid "Naming conventions"
5366 msgid "Fully Qualified Collection Names (FQCNs) for plugins and modules include three elements:"
5370 msgid "the Galaxy namespace, which generally represents the company or group"
5374 msgid "the collection name, which generally represents the product or OS"
5378 msgid "the plugin or module name"
5382 msgid "always in lower case"
5386 msgid "words separated with an underscore (``_``) character"
5390 msgid "singular, rather than plural, for example, ``command`` not ``commands``"
5394 msgid "For example, ``community.mongodb.mongodb_linux`` or ``cisco.meraki.meraki_device``."
5398 msgid "It is convenient if the organization and repository names on GitHub (or elsewhere) match you…
5402 msgid "Speak to us"
5406 msgid "Circulating your ideas before coding helps you adopt good practices and avoid common mistake…
5410 msgid "Where to get support"
5414 msgid "Ansible has a thriving and knowledgeable community of module developers that is a great reso…
5418 msgid "In the :ref:`ansible_community_guide` you can find how to:"
5422 msgid "Subscribe to the Mailing Lists - We suggest \"Ansible Development List\" and \"Ansible Annou…
5426 msgid "``#ansible-devel`` - We have found that communicating on the IRC channel, ``#ansible-devel``…
5430 msgid "IRC meetings - Join the various weekly IRC meetings `meeting schedule and agenda page <https…
5434 msgid "Required files"
5438 msgid "Your collection should include the following files to be usable:"
5442 msgid "an ``__init__.py`` file - An empty file to initialize namespace and allow Python to import t…
5446 msgid "at least one plugin, for example, ``/plugins/modules/$your_first_module.py``. *Required*"
5450 msgid "if needed, one or more ``/plugins/doc_fragments/$topic.py`` files - Code documentation, such…
5454 msgid "if needed, one or more ``/plugins/module_utils/$topic.py`` files - Code shared between more …
5458 msgid "When you have these files ready, review the :ref:`developing_modules_checklist` again. If yo…
5462 msgid "If you need help or advice, consider joining the ``#ansible-devel`` IRC channel (see how in …
5466 msgid "New to git or GitHub"
5470 msgid "We realize this may be your first use of Git or GitHub. The following guides may be of use:"
5474 msgid "`How to create a fork of ansible/ansible <https://help.github.com/articles/fork-a-repo/>`_"
5478 msgid "`How to sync (update) your fork <https://help.github.com/articles/syncing-a-fork/>`_"
5482 msgid "`How to create a Pull Request (PR) <https://help.github.com/articles/about-pull-requests/>`_"
5486 msgid "Developing plugins"
5490 msgid "Plugins augment Ansible's core functionality with logic and features that are accessible to …
5494 msgid "be written in Python"
5498 msgid "raise errors"
5502 msgid "return strings in unicode"
5506 msgid "conform to Ansible's configuration and documentation standards"
5510 msgid "Once you've reviewed these general guidelines, you can skip to the particular type of plugin…
5514 msgid "Writing plugins in Python"
5518 msgid "You must write your plugin in Python so it can be loaded by the ``PluginLoader`` and returne…
5522 msgid "Raising errors"
5526 msgid "You should return errors encountered during plugin execution by raising ``AnsibleError()`` o…
5530 msgid "Check the different `AnsibleError objects <https://github.com/ansible/ansible/blob/devel/lib…
5534 msgid "String encoding"
5538 msgid "You must convert any strings returned by your plugin into Python's unicode type. Converting …
5542 msgid "Plugin configuration & documentation standards"
5546 msgid "To define configurable options for your plugin, describe them in the ``DOCUMENTATION`` secti…
5550 msgid "To access the configuration settings in your plugin, use ``self.get_option(<option_name>)``.…
5554 msgid "Plugins that support embedded documentation (see :ref:`ansible-doc` for the list) should inc…
5558 msgid "Developing particular plugin types"
5563 msgid "Action plugins"
5567 msgid "Action plugins let you integrate local processing and local data with module functionality."
5571 msgid "To create an action plugin, create a new class with the Base(ActionBase) class as the parent…
5575 msgid "From there, execute the module using the ``_execute_module`` method to call the original mod…
5579 msgid "For example, if you wanted to check the time difference between your Ansible controller and …
5583 msgid "This code checks the time on the controller, captures the date and time for the remote machi…
5587 msgid "For practical examples of action plugins, see the source code for the `action plugins includ…
5591 msgid "Cache plugins"
5595 msgid "Cache plugins store gathered facts and data retrieved by inventory plugins."
5599 msgid "Import cache plugins using the cache_loader so you can use ``self.set_options()`` and ``self…
5603 msgid "There are two base classes for cache plugins, ``BaseCacheModule`` for database-backed caches…
5607 msgid "To create a cache plugin, start by creating a new ``CacheModule`` class with the appropriate…
5611 msgid "New cache plugins should take the options ``_uri``, ``_prefix``, and ``_timeout`` to be cons…
5615 msgid "If you use the ``BaseCacheModule``, you must implement the methods ``get``, ``contains``, ``…
5619 msgid "If you use the ``BaseFileCacheModule``, you must implement ``_load`` and ``_dump`` methods t…
5623 msgid "If your cache plugin stores JSON, use ``AnsibleJSONEncoder`` in the ``_dump`` or ``set`` met…
5627 msgid "For example cache plugins, see the source code for the `cache plugins included with Ansible …
5631 msgid "Callback plugins"
5635 msgid "Callback plugins add new behaviors to Ansible when responding to events. By default, callbac…
5639 msgid "To create a callback plugin, create a new class with the Base(Callbacks) class as the parent…
5643 msgid "From there, override the specific methods from the CallbackBase that you want to provide a c…
5647 msgid "The following is a modified example of how Ansible's timer plugin is implemented, but with a…
5651 msgid "Note that the ``CALLBACK_VERSION`` and ``CALLBACK_NAME`` definitions are required for proper…
5655 msgid "For example callback plugins, see the source code for the `callback plugins included with An…
5659 msgid "New in ansible-core 2.11, callback plugins are notified (via ``v2_playbook_on_task_start``) …
5663 msgid "There are also some tasks which are generated internally and implicitly at various points in…
5667 msgid "Connection plugins"
5671 msgid "Connection plugins allow Ansible to connect to the target hosts so it can execute tasks on t…
5675 msgid "Ansible version 2.1 introduced the ``smart`` connection plugin. The ``smart`` connection typ…
5679 msgid "To create a new connection plugin (for example, to support SNMP, Message bus, or other trans…
5683 msgid "Connection plugins can support common options (such as the ``--timeout`` flag) by defining a…
5687 msgid "For example connection plugins, see the source code for the `connection plugins included wit…
5691 msgid "Filter plugins"
5695 msgid "Filter plugins manipulate data. They are a feature of Jinja2 and are also available in Jinja…
5699 msgid "Filter plugins do not use the standard configuration and documentation system described abov…
5703 msgid "For example filter plugins, see the source code for the `filter plugins included with Ansibl…
5707 msgid "Inventory plugins parse inventory sources and form an in-memory representation of the invent…
5711 msgid "You can see the details for inventory plugins in the :ref:`developing_inventory` page."
5715 msgid "Lookup plugins"
5719 msgid "Lookup plugins pull in data from external data stores. Lookup plugins can be used within pla…
5723 msgid "Lookup plugins are very flexible, allowing you to retrieve and return any type of data. When…
5727 msgid "Ansible includes many :ref:`filters <playbooks_filters>` which can be used to manipulate the…
5731 msgid "Here's a simple lookup plugin implementation --- this lookup returns the contents of a text …
5735 msgid "The following is an example of how this lookup is called:"
5739 msgid "For example lookup plugins, see the source code for the `lookup plugins included with Ansibl…
5743 msgid "For more usage examples of lookup plugins, see :ref:`Using Lookups<playbooks_lookups>`."
5747 msgid "Test plugins"
5751 msgid "Test plugins verify data. They are a feature of Jinja2 and are also available in Jinja2 temp…
5755 msgid "Test plugins do not use the standard configuration and documentation system described above."
5759 msgid "For example test plugins, see the source code for the `test plugins included with Ansible Co…
5763 msgid "Vars plugins"
5767 msgid "Vars plugins inject additional variable data into Ansible runs that did not come from an inv…
5771 msgid "Vars plugins were partially implemented in Ansible 2.0 and rewritten to be fully implemented…
5775 msgid "Older plugins used a ``run`` method as their main body/work:"
5779 msgid "Ansible 2.0 did not pass passwords to older plugins, so vaults were unavailable. Most of the…
5783 msgid "The parameters are:"
5787 msgid "loader: Ansible's DataLoader. The DataLoader can read files, auto-load JSON/YAML and decrypt…
5791 msgid "path: this is 'directory data' for every inventory source and the current play's playbook di…
5795 msgid "entities: these are host or group names that are pertinent to the variables needed. The plug…
5799 msgid "This ``get_vars`` method just needs to return a dictionary structure with the variables."
5803 msgid "Since Ansible version 2.4, vars plugins only execute as needed when preparing to execute a t…
5807 msgid "You can create vars plugins that are not enabled by default using the class variable ``REQUI…
5811 msgid "Include the ``vars_plugin_staging`` documentation fragment to allow users to determine when …
5815 msgid "For example vars plugins, see the source code for the `vars plugins included with Ansible Co…
5819 msgid "Learn about how to develop dynamic inventory sources"
5823 msgid "Ansible module architecture"
5827 msgid "If you are working on the ``ansible-core`` code, writing an Ansible module, or developing an…
5831 msgid "Types of modules"
5835 msgid "Ansible supports several different types of modules in its code base. Some of these are for …
5839 msgid "Action plugins look like modules to anyone writing a playbook. Usage documentation for most …
5843 msgid "Some action plugins do all their work on the controller. For example, the :ref:`debug <debug…
5847 msgid "Most action plugins set up some values on the controller, then invoke an actual module on th…
5851 msgid "New-style modules"
5855 msgid "All of the modules that ship with Ansible fall into this category. While you can write modul…
5859 msgid "New-style modules have the arguments to the module embedded inside of them in some manner. O…
5863 msgid "Python"
5867 msgid "New-style Python modules use the :ref:`Ansiballz` framework for constructing modules. These …
5871 msgid "In Ansible, up to version 2.0.x, the official Python modules used the :ref:`module_replacer`…
5875 msgid "PowerShell"
5879 msgid "New-style PowerShell modules use the :ref:`module_replacer` framework for constructing modul…
5883 msgid "JSONARGS modules"
5887 msgid "These modules are scripts that include the string ``<<INCLUDE_ANSIBLE_MODULE_JSON_ARGS>>`` i…
5891 msgid "Which is expanded as:"
5895 msgid "Ansible outputs a :term:`JSON` string with bare quotes. Double quotes are used to quote stri…
5899 msgid "These modules typically parse the contents of ``json_arguments`` using a JSON library and th…
5903 msgid "Non-native want JSON modules"
5907 msgid "If a module has the string ``WANT_JSON`` in it anywhere, Ansible treats it as a non-native m…
5911 msgid "These types of modules are self-contained entities. As of Ansible 2.1, Ansible only modifies…
5915 msgid "Examples of Non-native modules written in ruby are in the `Ansible for Rubyists <https://git…
5919 msgid "Binary modules"
5923 msgid "From Ansible 2.2 onwards, modules may also be small binary programs. Ansible doesn't perform…
5927 msgid "Binary modules take their arguments and return data to Ansible in the same way as :ref:`want…
5931 msgid "One example of a `binary module <https://github.com/ansible/ansible/blob/devel/test/integrat…
5935 msgid "Old-style modules"
5939 msgid "Old-style modules are similar to :ref:`want JSON modules <flow_want_json_modules>`, except t…
5943 msgid "How modules are executed"
5947 msgid "When a user uses :program:`ansible` or :program:`ansible-playbook`, they specify a task to e…
5951 msgid "Executor/task_executor"
5955 msgid "The TaskExecutor receives the module name and parameters that were parsed from the :term:`pl…
5959 msgid "The ``normal`` action plugin"
5963 msgid "The ``normal`` action plugin executes the module on the remote host. It is the primary coord…
5967 msgid "It loads the appropriate connection plugin for the task, which then transfers or executes as…
5971 msgid "It adds any internal Ansible properties to the module's parameters (for instance, the ones t…
5975 msgid "It works with other plugins (connection, shell, become, other action plugins) to create any …
5979 msgid "It pushes the module and module parameters to the remote host, although the :ref:`module_com…
5983 msgid "It handles any special cases regarding modules (for instance, async execution, or complicati…
5987 msgid "Much of this functionality comes from the `BaseAction` class, which lives in :file:`plugins/…
5991 msgid "When :term:`tasks <tasks>` are run with the ``async:`` parameter, Ansible uses the ``async``…
5995 msgid "Executor/module_common.py"
5999 msgid "Code in :file:`executor/module_common.py` assembles the module to be shipped to the managed …
6003 msgid ":ref:`PowerShell <flow_powershell_modules>` and :ref:`JSON-args modules <flow_jsonargs_modul…
6007 msgid "New-style :ref:`Python modules <flow_python_modules>` are assembled by :ref:`Ansiballz`."
6011 msgid ":ref:`Non-native-want-JSON <flow_want_json_modules>`, :ref:`Binary modules <flow_binary_modu…
6015 msgid "After the assembling step, one final modification is made to all modules that have a shebang…
6019 msgid "Assembler frameworks"
6023 msgid "Ansible supports two assembler frameworks: Ansiballz and the older Module Replacer."
6027 msgid "Module Replacer framework"
6031 msgid "The Module Replacer framework is the original framework implementing new-style modules, and …
6035 msgid "Replacements that only happen in the module file. These are public replacement strings that …
6039 msgid ":code:`from ansible.module_utils.MOD_LIB_NAME import *` is replaced with the contents of the…
6043 msgid ":code:`#<<INCLUDE_ANSIBLE_MODULE_COMMON>>` is equivalent to :code:`from ansible.module_utils…
6047 msgid ":code:`# POWERSHELL_COMMON` substitutes the contents of :file:`ansible/module_utils/powershe…
6051 msgid "Replacements that are used by ``ansible.module_utils`` code. These are internal replacement …
6055 msgid ":code:`\"<<ANSIBLE_VERSION>>\"` is substituted with the Ansible version.  In :ref:`new-style…
6059 msgid ":code:`\"<<INCLUDE_ANSIBLE_MODULE_COMPLEX_ARGS>>\"` is substituted with a string which is th…
6063 msgid ":code:`<<SELINUX_SPECIAL_FILESYSTEMS>>` substitutes a string which is a comma separated list…
6067 msgid ":code:`<<INCLUDE_ANSIBLE_MODULE_JSON_ARGS>>` substitutes the module parameters as a JSON str…
6071 msgid "The string :code:`syslog.LOG_USER` is replaced wherever it occurs with the ``syslog_facility…
6075 msgid "Ansiballz framework"
6079 msgid "The Ansiballz framework was adopted in Ansible 2.1 and is used for all new-style Python modu…
6083 msgid "Ansible wraps the zipfile in the Python script for two reasons:"
6087 msgid "for compatibility with Python 2.6 which has a less functional version of Python's ``-m`` com…
6091 msgid "so that pipelining will function properly. Pipelining needs to pipe the Python module into t…
6095 msgid "Prior to Ansible 2.7, the module was executed via a second Python interpreter instead of bei…
6099 msgid "In Ansiballz, any imports of Python modules from the :py:mod:`ansible.module_utils` package …
6103 msgid "At present, the Ansiballz Framework cannot determine whether an import should be included if…
6107 msgid "Passing args"
6111 msgid "Arguments are passed differently by the two frameworks:"
6115 msgid "In :ref:`module_replacer`, module arguments are turned into a JSON-ified string and substitu…
6119 msgid "In :ref:`Ansiballz`, the JSON-ified string is part of the script which wraps the zipfile. Ju…
6123 msgid "If you are writing modules, remember that the way we pass arguments is an internal implement…
6127 msgid "Very dynamic custom modules which need to parse arguments before they instantiate an ``Ansib…
6131 msgid "Prior to Ansible 2.7, the Ansible module was invoked in a second Python interpreter and the …
6135 msgid "Internal arguments"
6139 msgid "Both :ref:`module_replacer` and :ref:`Ansiballz` send additional arguments to the module bey…
6143 msgid "The internal arguments listed here are global. If you need to add a local internal argument …
6147 msgid "_ansible_no_log"
6151 msgid "Boolean. Set to True whenever a parameter in a task or play specifies ``no_log``. Any module…
6155 msgid "``no_log`` specified in a module's argument_spec is handled by a different mechanism."
6159 msgid "_ansible_debug"
6163 msgid "Boolean. Turns more verbose logging on or off and turns on logging of external commands that…
6167 msgid "_ansible_diff"
6171 msgid "Boolean. If a module supports it, tells the module to show a unified diff of changes to be m…
6175 msgid "_ansible_verbosity"
6179 msgid "Unused. This value could be used for finer grained control over logging."
6183 msgid "_ansible_selinux_special_fs"
6187 msgid "List. Names of filesystems which should have a special SELinux context. They are used by the…
6191 msgid "Most modules can use the built-in ``AnsibleModule`` methods to manipulate files. To access i…
6195 msgid "This replaces :attr:`ansible.module_utils.basic.SELINUX_SPECIAL_FS` from :ref:`module_replac…
6199 msgid "_ansible_syslog_facility"
6203 msgid "This parameter controls which syslog facility Ansible module logs to. To set, change the ``s…
6207 msgid "_ansible_version"
6211 msgid "This parameter passes the version of Ansible that runs the module. To access it, a module sh…
6215 msgid "Module return values & Unsafe strings"
6219 msgid "At the end of a module's execution, it formats the data that it wants to return as a JSON st…
6223 msgid "If Ansible templated every string return value, it would be vulnerable to an attack from use…
6227 msgid "Strings returned by invoking a module through ``ActionPlugin._execute_module()`` are automat…
6231 msgid "In case a poorly-coded action plugin fails to mark its results as \"Unsafe,\" Ansible audits…
6235 msgid "Special considerations"
6239 msgid "Pipelining"
6243 msgid "Ansible can transfer a module to a remote machine in one of two ways:"
6247 msgid "it can write out the module to a temporary file on the remote host and then use a second con…
6251 msgid "or it can use what's known as pipelining to execute the module by piping it into the remote …
6255 msgid "Pipelining only works with modules written in Python at this time because Ansible only knows…
6259 msgid "Why pass args over stdin?"
6263 msgid "Passing arguments via stdin was chosen for the following reasons:"
6267 msgid "When combined with :ref:`ANSIBLE_PIPELINING`, this keeps the module's arguments from tempora…
6271 msgid "Command line arguments would be insecure as most systems allow unprivileged users to read th…
6275 msgid "Environment variables are usually more secure than the commandline but some systems limit th…
6279 msgid "AnsibleModule"
6283 msgid "Argument spec"
6287 msgid "The ``argument_spec`` provided to ``AnsibleModule`` defines the supported arguments for a mo…
6291 msgid "Example ``argument_spec``:"
6295 msgid "This section will discuss the behavioral attributes for arguments:"
6299 msgid "``type`` allows you to define the type of the value accepted for the argument. The default v…
6303 msgid "str"
6307 msgid "list"
6311 msgid "dict"
6315 msgid "bool"
6319 msgid "int"
6323 msgid "float"
6327 msgid "path"
6331 msgid "raw"
6335 msgid "jsonarg"
6340 msgid "json"
6344 msgid "bytes"
6348 msgid "bits"
6352 msgid "The ``raw`` type, performs no type validation or type casting, and maintains the type of the…
6356 msgid "``elements`` works in combination with ``type`` when ``type='list'``. ``elements`` can then …
6360 msgid "The ``default`` option allows sets a default value for the argument for the scenario when th…
6364 msgid "fallback"
6368 msgid "``fallback`` accepts a ``tuple`` where the first argument is a callable (function) that will…
6372 msgid "The most common callable used is ``env_fallback`` which will allow an argument to optionally…
6376 msgid "``choices`` accepts a list of choices that the argument will accept. The types of ``choices`…
6380 msgid "``required`` accepts a boolean, either ``True`` or ``False`` that indicates that the argumen…
6384 msgid "no_log"
6388 msgid "``no_log`` accepts a boolean, either ``True`` or ``False``, that indicates explicitly whethe…
6392 msgid "In the absence of ``no_log``, if the parameter name appears to indicate that the argument va…
6396 msgid "``aliases`` accepts a list of alternative argument names for the argument, such as the case …
6400 msgid "``options`` implements the ability to create a sub-argument_spec, where the sub options of t…
6404 msgid "apply_defaults"
6408 msgid "``apply_defaults`` works alongside ``options`` and allows the ``default`` of the sub-options…
6412 msgid "In the example of the ``argument_spec`` at the top of this section, it would allow ``module.…
6416 msgid "removed_in_version"
6420 msgid "``removed_in_version`` indicates which version of ansible-core or a collection a deprecated …
6424 msgid "removed_at_date"
6428 msgid "``removed_at_date`` indicates that a deprecated argument will be removed in a minor ansible-…
6432 msgid "removed_from_collection"
6436 msgid "Specifies which collection (or ansible-core) deprecates this deprecated argument. Specify ``…
6440 msgid "deprecated_aliases"
6444 msgid "Deprecates aliases of this argument. Must contain a list or tuple of dictionaries having som…
6448 msgid "name"
6452 msgid "The name of the alias to deprecate. (Required.)"
6457 msgid "version"
6461 msgid "The version of ansible-core or the collection this alias will be removed in. Either ``versio…
6465 msgid "date"
6469 msgid "The a date after which a minor release of ansible-core or a major collection release will no…
6473 msgid "collection_name"
6477 msgid "Specifies which collection (or ansible-core) deprecates this deprecated alias. Specify ``ans…
6481 msgid "Examples:"
6485 msgid "mutually_exclusive"
6489 msgid "If ``options`` is specified, ``mutually_exclusive`` refers to the sub-options described in `…
6493 msgid "required_together"
6497 msgid "If ``options`` is specified, ``required_together`` refers to the sub-options described in ``…
6501 msgid "required_one_of"
6505 msgid "If ``options`` is specified, ``required_one_of`` refers to the sub-options described in ``op…
6509 msgid "required_if"
6513 msgid "If ``options`` is specified, ``required_if`` refers to the sub-options described in ``option…
6517 msgid "required_by"
6521 msgid "If ``options`` is specified, ``required_by`` refers to the sub-options described in ``option…
6525 msgid "Dependencies between module options"
6529 msgid "The following are optional arguments for ``AnsibleModule()``:"
6533 msgid "Must be a sequence (list or tuple) of sequences of strings. Every sequence of strings is a l…
6537 msgid "In this example, the options ``path`` and ``content`` must not specified at the same time. A…
6541 msgid "To ensure that precisely one of two (or more) options is specified, combine ``mutually_exclu…
6545 msgid "Must be a sequence (list or tuple) of sequences of strings. Every sequence of strings is a l…
6549 msgid "In this example, if one of the options ``file_path`` or ``file_hash`` is specified, Ansible …
6553 msgid "Must be a sequence (list or tuple) of sequences of strings. Every sequence of strings is a l…
6557 msgid "In this example, at least one of ``path`` and ``content`` must be specified. If none are spe…
6561 msgid "Must be a sequence of sequences. Every inner sequence describes one conditional dependency. …
6565 msgid "If you want that all options in a list of option names are specified if the condition is met…
6569 msgid "If you want that at least one option of a list of option names is specified if the condition…
6573 msgid "In this example, if the user specifies ``state=present``, at least one of the options ``path…
6577 msgid "On the other hand, if ``force`` (a boolean parameter) is set to ``true``, ``yes`` etc., both…
6581 msgid "Must be a dictionary mapping option names to sequences of option names. If the option name i…
6585 msgid "In the example, if ``force`` is specified, ``force_reason`` must also be specified. Also, if…
6589 msgid "Declaring check mode support"
6593 msgid "To declare that a module supports check mode, supply ``supports_check_mode=True`` to the ``A…
6597 msgid "The module can determine whether it is called in check mode by checking the boolean value ``…
6601 msgid "If ``supports_check_mode=False`` is specified, which is the default value, the module will e…
6605 msgid "Adding file options"
6609 msgid "To declare that a module should add support for all common file options, supply ``add_file_c…
6613 msgid "You can find `a list of all file options here <https://github.com/ansible/ansible/blob/devel…
6617 msgid "The helper functions ``module.load_file_common_arguments()`` and ``module.set_fs_attributes_…
6621 msgid "Ansible and Python 3"
6625 msgid "The ``ansible-core`` code runs on both Python 2 and Python 3 because we want Ansible to be a…
6629 msgid "To ensure that your code runs on Python 3 as well as on Python 2, learn the tips and tricks …
6633 msgid "controller-side code - code that runs on the machine where you invoke :command:`/usr/bin/ans…
6637 msgid "modules - the code which Ansible transmits to and invokes on the managed machine."
6641 msgid "shared ``module_utils`` code - the common code that's used by modules to perform tasks and s…
6645 msgid "However, the three types of code do not use the same string strategy. If you're developing a…
6649 msgid "Minimum version of Python 3.x and Python 2.x"
6653 msgid "On the controller we support Python 3.5 or greater and Python 2.7 or greater.  Module-side, …
6657 msgid "Python 3.5 was chosen as a minimum because it is the earliest Python 3 version adopted as th…
6661 msgid "For Python 2, the default is for modules to run on at least Python 2.6.  This allows users w…
6665 msgid "Python 2.4 Module-side Support:"
6669 msgid "Support for Python 2.4 and Python 2.5 was dropped in Ansible-2.4.  RHEL-5 (and its rebuilds …
6673 msgid "Developing Ansible code that supports Python 2 and Python 3"
6677 msgid "The best place to start learning about writing code that supports both Python 2 and Python 3…
6681 msgid "Understanding strings in Python 2 and Python 3"
6685 msgid "Python 2 and Python 3 handle strings differently, so when you write code that supports Pytho…
6689 msgid "In Python 2, the two types for these (:class:`str <python:str>` for bytes and :func:`unicode…
6693 msgid "Python 3 changes this behavior by making the separation between bytes (:class:`bytes <python…
6697 msgid "In Python 3 it's immediately apparent to the programmer when code is mixing the byte and tex…
6701 msgid "Ansible uses different strategies for working with strings in controller-side code, in :ref:…
6705 msgid "Controller string strategy: the Unicode Sandwich"
6709 msgid "In controller-side code we use a strategy known as the Unicode Sandwich (named after Python …
6713 msgid "Unicode Sandwich common borders: places to convert bytes to text in controller code"
6717 msgid "This is a partial list of places where we have to convert to and from bytes when using the U…
6721 msgid "Reading and writing to files"
6725 msgid "In Python 2, reading from files yields bytes.  In Python 3, it can yield text. To make code …
6729 msgid "Much of Ansible assumes that all encoded text is UTF-8.  At some point, if there is demand f…
6733 msgid "Writing to files is the opposite process:"
6737 msgid "Note that we don't have to catch :exc:`UnicodeError` here because we're transforming to UTF-…
6741 msgid "Filesystem interaction"
6745 msgid "Dealing with filenames often involves dropping back to bytes because on UNIX-like systems fi…
6749 msgid "When you are only manipulating a filename as a string without talking to the filesystem (or …
6753 msgid "On the other hand, if the code needs to manipulate the filename and also talk to the filesys…
6757 msgid "Make sure all variables passed to a function are the same type. If you're working with somet…
6761 msgid "Interacting with other programs"
6765 msgid "Interacting with other programs goes through the operating system and C libraries and operat…
6769 msgid "One of the main places in Ansible's controller code that we interact with other programs is …
6773 msgid "Module string strategy: Native String"
6777 msgid "In modules we use a strategy known as Native Strings. This makes things easier on the commun…
6781 msgid "Native strings refer to the type that Python uses when you specify a bare string literal:"
6785 msgid "In Python 2, these are byte strings. In Python 3 these are text strings. Modules should be c…
6789 msgid "Module_utils string strategy: hybrid"
6793 msgid "In ``module_utils`` code we use a hybrid string strategy. Although Ansible's ``module_utils`…
6797 msgid "In ``module_utils`` code:"
6801 msgid "Functions **must** accept string parameters as either text strings or byte strings."
6805 msgid "Functions may return either the same type of string as they were given or the native string …
6809 msgid "Functions that return strings **must** document whether they return strings of the same type…
6813 msgid "Module-utils functions are therefore often very defensive in nature. They convert their stri…
6817 msgid "Tips, tricks, and idioms for Python 2/Python 3 compatibility"
6821 msgid "Use forward-compatibility boilerplate"
6825 msgid "Use the following boilerplate code at the top of all python files to make certain constructs…
6829 msgid "``__metaclass__ = type`` makes all classes defined in the file into new-style classes withou…
6833 msgid "The ``__future__`` imports do the following:"
6838 msgid "absolute_import"
6842 msgid "Makes imports look in :data:`sys.path <python3:sys.path>` for the modules being imported, sk…
6847 msgid "division"
6851 msgid "Makes division of integers always return a float.  If you need to find the quotient use ``x …
6856 msgid "print_function"
6860 msgid "Changes :func:`print <python3:print>` from a keyword into a function."
6864 msgid "`PEP 0328: Absolute Imports <https://www.python.org/dev/peps/pep-0328/#guido-s-decision>`_"
6868 msgid "`PEP 0238: Division <https://www.python.org/dev/peps/pep-0238>`_"
6872 msgid "`PEP 3105: Print function <https://www.python.org/dev/peps/pep-3105>`_"
6876 msgid "Prefix byte strings with ``b_``"
6880 msgid "Since mixing text and bytes types leads to tracebacks we want to be clear about what variabl…
6884 msgid "We do not prefix the text strings instead because we only operate on byte strings at the bor…
6888 msgid "Import Ansible's bundled Python ``six`` library"
6892 msgid "The third-party Python `six <https://pypi.org/project/six/>`_ library exists to help project…
6896 msgid "Ansible can also use a system copy of six"
6900 msgid "Ansible will use a system copy of six if the system copy is a later version than the one Ans…
6904 msgid "Handle exceptions with ``as``"
6908 msgid "In order for code to function on Python 2.6+ and Python 3, use the new exception-catching sy…
6912 msgid "Do **not** use the following syntax as it will fail on every version of Python 3:"
6916 msgid "Update octal numbers"
6920 msgid "In Python 2.x, octal literals could be specified as ``0755``.  In Python 3, octals must be s…
6924 msgid "String formatting for controller code"
6928 msgid "Use ``str.format()`` for Python 2.6 compatibility"
6932 msgid "Starting in Python 2.6, strings gained a method called ``format()`` to put strings together.…
6936 msgid "Both of the format strings above map positional arguments of the ``format()`` method into th…
6940 msgid "Python documentation on `format strings <https://docs.python.org/2/library/string.html#forma…
6944 msgid "Use percent format with byte strings"
6948 msgid "In Python 3.x, byte strings do not have a ``format()`` method.  However, it does have suppor…
6952 msgid "Percent formatting added in Python 3.5"
6956 msgid "Percent formatting of byte strings was added back into Python 3 in 3.5. This isn't a problem…
6960 msgid "Python documentation on `percent formatting <https://docs.python.org/2/library/stdtypes.html…
6964 msgid "Testing modules on Python 3"
6968 msgid "Ansible modules are slightly harder to code to support Python 3 than normal code from other …
6972 msgid "Rebasing a pull request"
6976 msgid "You may find that your pull request (PR) is out-of-date and needs to be rebased. This can ha…
6980 msgid "Files modified in your PR are in conflict with changes which have already been merged."
6984 msgid "Your PR is old enough that significant changes to automated test infrastructure have occurre…
6988 msgid "Rebasing the branch used to create your PR will resolve both of these issues."
6992 msgid "Configuring your remotes"
6996 msgid "Before you can rebase your PR, you need to make sure you have the proper remotes configured.…
7000 msgid "However, you also need to add a remote which points to the upstream repository::"
7004 msgid "Which should leave you with the following remotes::"
7008 msgid "Checking the status of your branch should show your fork is up-to-date with the ``origin`` r…
7012 msgid "Rebasing your branch"
7016 msgid "Once you have an ``upstream`` remote configured, you can rebase the branch for your PR::"
7020 msgid "This will replay the changes in your branch on top of the changes made in the upstream ``dev…
7024 msgid "After you rebase, the status of your branch changes::"
7028 msgid "Don't worry, this is normal after a rebase. You should ignore the ``git status`` instruction…
7032 msgid "Updating your pull request"
7036 msgid "Now that you've rebased your branch, you need to push your changes to GitHub to update your …
7040 msgid "Since rebasing re-writes git history, you will need to use a force push::"
7044 msgid "Your PR on GitHub has now been updated. This will automatically trigger testing of your chan…
7048 msgid "Getting help rebasing"
7052 msgid "For help with rebasing your PR, or other development related questions, join us on our #ansi…
7056 msgid ":ref:`community_development_process`"
7060 msgid "Information on roadmaps, opening PRs, Ansibullbot, and more"
7064 msgid "Developer Guide"
7068 msgid "**Making Open Source More Inclusive**"
7072 msgid "Red Hat is committed to replacing problematic language in our code, documentation, and web p…
7076 msgid "Welcome to the Ansible Developer Guide!"
7080 msgid "**Who should use this guide?**"
7084 msgid "If you want to extend Ansible by using a custom module or plugin locally, creating a module …
7088 msgid "Find the task that best describes what you want to do:"
7092 msgid "I'm looking for a way to address a use case:"
7096 msgid "I want to :ref:`add a custom plugin or module locally <developing_locally>`."
7100 msgid "I want to figure out if :ref:`developing a module is the right approach <module_dev_should_y…
7104 msgid "I want to :ref:`develop a collection <developing_collections>`."
7108 msgid "I want to :ref:`contribute to an Ansible-maintained collection <contributing_maintained_coll…
7112 msgid "I want to :ref:`contribute to a community-maintained collection <hacking_collections>`."
7116 msgid "I want to :ref:`migrate a role to a collection <migrating_roles>`."
7120 msgid "I've read the info above, and I'm sure I want to develop a module:"
7124 msgid "What do I need to know before I start coding?"
7128 msgid "I want to :ref:`set up my Python development environment <environment_setup>`."
7132 msgid "I want to :ref:`get started writing a module <developing_modules_general>`."
7136 msgid "I want to write a specific kind of module:"
7140 msgid "a :ref:`network module <developing_modules_network>`"
7144 msgid "a :ref:`Windows module <developing_modules_general_windows>`."
7148 msgid "an :ref:`Amazon module <AWS_module_development>`."
7152 msgid "an :ref:`OpenStack module <OpenStack_module_development>`."
7156 msgid "an :ref:`oVirt/RHV module <oVirt_module_development>`."
7160 msgid "a :ref:`VMware module <VMware_module_development>`."
7164 msgid "I want to :ref:`write a series of related modules <developing_modules_in_groups>` that integ…
7168 msgid "I want to refine my code:"
7172 msgid "I want to :ref:`debug my module code <debugging_modules>`."
7176 msgid "I want to :ref:`add tests <developing_testing>`."
7180 msgid "I want to :ref:`document my module <module_documenting>`."
7184 msgid "I want to :ref:`document my set of modules for a network platform <documenting_modules_netwo…
7188 msgid "I want to follow :ref:`conventions and tips for clean, usable module code <developing_module…
7192 msgid "I want to :ref:`make sure my code runs on Python 2 and Python 3 <developing_python_3>`."
7196 msgid "I want to work on other development projects:"
7200 msgid "I want to :ref:`write a plugin <developing_plugins>`."
7204 msgid "I want to :ref:`connect Ansible to a new source of inventory <developing_inventory>`."
7208 msgid "I want to :ref:`deprecate an outdated module <deprecating_modules>`."
7212 msgid "I want to contribute back to the Ansible project:"
7216 msgid "I want to :ref:`understand how to contribute to Ansible <ansible_community_guide>`."
7220 msgid "I want to :ref:`contribute my module or plugin <developing_modules_checklist>`."
7224 msgid "I want to :ref:`understand the license agreement <contributor_license_agreement>` for contri…
7228 msgid "If you prefer to read the entire guide, here's a list of the pages in order."
7232 msgid "Migrating Roles to Roles in Collections on Galaxy"
7236 msgid "You can migrate any existing standalone role into a collection and host the collection on Ga…
7240 msgid "You must migrate roles to collections if you want to distribute them as certified Ansible co…
7244 msgid "If you want to import your collection to Galaxy, you need a `Galaxy namespace <https://galax…
7248 msgid "See :ref:`developing_collections` for details on collections."
7252 msgid "Comparing standalone roles to collection roles"
7256 msgid ":ref:`Standalone roles <playbooks_reuse_roles>` have the following directory structure:"
7260 msgid "The highlighted directories above will change when you migrate to a collection-based role. T…
7264 msgid "You will need to use the Fully Qualified Collection Name (FQCN) to use the roles and plugins…
7268 msgid "So for example, in the above collection, the FQCN to access  ``role1`` would be:"
7272 msgid "A collection can contain one or more roles in the :file:`roles/` directory and these are alm…
7276 msgid "In standalone roles, some of the plugin directories referenced their plugin types in the plu…
7280 msgid "Migrating a role to a collection"
7284 msgid "To migrate from a standalone role that contains no plugins to a collection role:"
7288 msgid "Create a local :file:`ansible_collections` directory and ``cd`` to this new directory."
7293 msgid "Create a collection. If you want to import this collection to Ansible Galaxy, you need a `Ga…
7298 msgid "This creates the collection directory structure."
7303 msgid "Copy the standalone role directory into the :file:`roles/` subdirectory of the collection. R…
7308 msgid "Update ``galaxy.yml`` to include any role dependencies."
7313 msgid "Update the collection README.md file to add links to any role README.md files."
7317 msgid "Migrating a role that contains plugins to a collection"
7321 msgid "To migrate from a standalone role that has plugins to a collection role:"
7325 msgid "Create a local :file:`ansible_collections directory` and ``cd`` to this new directory."
7329 msgid "Move any modules to the :file:`plugins/modules/` directory."
7333 msgid "Move any other plugins to the appropriate :file:`plugins/PLUGINTYPE/` directory.  See :ref:`…
7337 msgid "Change any references to the role to use the :abbr:`FQCN (Fully Qualified Collection Name)`."
7341 msgid "You can alternately use the ``collections`` keyword to simplify this:"
7345 msgid "Migrating other role plugins to a collection"
7349 msgid "To migrate other role plugins to a collection:"
7353 msgid "Move each nonmodule plugins to the appropriate :file:`plugins/PLUGINTYPE/` directory. The :f…
7357 msgid "Update documentation to use the FQCN. Plugins that use ``doc_fragments`` need to use FQCN (f…
7361 msgid "Update relative imports work in collections to start with a period.  For example, :file:`./f…
7365 msgid "If you have a custom ``module_utils`` or import from ``__init__.py``, you must also:"
7369 msgid "Change the Python namespace for custom ``module_utils`` to use the :abbr:`FQCN (Fully Qualif…
7373 msgid "Change how you import from ``__init__.py``. See :ref:`update_init_role`."
7377 msgid "Updating ``module_utils``"
7381 msgid "If any of your custom modules use a custom module utility, once you migrate to a collection …
7385 msgid "When coding with ``module_utils`` in a collection, the Python import statement needs to take…
7389 msgid "You need to follow the same rules in changing paths and using namespaced names for subclasse…
7393 msgid "The following example code snippets show a Python and a PowerShell module using both default…
7397 msgid "In the Python example the ``module_utils`` is ``helper`` and the :abbr:`FQCN (Fully Qualifie…
7401 msgid "In the PowerShell example the ``module_utils`` is ``hyperv`` and the :abbr:`FQCN (Fully Qual…
7405 msgid "Importing from __init__.py"
7409 msgid "Because of the way that the CPython interpreter does imports, combined with the way the Ansi…
7413 msgid "Example: Migrating a standalone role with plugins to a collection"
7417 msgid "In this example we have a standalone role called ``my-standalone-role.webapp`` to emulate a …
7421 msgid "Create a new collection, for example, ``acme.webserver``:"
7425 msgid "Create the ``webapp`` role inside the collection and copy all contents from the standalone r…
7429 msgid "Move the ``manage_webserver`` module to its new home in ``acme/webserver/plugins/modules/``:"
7433 msgid "This example changed the original source file ``manage_webserver.py`` to the destination fil…
7437 msgid "Change ``manage_webserver`` to ``acme.webserver.manage`` in :file:`tasks/` files in the role…
7441 msgid "This name change is only required if you changed the original module name, but illustrates c…
7445 msgid "Example: Supporting standalone roles and migrated collection roles in a downstream RPM"
7449 msgid "A standalone role can co-exist with its collection role counterpart (for example, as part of…
7453 msgid "This section walks through an example creating this coexistence in a downstream RPM and requ…
7457 msgid "To deliver a role as both a standalone role and a collection role:"
7461 msgid "Place the collection in  :file:`/usr/local/share/py38-ansible/collections/ansible_collection…
7465 msgid "Copy the contents of the role inside the collection into a directory named after the standal…
7469 msgid "All previously bundled modules and plugins used in the standalone role are now referenced by…
7473 msgid "The following is an example RPM spec file that accomplishes this using this example content:"
7477 msgid "Using ``ansible.legacy`` to access local custom modules from collections-based roles"
7481 msgid "Some roles use :ref:`local custom modules <developing_locally>` that are not part of the rol…
7485 msgid "To enable a role hosted in a collection to find legacy custom modules and other plugins host…
7489 msgid "Edit the role's ``meta/main.yml`` and add the ``ansible.legacy`` collection to your collecti…
7493 msgid "Alternatively, you can update the tasks directly by changing ``local_module_name`` to ``ansi…
7497 msgid "The lifecycle of an Ansible module or plugin"
7501 msgid "Modules and plugins in the main Ansible repository have a defined life cycle, from the first…
7505 msgid "When a module or plugin is first accepted into Ansible, we consider it in tech preview and w…
7509 msgid "If a module or plugin matures, the 'preview' mark in the documentation is removed. Backward …
7513 msgid "If a module's or plugin's target API changes radically, or if someone creates a better imple…
7517 msgid "When a module or plugin has been deprecated for four release cycles, it is removed and repla…
7521 msgid "For modules and plugins in collections, the lifecycle is similar. Since ansible-base 2.10, i…
7525 msgid "Deprecating modules and plugins in the Ansible main repository"
7529 msgid "To deprecate a module in ansible-core, you must:"
7533 msgid "Rename the file so it starts with an ``_``, for example, rename ``old_cloud.py`` to ``_old_c…
7537 msgid "Mention the deprecation in the relevant changelog (by creating a changelog fragment with a s…
7541 msgid "Reference the deprecation in the relevant ``porting_guide_core_x.y.rst``."
7545 msgid "Add ``deprecated:`` to the documentation with the following sub-values:"
7549 msgid "removed_in"
7554 msgid "A ``string``, such as ``\"2.10\"``; the version of Ansible where the module will be replaced…
7558 msgid "remove_by_date"
7563 msgid "(Added in ansible-base 2.10). An ISO 8601 formatted date when the module will be removed. Us…
7567 msgid "why"
7572 msgid "Optional string that used to detail why this has been removed."
7576 msgid "alternative"
7581 msgid "Inform users they should do instead, for example, ``Use M(whatmoduletouseinstead) instead.``…
7585 msgid "For an example of documenting deprecation, see this `PR that deprecates multiple modules <ht…
7589 msgid "Deprecating modules and plugins in a collection"
7593 msgid "To deprecate a module in a collection, you must:"
7597 msgid "Add a ``deprecation`` entry to ``plugin_routing`` in ``meta/runtime.yml``. For example, to d…
7601 msgid "For other plugin types, you have to replace ``modules:`` with ``<plugin_type>:``, for exampl…
7605 msgid "Instead of ``removal_version``, you can also use ``removal_date`` with an ISO 8601 formatted…
7609 msgid "Mention the deprecation in the relevant changelog. If the collection uses ``antsibull-change…
7613 msgid "Add ``deprecated:`` to the documentation of the module or plugin with the following sub-valu…
7617 msgid "Changing a module or plugin name in the Ansible main repository"
7621 msgid "You can also rename a module and keep a deprecated alias to the old name by using a symlink …
7625 msgid "Renaming a module or plugin in a collection, or redirecting a module or plugin to another co…
7629 msgid "To rename a module or plugin in a collection, or to redirect a module or plugin to another c…
7633 msgid "If you want to deprecate the old name, add a ``deprecation:`` entry (see above):"
7637 msgid "You need to use the Fully Qualified Collection Name (FQCN) of the new module/plugin name, ev…
7641 msgid "If you need to support Ansible 2.9, please note that Ansible 2.9 does not know about ``meta/…
7645 msgid "Tombstoning a module or plugin in a collection"
7649 msgid "To remove a deprecated module or plugin from a collection, you need to tombstone it:"
7653 msgid "Remove the module or plugin file with related files like tests, documentation references, an…
7657 msgid "Add a tombstone entry in ``meta/runtime.yml``. For example, to tombstone the module ``old_cl…
7661 msgid "Instead of ``removal_version``, you can also use ``removal_date`` with an ISO 8601 formatted…
7665 msgid "Ansible architecture"
7669 msgid "Ansible is a radically simple IT automation engine that automates cloud provisioning, config…
7673 msgid "Being designed for multi-tier deployments since day one, Ansible models your IT infrastructu…
7677 msgid "It uses no agents and no additional custom security infrastructure, so it's easy to deploy -…
7681 msgid "In this section, we'll give you a really quick overview of how Ansible works so you can see …
7685 msgid "Modules"
7689 msgid "Ansible works by connecting to your nodes and pushing out scripts called \"Ansible modules\"…
7693 msgid "You can :ref:`write your own modules <developing_modules_general>`, though you should first …
7697 msgid "Module utilities"
7701 msgid "When multiple modules use the same code, Ansible stores those functions as module utilities …
7705 msgid "Plugins"
7709 msgid ":ref:`Plugins <plugins_lookup>` augment Ansible's core functionality. While modules execute …
7713 msgid "Inventory"
7717 msgid "By default, Ansible represents the machines it manages in a file (INI, YAML, and so on) that…
7721 msgid "To add new machines, there is no additional SSL signing server involved, so there's never an…
7725 msgid "If there's another source of truth in your infrastructure, Ansible can also connect to that.…
7729 msgid "Here's what a plain text inventory file looks like::"
7733 msgid "Once inventory hosts are listed, variables can be assigned to them in simple text files (in …
7737 msgid "Or, as already mentioned, use a dynamic inventory to pull your inventory from data sources l…
7741 msgid "Playbooks"
7745 msgid "Playbooks can finely orchestrate multiple slices of your infrastructure topology, with very …
7749 msgid "Ansible's approach to orchestration is one of finely-tuned simplicity, as we believe your au…
7753 msgid "Here's what a simple playbook looks like::"
7757 msgid "The Ansible search path"
7761 msgid "Modules, module utilities, plugins, playbooks, and roles can live in multiple locations. If …
7765 msgid "Ansible's search path grows incrementally over a run. As Ansible finds each playbook and rol…
7769 msgid "Directories adjacent to a playbook specified on the command line. If you run Ansible with ``…
7773 msgid "Directories adjacent to a playbook that is statically imported by a playbook specified on th…
7777 msgid "Subdirectories of a role directory referenced by a playbook. If ``play.yml`` runs ``myrole``…
7781 msgid "Directories specified as default paths in ``ansible.cfg`` or by the related environment vari…
7785 msgid "Sample environment variables:"
7789 msgid "The standard directories that ship as part of the Ansible distribution."
7793 msgid "Modules, module utilities, and plugins in user-specified directories will override the stand…
7797 msgid "If you have more than one module, module utility, or plugin with the same name in different …
7801 msgid "Guidelines for Ansible Amazon AWS module development"
7805 msgid "The Ansible AWS collection (on `Galaxy <https://galaxy.ansible.com/community/aws>`_, source …
7813 msgid "Requirements"
7817 msgid "Python Compatibility"
7821 msgid "AWS content in Ansible 2.9 and 1.x collection releases supported Python 2.7 and newer."
7825 msgid "Starting with the 2.0 releases of both collections, Python 2.7 support will be ended in acco…
7829 msgid "SDK Version Support"
7833 msgid "Starting with the 2.0 releases of both collections, it is generally the policy to support th…
7837 msgid "Features and functionality that require newer versions of the SDK can be contributed provide…
7841 msgid "And handled using the ``botocore_at_least`` helper method:"
7845 msgid "Maintaining existing modules"
7849 msgid "Fixing bugs"
7853 msgid "Bug fixes to code that relies on boto will still be accepted. When possible, the code should…
7857 msgid "Adding new features"
7861 msgid "Try to keep backward compatibility with relatively recent versions of boto3. That means that…
7865 msgid "Use feature testing (for example, ``hasattr('boto3.module', 'shiny_new_method')``) to check …
7869 msgid "Migrating to boto3"
7873 msgid "Prior to Ansible 2.0, modules were written in either boto3 or boto. We are still porting som…
7877 msgid "Porting code to AnsibleAWSModule"
7881 msgid "Some old AWS modules use the generic ``AnsibleModule`` as a base rather than the more effici…
7885 msgid "to:"
7889 msgid "Few other changes are required. AnsibleAWSModule does not inherit methods from AnsibleModule…
7893 msgid "When porting, keep in mind that AnsibleAWSModule also will add the default ec2 argument spec…
7897 msgid "These can be replaced with:"
7901 msgid "Creating new AWS modules"
7905 msgid "Use boto3 and AnsibleAWSModule"
7909 msgid "All new AWS modules must use boto3 and ``AnsibleAWSModule``."
7913 msgid "``AnsibleAWSModule`` greatly simplifies exception handling and library management, reducing …
7917 msgid "Naming your module"
7921 msgid "Base the name of the module on the part of AWS that you actually use. (A good rule of thumb …
7925 msgid "Unless the name of your service is quite unique, please consider using ``aws_`` as a prefix.…
7929 msgid "Importing botocore and boto3"
7933 msgid "The ``ansible_collections.amazon.aws.plugins.module_utils.ec2`` module and ``ansible_collect…
7937 msgid "or:"
7941 msgid "Supporting Module Defaults"
7945 msgid "The existing AWS modules support using :ref:`module_defaults <module_defaults>` for common a…
7949 msgid "Connecting to AWS"
7953 msgid "AnsibleAWSModule provides the ``resource`` and ``client`` helper methods for obtaining boto3…
7957 msgid "If using the basic AnsibleModule then you should use ``get_aws_connection_info`` and then ``…
7961 msgid "These helpers also for missing profiles or a region not set when it needs to be, so you don'…
7965 msgid "An example of connecting to ec2 is shown below. Note that unlike boto there is no ``NoAuthHa…
7969 msgid "or for the higher level ec2 resource:"
7973 msgid "An example of the older style connection used for modules based on AnsibleModule rather than…
7977 msgid "Common Documentation Fragments for Connection Parameters"
7981 msgid "There are two :ref:`common documentation fragments <module_docs_fragments>` that should be i…
7985 msgid "``aws`` - contains the common boto connection parameters"
7989 msgid "``ec2`` - contains the common region parameter required for many AWS modules"
7993 msgid "These fragments should be used rather than re-documenting these properties to ensure consist…
7997 msgid "Handling exceptions"
8001 msgid "You should wrap any boto3 or botocore call in a try block. If an exception is thrown, then t…
8005 msgid "Catch the general ``ClientError`` or look for a specific error code with"
8009 msgid "``is_boto3_error_code``."
8013 msgid "Use ``aws_module.fail_json_aws()`` to report the module failure in a standard way"
8017 msgid "Retry using AWSRetry"
8021 msgid "Use ``fail_json()`` to report the failure without using ``ansible_collections.amazon.aws.plu…
8025 msgid "Do something custom in the case where you know how to handle the exception"
8029 msgid "For more information on botocore exception handling see the `botocore error documentation <h…
8033 msgid "Using is_boto3_error_code"
8037 msgid "To use ``ansible_collections.amazon.aws.plugins.module_utils.core.is_boto3_error_code`` to c…
8041 msgid "Using fail_json_aws()"
8045 msgid "In the AnsibleAWSModule there is a special method, ``module.fail_json_aws()`` for nice repor…
8049 msgid "You should use the AnsibleAWSModule for all new modules, unless not possible. If adding sign…
8053 msgid "Note that it should normally be acceptable to catch all normal exceptions here, however if y…
8057 msgid "If you need to perform an action based on the error boto3 returned, use the error code and t…
8061 msgid "using fail_json() and avoiding ansible_collections.amazon.aws.plugins.module_utils.core"
8065 msgid "Boto3 provides lots of useful information when an exception is thrown so pass this to the us…
8069 msgid "Note: we use `str(e)` rather than `e.message` as the latter doesn't work with python3"
8073 msgid "If you need to perform an action based on the error boto3 returned, use the error code."
8077 msgid "API throttling (rate limiting) and pagination"
8081 msgid "For methods that return a lot of results, boto3 often provides `paginators <https://boto3.re…
8085 msgid "Any time that you are calling the AWS API a lot, you may experience API throttling, and ther…
8089 msgid "You can use ``exponential_backoff`` or ``jittered_backoff`` strategies - see the cloud ``mod…
8093 msgid "The combination of these two approaches is then:"
8097 msgid "Prior to Ansible 2.10 if the underlying ``describe_some_resources`` API call threw a ``Resou…
8101 msgid "To make use of AWSRetry easier, it can now be wrapped around a client returned by ``AnsibleA…
8105 msgid "Any calls from that client can be made to use the decorator passed at call-time using the `a…
8109 msgid "The call will be retried the specified number of times, so the calling functions don't need …
8113 msgid "You can also use customization for ``retries``, ``delay`` and ``max_delay`` parameters used …
8117 msgid "To make all Amazon modules uniform, prefix the module param with ``backoff_``, so ``retries`…
8121 msgid "and likewise with ``backoff_delay`` and ``backoff_max_delay``."
8125 msgid "Returning Values"
8129 msgid "When you make a call using boto3, you will probably get back some useful information that yo…
8133 msgid "Boto3 returns all values CamelCased.  Ansible follows Python standards for variable names an…
8137 msgid "You should use this helper function and avoid changing the names of values returned by Boto3…
8141 msgid "Dealing with IAM JSON policy"
8145 msgid "If your module accepts IAM JSON policies then set the type to 'json' in the module spec. For…
8149 msgid "Note that AWS is unlikely to return the policy in the same order that is was submitted. Ther…
8153 msgid "`compare_policies` takes two dictionaries, recursively sorts and makes them hashable for com…
8157 msgid "Dealing with tags"
8161 msgid "AWS has a concept of resource tags. Usually the boto3 API has separate calls for tagging and…
8165 msgid "It is common practice in Ansible AWS modules to have a `purge_tags` parameter that defaults …
8169 msgid "The `purge_tags` parameter means that existing tags will be deleted if they are not specifie…
8173 msgid "There is a helper function `compare_aws_tags` to ease dealing with tags. It can compare two …
8177 msgid "Helper functions"
8181 msgid "Along with the connection functions in Ansible ec2.py module_utils, there are some other use…
8185 msgid "camel_dict_to_snake_dict"
8189 msgid "boto3 returns results in a dict.  The keys of the dict are in CamelCase format. In keeping w…
8193 msgid "``camel_dict_to_snake_dict`` takes an optional parameter called ``ignore_list`` which is a l…
8197 msgid "Another optional parameter is ``reversible``. By default, ``HTTPEndpoint`` is converted to `…
8201 msgid "snake_dict_to_camel_dict"
8205 msgid "`snake_dict_to_camel_dict` converts snake cased keys to camel case. By default, because it w…
8209 msgid "ansible_dict_to_boto3_filter_list"
8213 msgid "Converts a an Ansible list of filters to a boto3 friendly list of dicts.  This is useful for…
8217 msgid "boto_exception"
8221 msgid "Pass an exception returned from boto or boto3, and this function will consistently get the m…
8225 msgid "Deprecated: use `AnsibleAWSModule`'s `fail_json_aws` instead."
8229 msgid "boto3_tag_list_to_ansible_dict"
8233 msgid "Converts a boto3 tag list to an Ansible dict. Boto3 returns tags as a list of dicts containi…
8237 msgid "This function converts the list in to a single dict where the dict key is the tag key and th…
8241 msgid "ansible_dict_to_boto3_tag_list"
8245 msgid "Opposite of above. Converts an Ansible dict to a boto3 tag list of dicts. You can again over…
8249 msgid "get_ec2_security_group_ids_from_names"
8253 msgid "Pass this function a list of security group names or combination of security group names and…
8257 msgid "compare_policies"
8261 msgid "Pass two dicts of policies to check if there are any meaningful differences and returns true…
8265 msgid "This method should be used any time policies are being compared so that a change in order do…
8269 msgid "compare_aws_tags"
8273 msgid "Pass two dicts of tags and an optional purge parameter and this function will return a dict …
8277 msgid "This function is useful when using boto3 'add_tags' and 'remove_tags' functions. Be sure to …
8281 msgid "Integration Tests for AWS Modules"
8285 msgid "All new AWS modules should include integration tests to ensure that any changes in AWS APIs …
8289 msgid "For general information on running the integration tests see the :ref:`Integration Tests pag…
8293 msgid "The integration tests for your module should be added in `test/integration/targets/MODULE_NA…
8297 msgid "You must also have a aliases file in `test/integration/targets/MODULE_NAME/aliases`. This fi…
8301 msgid "Tests for new modules should be added to the same group as existing AWS tests. In general ju…
8305 msgid "AWS Credentials for Integration Tests"
8309 msgid "The testing framework handles running the test with appropriate AWS credentials, these are m…
8313 msgid "`aws_region`"
8317 msgid "`aws_access_key`"
8321 msgid "`aws_secret_key`"
8325 msgid "`security_token`"
8329 msgid "So all invocations of AWS modules in the test should set these parameters. To avoid duplicat…
8333 msgid "AWS Permissions for Integration Tests"
8337 msgid "As explained in the :ref:`Integration Test guide <testing_integration>` there are defined IA…
8341 msgid "If your module interacts with a new service or otherwise requires new permissions, tests wil…
8345 msgid "If your PR has test failures, check carefully to be certain the failure is only due to the m…
8349 msgid "Your pull request cannot be merged until the tests are passing. If your pull request is fail…
8353 msgid "There are two ways to figure out which IAM permissions you need for your PR to pass:"
8357 msgid "Start with the most permissive IAM policy, run the tests to collect information about which …
8361 msgid "Start with the least permissive IAM policy, run the tests to discover a failure, add permiss…
8365 msgid "To start with the most permissive IAM policy:"
8369 msgid "`Create an IAM policy <https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_crea…
8373 msgid "Run your tests locally with this policy. On AnsibleAWSModule-based modules, the ``debug_boto…
8377 msgid "Modify your policy to allow only the actions your tests use. Restrict account, region, and p…
8381 msgid "Run the tests again with a user or role that allows only the new policy."
8385 msgid "If the tests fail, troubleshoot (see tips below), modify the policy, run the tests again, an…
8390 msgid "Open a pull request proposing the minimum required policy to the `CI policies <https://githu…
8394 msgid "To start from the least permissive IAM policy:"
8398 msgid "Run the integration tests locally with no IAM permissions."
8402 msgid "Examine the error when the tests reach a failure."
8406 msgid "If the error message indicates the action used in the request, add the action to your policy…
8410 msgid "If the error message does not indicate the action used in the request:"
8414 msgid "Usually the action is a CamelCase version of the method name - for example, for an ec2 clien…
8418 msgid "Refer to the documentation to identify the action."
8422 msgid "If the error message indicates the resource ARN used in the request, limit the action to tha…
8426 msgid "If the error message does not indicate the resource ARN used:"
8430 msgid "Determine if the action can be restricted to a resource by examining the documentation."
8434 msgid "If the action can be restricted, use the documentation to construct the ARN and add it to th…
8438 msgid "Add the action or resource that caused the failure to `an IAM policy <https://docs.aws.amazo…
8442 msgid "Run the tests again with this policy attached to your user or role."
8446 msgid "If the tests still fail at the same place with the same error you will need to troubleshoot …
8450 msgid "Troubleshooting IAM policies"
8454 msgid "When you make changes to a policy, wait a few minutes for the policy to update before re-run…
8458 msgid "Use the `policy simulator <https://policysim.aws.amazon.com/>`_ to verify that each action (…
8462 msgid "If you're restricting actions to certain resources, replace resources temporarily with `*`. …
8466 msgid "If the initial troubleshooting above doesn't provide any more insight, AWS may be using addi…
8470 msgid "Examine the AWS FullAccess policy for the service for clues."
8474 msgid "Re-read the AWS documentation, especially the list of `Actions, Resources and Condition Keys…
8478 msgid "Look at the `cloudonaut <https://iam.cloudonaut.io>`_ documentation as a troubleshooting cro…
8482 msgid "Use a search engine."
8486 msgid "Ask in the Ansible IRC channel #ansible-aws (on `irc.libera.chat <https://libera.chat>`_)."
8490 msgid "Unsupported Integration tests"
8494 msgid "There are a limited number of reasons why it may not be practical to run integration tests f…
8498 msgid "Some cases where tests should be marked as unsupported: 1) The tests take longer than 10 or …
8502 msgid "Where one of these reasons apply you should open a pull request proposing the minimum requir…
8506 msgid "Unsupported integration tests will not be automatically run by CI.  However, the necessary p…
8510 msgid "OpenStack Ansible Modules"
8514 msgid "Please see the `OpenStack guidelines <https://opendev.org/openstack/ansible-collections-open…
8518 msgid "oVirt Ansible Modules"
8522 msgid "The set of modules for interacting with oVirt/RHV are currently part of the community.genera…
8530 msgid "Naming"
8534 msgid "All modules should start with an ``ovirt_`` prefix."
8538 msgid "All modules should be named after the resource it manages in singular form."
8542 msgid "All modules that gather information should have a ``_info`` suffix."
8546 msgid "Interface"
8550 msgid "Every module should return the ID of the resource it manages."
8554 msgid "Every module should return the dictionary of the resource it manages."
8558 msgid "Never change the name of the parameter, as we guarantee backward compatibility. Use aliases …
8562 msgid "If a parameter can't achieve idempotency for any reason, please document it."
8566 msgid "Interoperability"
8570 msgid "All modules should work against all minor versions of version 4 of the API. Version 3 of the…
8574 msgid "Libraries"
8578 msgid "All modules should use ``ovirt_full_argument_spec`` or ``ovirt_info_full_argument_spec`` to …
8582 msgid "All modules should use ``extends_documentation_fragment``: ovirt to go along with ``ovirt_fu…
8586 msgid "All info modules should use ``extends_documentation_fragment``: ``ovirt_info`` to go along w…
8590 msgid "Functions that are common to all modules should be implemented in the ``module_utils/ovirt.p…
8594 msgid "Python SDK version 4 must be used."
8598 msgid "New module development"
8602 msgid "Please read :ref:`developing_modules`, first to know what common properties, functions and f…
8606 msgid "In order to achieve idempotency of oVirt entity attributes, a helper class was created. The …
8610 msgid "The code above handle the check if the entity should be updated, so we don't update the enti…
8614 msgid "If your module must support action handling (for example, virtual machine start) you must en…
8618 msgid "As you can see from the preceding example, the ``action`` method accepts the ``action_condit…
8622 msgid "Testing"
8626 msgid "Integration testing is currently done in oVirt's CI system `on Jenkins <https://jenkins.ovir…
8630 msgid "Please consider using these integration tests if you create a new module or add a new featur…
8634 msgid "Guidelines for VMware module development"
8638 msgid "The Ansible VMware collection (on `Galaxy <https://galaxy.ansible.com/community/vmware>`_, s…
8642 msgid "Testing with govcsim"
8646 msgid "Most of the existing modules are covered by functional tests. The tests are located `here <h…
8650 msgid "By default, the tests run against a vCenter API simulator called `govcsim <https://github.co…
8654 msgid "You can trigger the test of a module manually with the ``ansible-test`` command. For example…
8658 msgid "``govcsim`` is handy because it is much faster than a regular test environment. However, ``g…
8662 msgid "Do not confuse ``govcsim`` with ``vcsim``. ``vcsim`` is an older and outdated version of vCe…
8666 msgid "Testing with your own infrastructure"
8670 msgid "You can also target a regular VMware environment. This paragraph explains step by step how y…
8674 msgid "2 ESXi hosts (6.5 or 6.7)"
8678 msgid "with 2 NIC, the second ones should be available for the test"
8682 msgid "a VCSA host"
8686 msgid "a NFS server"
8690 msgid "Python dependencies:"
8694 msgid "`pyvmomi <https://github.com/vmware/pyvmomi/tree/master/pyVmomi>`_"
8698 msgid "`requests <https://2.python-requests.org/en/master/>`_"
8702 msgid "If you want to deploy your test environment in a hypervisor, both `VMware or Libvirt <https:…
8706 msgid "NFS server configuration"
8710 msgid "Your NFS server must expose the following directory structure:"
8714 msgid "On a Linux system, you can expose the directory over NFS with the following export file:"
8718 msgid "With this configuration all the new files will be owned by the user with the UID and GID 100…
8722 msgid "The service can be enabled with:"
8726 msgid "Configure your installation"
8730 msgid "Prepare a configuration file that describes your set-up. The file should be called :file:`te…
8734 msgid "Using an HTTP proxy"
8738 msgid "Hosting test infrastructure behind an HTTP proxy is supported. You can specify the location …
8742 msgid "In addition, you may need to adjust the variables of the following `var files <https://githu…
8746 msgid "Run the test-suite"
8750 msgid "Once your configuration is ready, you can trigger a run with the following command:"
8754 msgid "``vmware_host_firewall_manager`` is the name of the module to test."
8758 msgid "``vmware_guest`` is much larger than any other test role and is rather slow. You can enable …
8762 msgid "Unit-test"
8766 msgid "The VMware modules have limited unit-test coverage. You can run the test suite with the foll…
8770 msgid "Code style and best practice"
8774 msgid "datacenter argument with ESXi"
8778 msgid "The ``datacenter`` parameter should not use ``ha-datacenter`` by default. This is because th…
8782 msgid "esxi_hostname should not be mandatory"
8786 msgid "Depending upon the functionality provided by ESXi or vCenter, some modules can seamlessly wo…
8790 msgid "Example should use the fully qualified collection name (FQCN)"
8794 msgid "Use FQCN for examples within module documentation. For instance, you should use ``community.…
8798 msgid "This way, the examples do not depend on the ``collections`` directive of the playbook."
8802 msgid "Functional tests"
8806 msgid "Writing new tests"
8810 msgid "If you are writing a new collection of integration tests, there are a few VMware-specific th…
8814 msgid "The test-suite uses a set of common, pre-defined vars located `in prepare_vmware_tests <http…
8818 msgid "This will give you a ready to use cluster, datacenter, datastores, folder, switch, dvswitch,…
8822 msgid "No need to create too much resources"
8826 msgid "Most of the time, it's not necessary to use ``with_items`` to create multiple resources. By …
8830 msgid "VM names should be predictable"
8834 msgid "If you need to create a new VM during your test, you can use ``test_vm1``, ``test_vm2`` or `…
8838 msgid "Avoid the common boiler plate code in your test playbook"
8842 msgid "From Ansible 2.10, the test suite uses `modules_defaults`. This module allow us to preinitia…
8846 msgid "hostname"
8850 msgid "username"
8854 msgid "password"
8858 msgid "validate_certs"
8862 msgid "For example, the following block:"
8866 msgid "should be simplified to just:"
8870 msgid "Typographic convention"
8874 msgid "Nomenclature"
8878 msgid "We try to enforce the following rules in our documentation:"
8882 msgid "VMware, not VMWare or vmware"
8886 msgid "ESXi, not esxi or ESXI"
8890 msgid "vCenter, not vcenter or VCenter"
8894 msgid "We also refer to vcsim's Go implementation with ``govcsim``. This to avoid any confusion wit…
8898 msgid "Guidelines for VMware REST module development"
8902 msgid "The Ansible VMware REST collection (on `Galaxy <https://galaxy.ansible.com/vmware/vmware_res…
8906 msgid "Contribution process"
8910 msgid "The modules of the vmware_rest collection are autogenerated by another tool called `vmware_r…
8914 msgid "If you would like to contribute a change, we would appreciate if you:"
8918 msgid "submit a Github Pull Request (PR) against the vmware_rest_code_generator project"
8922 msgid "but also ensure the generated modules are compliant with our quality criteria."
8926 msgid "You will need:"
8930 msgid "Python 3.6 or greater"
8934 msgid "the `tox <https://tox.readthedocs.io/en/latest/install.html>` command"
8938 msgid "vmware_rest_code_generator"
8942 msgid "Your contribution should follow the coding style of `Black <https://github.com/psf/black>`. …
8946 msgid "To regenerate the vmware_rest collection, you can use the following commands:"
8950 msgid "If you also want to update the EXAMPLE section of the modules, run:"
8954 msgid "Testing with ansible-test"
8958 msgid "All the modules are covered by a functional test. The tests are located in the :file:`tests/…
8962 msgid "To run the tests, you will need a vcenter instance and an ESXi."
8966 msgid "black code formatter"
8970 msgid "We follow the coding style of `Black <https://github.com/psf/black>`. You can run the code f…
8974 msgid "sanity tests"
8978 msgid "Here we use Python 3.8, the minimal version is 3.6."
8982 msgid "integration tests"
8986 msgid "These tests should be run against your test environment."
8990 msgid "..warning:: The test suite will delete all the existing DC from your test environment."
8994 msgid "First, prepare a configuration file, we call it :file:`/tmp/inventory-vmware_rest` in this e…
8998 msgid "To run the tests, use the following command. You may want to adjust the Python version."
9002 msgid "Basic rules"
9006 msgid "Use standard American English"
9010 msgid "Ansible uses Standard American English. Watch for common words that are spelled differently …
9014 msgid "Write for a global audience"
9018 msgid "Everything you say should be understandable by people of different backgrounds and cultures.…
9022 msgid "Follow naming conventions"
9026 msgid "Always follow naming conventions and trademarks."
9030 msgid "Use clear sentence structure"
9034 msgid "Clear sentence structure means:"
9038 msgid "Start with the important information first."
9042 msgid "Avoid padding/adding extra words that make the sentence harder to understand."
9046 msgid "Keep it short - Longer sentences are harder to understand."
9050 msgid "Some examples of improving sentences:"
9055 msgid "Bad:"
9059 msgid "The unwise walking about upon the area near the cliff edge may result in a dangerous fall an…
9064 msgid "Better:"
9068 msgid "Danger! Stay away from the cliff."
9072 msgid "Furthermore, large volumes of water are also required for the process of extraction."
9076 msgid "Extraction also requires large volumes of water."
9080 msgid "Avoid verbosity"
9084 msgid "Write short, succinct sentences. Avoid terms like:"
9088 msgid "\"...as has been said before,\""
9092 msgid "\"..each and every,\""
9096 msgid "\"...point in time,\""
9100 msgid "\"...in order to,\""
9104 msgid "Highlight menu items and commands"
9108 msgid "When documenting menus or commands, it helps to **bold** what is important."
9112 msgid "For menu procedures, bold the menu names, button names, and so on to help the user find them…
9116 msgid "On the **File** menu, click **Open**."
9120 msgid "Type a name in the **User Name** field."
9124 msgid "In the **Open** dialog box, click **Save**."
9128 msgid "On the toolbar, click the **Open File** icon."
9132 msgid "For code or command snippets, use the RST `code-block directive <https://www.sphinx-doc.org/…
9136 msgid "Grammar and Punctuation"
9140 msgid "Common Styles and Usage, and Common Mistakes"
9145 msgid "Ansible"
9149 msgid "Write \"Ansible.\" Not \"Ansible, Inc.\" or \"AnsibleWorks The only exceptions to this rule …
9153 msgid "Never use the logotype by itself in body text. Always keep the same font you are using the r…
9157 msgid "A company is singular in the US. In other words, Ansible is an \"it,\" not a \"they.\""
9161 msgid "Capitalization"
9165 msgid "If it's not a real product, service, or department at Ansible, don't capitalize it. Not even…
9169 msgid "Colon"
9173 msgid "A colon is generally used before a list or series: - The Triangle Area consists of three cit…
9177 msgid "But not if the list is a complement or object of an element in the sentence: - Before going …
9181 msgid "Use a colon after \"as follows\" and \"the following\" if the related list comes immediately…
9185 msgid "Open a terminal."
9189 msgid "Type cd..."
9193 msgid "Use a colon to introduce a bullet list (or dash, or icon/symbol of your choice):"
9197 msgid "In the Properties dialog box, you'll find the following entries:"
9201 msgid "Connection name"
9205 msgid "Count"
9209 msgid "Cost per item"
9213 msgid "Commas"
9217 msgid "Use serial commas, the comma before the \"and\" in a series of three or more items:"
9221 msgid "\"Item 1, item 2, and item 3.\""
9225 msgid "It's easier to read that way and helps avoid confusion. The primary exception to this you wi…
9229 msgid "Commas are always important, considering the vast difference in meanings of the following tw…
9233 msgid "Let's eat, Grandma"
9237 msgid "Let's eat Grandma."
9241 msgid "Correct punctuation could save Grandma's life."
9245 msgid "If that does not convince you, maybe this will:"
9249 msgid "Contractions"
9253 msgid "Do not use contractions in Ansible documents."
9257 msgid "Em dashes"
9261 msgid "When possible, use em-dashes with no space on either side. When full em-dashes aren't availa…
9265 msgid "A pair of em dashes can be used in place of commas to enhance readability. Note, however, th…
9269 msgid "A pair of em dashes can replace a pair of parentheses. Dashes are considered less formal tha…
9273 msgid "When dashes are used in place of parentheses, surrounding punctuation should be omitted. Com…
9277 msgid "When used in place of parentheses at the end of a sentence, only a single dash is used."
9281 msgid "Exclamation points (!)"
9285 msgid "Do not use them at the end of sentences. An exclamation point can be used when referring to …
9289 msgid "Gender References"
9293 msgid "Do not use gender-specific pronouns in documentation. It is far less awkward to read a sente…
9297 msgid "It is fine to use \"you\" when giving instructions and \"the user,\" \"new users,\" and so o…
9301 msgid "Never use \"one\" in place of \"you\" when writing technical documentation. Using \"one\" is…
9305 msgid "Never use \"we\" when writing. \"We\" aren't doing anything on the user side. Ansible's prod…
9309 msgid "Hyphen"
9313 msgid "The hyphen's primary function is the formation of certain compound terms. Do not use a hyphe…
9317 msgid "Use hyphens to avoid ambiguity or confusion:"
9321 msgid "In professionally printed material (particularly books, magazines, and newspapers), the hyph…
9325 msgid "Lists"
9329 msgid "Keep the structure of bulleted lists equivalent and consistent. If one bullet is a verb phra…
9333 msgid "Capitalize the first word of each bullet. Unless it is obvious that it is just a list of ite…
9337 msgid "When the bulleted list appears within the context of other copy, (unless it's a straight lis…
9341 msgid "In some cases where the bullets are appearing independently, such as in a poster or a homepa…
9345 msgid "When giving instructional steps, use numbered lists instead of bulleted lists."
9349 msgid "Months and States"
9353 msgid "Abbreviate months and states according to AP. Months are only abbreviated if they are used i…
9357 msgid "Months: Jan., Feb., March, April, May, June, July, Aug., Sept., Nov., Dec."
9361 msgid "States: Ala., Ariz., Ark., Calif., Colo., Conn., Del., Fla., Ga., Ill., Ind., Kan., Ky., La.…
9365 msgid "Numbers"
9369 msgid "Numbers between one and nine are written out. 10 and above are numerals. The exception to th…
9373 msgid "Phone Numbers"
9377 msgid "Phone number style: 1 (919) 555-0123 x002 and 1 888-GOTTEXT"
9381 msgid "Quotations (Using Quotation Marks and Writing Quotes)"
9385 msgid "\"Place the punctuation inside the quotes,\" the editor said."
9389 msgid "Except in rare instances, use only \"said\" or \"says\" because anything else just gets in t…
9393 msgid "Place the name first right after the quote:"
9397 msgid "\"I like to write first-person because I like to become the character I'm writing,\" Wally L…
9401 msgid "Not:"
9405 msgid "\"I like to write first-person because I like to become the character I'm writing,\" said Wa…
9409 msgid "Semicolon"
9413 msgid "Use a semicolon to separate items in a series if the items contain commas:"
9417 msgid "Everyday I have coffee, toast, and fruit for breakfast; a salad for lunch; and a peanut butt…
9421 msgid "Use a semicolon before a conjunctive adverb (however, therefore, otherwise, namely, for exam…
9425 msgid "Spacing after sentences"
9429 msgid "Use only a single space after a sentence."
9433 msgid "Time"
9437 msgid "Time of day is written as \"4 p.m.\""
9441 msgid "Ansible style guide"
9445 msgid "Welcome to the Ansible style guide! To create clear, concise, consistent, useful materials o…
9449 msgid "Linguistic guidelines"
9453 msgid "We want the Ansible documentation to be:"
9457 msgid "clear"
9461 msgid "direct"
9465 msgid "conversational"
9469 msgid "easy to translate"
9473 msgid "We want reading the docs to feel like having an experienced, friendly colleague explain how …
9477 msgid "Stylistic cheat-sheet"
9481 msgid "This cheat-sheet illustrates a few rules that help achieve the \"Ansible tone\":"
9485 msgid "Rule"
9489 msgid "Good example"
9493 msgid "Bad example"
9497 msgid "Use active voice"
9501 msgid "You can run a task by"
9505 msgid "A task can be run by"
9509 msgid "Use the present tense"
9513 msgid "This command creates a"
9517 msgid "This command will create a"
9521 msgid "Address the reader"
9525 msgid "As you expand your inventory"
9529 msgid "When the number of managed nodes grows"
9533 msgid "Use standard English"
9537 msgid "Return to this page"
9541 msgid "Hop back to this page"
9545 msgid "Use American English"
9549 msgid "The color of the output"
9553 msgid "The colour of the output"
9557 msgid "Header case"
9561 msgid "Headers should be written in sentence case. For example, this section's title is ``Header ca…
9565 msgid "Avoid using Latin phrases"
9569 msgid "Latin words and phrases like ``e.g.`` or ``etc.`` are easily understood by English speakers.…
9573 msgid "Use the following English terms in place of Latin terms or abbreviations:"
9577 msgid "Latin"
9581 msgid "English"
9585 msgid "i.e"
9589 msgid "in other words"
9594 msgid "e.g."
9598 msgid "for example"
9602 msgid "etc"
9606 msgid "and so on"
9610 msgid "via"
9614 msgid "by/ through"
9618 msgid "vs./versus"
9622 msgid "rather than/against"
9626 msgid "reStructuredText guidelines"
9630 msgid "The Ansible documentation is written in reStructuredText and processed by Sphinx. We follow …
9634 msgid "Header notation"
9638 msgid "`Section headers in reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructure…
9642 msgid "``###`` with overline, for parts:"
9646 msgid "``***`` with overline, for chapters:"
9650 msgid "``===`` for sections:"
9654 msgid "``---`` for subsections:"
9658 msgid "``^^^`` for sub-subsections:"
9662 msgid "``\"\"\"`` for paragraphs:"
9666 msgid "Syntax highlighting - Pygments"
9670 msgid "The Ansible documentation supports a range of `Pygments lexers <https://pygments.org/>`_ for…
9674 msgid "The Ansible documentation allows the following values:"
9678 msgid "none (no highlighting)"
9682 msgid "ansible-output (a custom lexer for Ansible output)"
9686 msgid "bash"
9690 msgid "console"
9694 msgid "csharp"
9698 msgid "ini"
9702 msgid "powershell"
9706 msgid "python"
9710 msgid "rst"
9714 msgid "sh"
9718 msgid "shell"
9722 msgid "shell-session"
9726 msgid "text"
9730 msgid "yaml"
9734 msgid "yaml+jinja"
9738 msgid "For example, you can highlight Python code using following syntax:"
9742 msgid "Internal navigation"
9746 msgid "`Anchors (also called labels) and links <https://www.sphinx-doc.org/en/master/usage/restruct…
9750 msgid "Adding anchors"
9754 msgid "Include at least one anchor on every page"
9758 msgid "Place the main anchor above the main header"
9762 msgid "If the file has a unique title, use that for the main page anchor::"
9766 msgid "You may also add anchors elsewhere on the page"
9770 msgid "Adding internal links"
9774 msgid "All internal links must use ``:ref:`` syntax. These links both point to the anchor defined a…
9778 msgid "The second example adds custom text for the link."
9782 msgid "Adding links to modules and plugins"
9786 msgid "Ansible 2.10 and later require the extended Fully Qualified Collection Name (FQCN) as part o…
9790 msgid "For example:"
9794 msgid "displays as :ref:`ansible.builtin.first_found lookup plugin <ansible_collections.ansible.bui…
9798 msgid "Modules require different suffixes from other plugins:"
9802 msgid "Module links use this extended FQCN module name with ``_module`` for the anchor."
9806 msgid "Plugin links use this extended FQCN plugin name with the plugin type (``_connection`` for ex…
9810 msgid "``ansible.builtin`` is the FQCN for modules included in ``ansible.base``. Documentation link…
9814 msgid "Adding local TOCs"
9818 msgid "The page you're reading includes a `local TOC <https://docutils.sourceforge.io/docs/ref/rst/…
9822 msgid "place it below, not above, the main heading and (optionally) introductory text"
9826 msgid "use the ``:local:`` directive so the page's main header is not included"
9830 msgid "do not include a title"
9834 msgid "The syntax is:"
9838 msgid "More resources"
9842 msgid "These pages offer more help with grammatical, stylistic, and technical rules for documentati…
9846 msgid ":ref:`community_documentation_contributions`"
9850 msgid "How to contribute to the Ansible documentation"
9854 msgid ":ref:`testing_documentation_locally`"
9858 msgid "How to build the Ansible documentation"
9862 msgid "#ansible-docs IRC chat channel"
9866 msgid "Resources"
9870 msgid "Follow the style of the :ref:`Ansible Documentation<ansible_documentation>`"
9874 msgid "Ask for advice on IRC, on the ``#ansible-devel`` `libera.chat channel <https://libera.chat/>…
9878 msgid "Review these online style guides:"
9882 msgid "`AP Stylebook <https://www.apstylebook.com>`_"
9886 msgid "`Chicago Manual of Style <https://www.chicagomanualofstyle.org/home.html>`_"
9890 msgid "`Strunk and White's Elements of Style <https://www.crockford.com/wrrrld/style.html>`_"
9894 msgid "Writing documentation so search can find it"
9898 msgid "One of the keys to writing good documentation is to make it findable. Readers use a combinat…
9902 msgid "To ensure Ansible documentation is findable, you should:"
9906 msgid "Use headings that clearly reflect what you are documenting."
9910 msgid "Use numbered lists for procedures or high-level steps where possible."
9914 msgid "Avoid linking to github blobs where possible."
9918 msgid "Using clear headings in documentation"
9922 msgid "We all use simple English when we want to find something. For example, the title of this pag…
9926 msgid "Search optimization"
9930 msgid "Findable documentation"
9934 msgid "Writing for findability"
9938 msgid "What we are really trying to describe is - how do I write documentation so search engines ca…
9942 msgid "One word of caution - you do want to limit the size of your headings. A full heading such as…
9946 msgid "Using numbered lists for `zero position` snippets"
9950 msgid "Google can optimize the search results by adding a `feature snippet <https://support.google.…
9954 msgid "Google returns the feature snippet in the form of numbered steps. Where possible, you should…
9958 msgid "Problems with github blobs on search results"
9962 msgid "Search engines do not typically return github blobs in search results, at least not in highe…
9966 msgid "Other search hints"
9970 msgid "While it may not be possible to adapt your documentation to all search optimizations, keep t…
9974 msgid "**Search engines don't parse beyond the `#` in an html page.** So for example, all the subhe…
9978 msgid "**Make your first few sentences clearly describe your page topic.** Search engines return no…
9982 msgid "Spelling - Word Usage - Common Words and Phrases to Use and Avoid"
9986 msgid "Acronyms"
9990 msgid "Always uppercase. An acronym is a word formed from the initial letters of a name, such as RO…
9994 msgid "Spell out the acronym before using it in alone text, such as \"The Embedded DevKit (EDK)...\…
9998 msgid "Applications"
10002 msgid "When used as a proper name, use the capitalization of the product, such as GNUPro or Source-…
10006 msgid "\"vi\" is always lowercase."
10010 msgid "As"
10014 msgid "This is often used to mean \"because\", but has other connotations, for example, parallel or…
10018 msgid "Asks for"
10022 msgid "Use \"requests\" instead."
10026 msgid "Assure/Ensure/Insure"
10030 msgid "Assure implies a sort of mental comfort. As in \"I assured my husband that I would eventuall…
10034 msgid "Ensure means \"to make sure.\""
10038 msgid "Insure relates to monetary insurance."
10042 msgid "Back up"
10046 msgid "This is a verb. You \"back up\" files; you do not \"backup\" files."
10050 msgid "Backup"
10054 msgid "This is a noun. You create \"backup\" files; you do not create \"back up\" files."
10058 msgid "Backward"
10062 msgid "Correct. Avoid using backwards unless you are stating that something has \"backwards compati…
10066 msgid "Backwards compatibility"
10070 msgid "Correct as is."
10074 msgid "By way of"
10078 msgid "Use \"using\" instead."
10082 msgid "Can/May"
10086 msgid "Use \"can\" to describe actions or conditions that are possible. Use \"may\" only to describ…
10090 msgid "CD or cd"
10094 msgid "When referring to a compact disk, use CD, such as \"Insert the CD into the CD-ROM drive.\" W…
10098 msgid "CD-ROM"
10102 msgid "Correct. Do not use \"cdrom,\" \"CD-Rom,\" \"CDROM,\" \"cd-rom\" or any other variation. Whe…
10106 msgid "Command line"
10110 msgid "Correct. Do not use \"command-line\" or \"commandline\" as a noun. If used as an adjective, …
10114 msgid "Use \"command line\" to describes where to place options for a command, but not where to typ…
10118 msgid "Daylight saving time (DST)"
10122 msgid "Correct. Do not use daylight savings time. Daylight Saving Time (DST) is often misspelled \"…
10126 msgid "Download"
10130 msgid "Correct. Do not use \"down load\" or \"down-load.\""
10134 msgid "Spell it out: \"For example.\""
10138 msgid "Failover"
10142 msgid "When used as a noun, a failover is a backup operation that automatically switches to a stand…
10146 msgid "Fail over"
10150 msgid "When used as a verb, fail over is two words since there can be different tenses such as fail…
10154 msgid "Fewer"
10158 msgid "Fewer is used with plural nouns. Think things you could count.  Time, money, distance, and w…
10162 msgid "File name"
10166 msgid "Correct. Do not use \"filename.\""
10170 msgid "File system"
10174 msgid "Correct. Do not use \"filesystem.\" The system that an operating system or program uses to o…
10178 msgid "For instance"
10182 msgid "For example,\" instead."
10186 msgid "For further/additional/whatever information"
10190 msgid "Use \"For more information\""
10194 msgid "For this reason"
10198 msgid "Use \"therefore\"."
10202 msgid "Forward"
10206 msgid "Correct. Avoid using \"forwards.\""
10210 msgid "Gigabyte (GB)"
10214 msgid "2 to the 30th power (1,073,741,824) bytes. One gigabyte is equal to 1,024 megabytes. Gigabyt…
10218 msgid "Got"
10223 msgid "Avoid. Use \"must\" instead."
10227 msgid "High-availability"
10231 msgid "Correct. Do not use \"high availability.\""
10235 msgid "Highly available"
10239 msgid "Correct. Do not use highly-available.\""
10243 msgid "Hostname"
10247 msgid "Correct. Do not use host name."
10251 msgid "i.e."
10255 msgid "Spell it out: \"That is.\""
10259 msgid "Installer"
10263 msgid "Avoid. Use \"installation program\" instead."
10267 msgid "It's and its"
10271 msgid "\"It's\" is a contraction for \"it is;\" use \"it is\" instead of \"it's.\" Use \"its\" as a…
10275 msgid "Less"
10279 msgid "Less is used with singular nouns. For example \"View less details\" wouldn't be correct but …
10283 msgid "Linux"
10287 msgid "Correct. Do not use \"LINUX\" or \"linux\" unless referring to a command, such as \"To start…
10291 msgid "Login"
10295 msgid "A noun used to refer to the login prompt, such as \"At the login prompt, enter your username…
10299 msgid "Log in"
10303 msgid "A verb used to refer to the act of logging in. Do not use \"login,\" \"loggin,\" \"logon,\" …
10307 msgid "Log on"
10311 msgid "To make a computer system or network recognize you so that you can begin a computer session.…
10315 msgid "Lots of"
10319 msgid "Use \"Several\" or something equivalent instead."
10323 msgid "Make sure"
10327 msgid "This means \"be careful to remember, attend to, or find out something.\" For example, \"...m…
10331 msgid "Manual/man page"
10335 msgid "Correct. Two words. Do not use \"manpage\""
10339 msgid "MB"
10343 msgid "When spelled MB, short for megabyte (1,000,000 or 1,048,576 bytes, depending on the context)…
10347 msgid "When spelled Mb, short for megabit."
10351 msgid "MBps"
10355 msgid "Short for megabytes per second, a measure of data transfer speed. Mass storage devices are g…
10359 msgid "MySQL"
10363 msgid "Common open source database server and client package. Do not use \"MYSQL\" or \"mySQL.\""
10367 msgid "Need to"
10371 msgid "Read-only"
10375 msgid "Correct. Use when referring to the access permissions of files or directories."
10379 msgid "Real time/real-time"
10383 msgid "Depends. If used as a noun, it is the actual time during which something takes place. For ex…
10387 msgid "Refer to"
10391 msgid "Use to indicate a reference (within a manual or website) or a cross-reference (to another ma…
10395 msgid "See"
10399 msgid "Don't use. Use \"Refer to\" instead."
10403 msgid "Since"
10407 msgid "This is often used to mean \"because\", but \"since\" has connotations of time, so be carefu…
10411 msgid "Tells"
10415 msgid "Use \"Instructs\" instead."
10419 msgid "That/which"
10423 msgid "\"That\" introduces a restrictive clause-a clause that must be there for the sentence to mak…
10427 msgid "Then/than"
10431 msgid "\"Then\" refers to a time in the past or the next step in a sequence. \"Than\" is used for c…
10435 msgid "Third-party"
10439 msgid "Correct. Do not use \"third party\"."
10443 msgid "Troubleshoot"
10447 msgid "Correct. Do not use \"trouble shoot\" or \"trouble-shoot.\" To isolate the source of a probl…
10451 msgid "UK"
10456 msgid "Correct as is, no periods."
10460 msgid "UNIX®"
10464 msgid "Correct. Do not use \"Unix\" or \"unix.\" UNIX® is a registered trademark of The Open Group."
10468 msgid "Unset"
10472 msgid "Don't use. Use Clear."
10476 msgid "US"
10480 msgid "User"
10484 msgid "When referring to the reader, use \"you\" instead of \"user.\" For example, \"The user must.…
10488 msgid "Username"
10492 msgid "Correct. Do not use \"user name.\""
10496 msgid "View"
10500 msgid "When using as a reference (\"View the documentation available online.\"), do not use View. U…
10504 msgid "Within"
10508 msgid "Don't use to refer to a file that exists in a directory. Use \"In\"."
10512 msgid "World Wide Web"
10516 msgid "Correct. Capitalize each word. Abbreviate as \"WWW\" or \"Web.\""
10520 msgid "Webpage"
10524 msgid "Correct. Do not use \"web page\" or \"Web page.\""
10528 msgid "Web server"
10532 msgid "Correct. Do not use \"webserver\". For example, \"The Apache HTTP Server is the default Web …
10536 msgid "Website"
10540 msgid "Correct. Do not use \"web site\" or \"Web site.\" For example, \"The Ansible website contain…
10544 msgid "Who/whom"
10548 msgid "Use the pronoun \"who\" as a subject. Use the pronoun \"whom\" as a direct object, an indire…
10552 msgid "Will"
10556 msgid "Do not use future tense unless it is absolutely necessary. For instance, do not use the sent…
10560 msgid "Wish"
10564 msgid "Use \"need\" instead of \"desire\" and \"wish.\" Use \"want\" when the reader's actions are …
10568 msgid "x86"
10572 msgid "Correct. Do not capitalize the \"x.\""
10576 msgid "x86_64"
10580 msgid "Do not use. Do not use \"Hammer\". Always use \"AMD64 and Intel® EM64T\" when referring to t…
10584 msgid "You"
10588 msgid "Correct. Do not use \"I,\" \"he,\" or \"she.\""
10592 msgid "You may"
10596 msgid "Try to avoid using this. For example, \"you may\" can be eliminated from this sentence \"You…
10600 msgid "Trademark Usage"
10604 msgid "Why is it important to use the TM, SM, and ® for our registered marks?"
10608 msgid "Before a trademark is registered with the United States Patent and Trademark Office it is ap…
10612 msgid "Once the trademark is registered, it is appropriate to use the symbol in place of the TM or …
10616 msgid "General Rules:"
10620 msgid "Trademarks should be used on 1st references on a page or within a section."
10624 msgid "Use Red Hat® Ansible® Automation Platform or Ansible®, on first reference when referring to …
10628 msgid "Use \"Ansible\" alone as the company name, as in \"Ansible announced quarterly results,\" wh…
10632 msgid "Also add the trademark disclaimer. * When using Ansible trademarks in the body of written te…
10636 msgid "For Registered Trademarks: - [Name of Trademark] is a registered trademark of Red Hat, Inc. …
10640 msgid "For Unregistered Trademarks (TMs/SMs): - [Name of Trademark] is a trademark of Red Hat, Inc.…
10644 msgid "For registered and unregistered trademarks: - [Name of Trademark] is a registered trademark …
10648 msgid "Guidelines for the proper use of trademarks:"
10652 msgid "Always distinguish trademarks from surround text with at least initial capital letters or in…
10656 msgid "Always use proper trademark form and spelling."
10660 msgid "Never use a trademark as a noun. Always use a trademark as an adjective modifying the noun."
10664 msgid "Correct: Red Hat® Ansible® Automation Platform system performance is incredible."
10668 msgid "Incorrect: Ansible's performance is incredible."
10672 msgid "Never use a trademark as a verb. Trademarks are products or services, never actions."
10676 msgid "Correct: \"Orchestrate your entire network using Red Hat® Ansible® Automation Platform.\""
10680 msgid "Incorrect: \"Ansible your entire network.\""
10684 msgid "Never modify a trademark to a plural form. Instead, change the generic word from the singula…
10688 msgid "Correct: \"Corporate demand for Red Hat® Ansible® Automation Platform software is surging.\""
10692 msgid "Incorrect: \"Corporate demand for Ansible is surging.\""
10696 msgid "Never modify a trademark from its possessive form, or make a trademark possessive. Always us…
10700 msgid "Never translate a trademark into another language."
10704 msgid "Never use trademarks to coin new words or names."
10708 msgid "Never use trademarks to create a play on words."
10712 msgid "Never alter a trademark in any way including through unapproved fonts or visual identifiers."
10716 msgid "Never abbreviate or use any Ansible trademarks as an acronym."
10720 msgid "The importance of Ansible trademarks"
10724 msgid "The Ansible trademark and the \"A\" logo in a shaded circle are our most valuable assets. Th…
10728 msgid "The mark consists of the letter \"A\" in a shaded circle. As of 5/11/15, this was a pending …
10732 msgid "Common Ansible Trademarks"
10736 msgid "Ansible®"
10740 msgid "Other Common Trademarks and Resource Sites:"
10744 msgid "Linux is a registered trademark of Linus Torvalds."
10748 msgid "UNIX® is a registered trademark of The Open Group."
10752 msgid "Microsoft, Windows, Vista, XP, and NT are registered trademarks or trademarks of Microsoft C…
10756 msgid "Apple, Mac, Mac OS, Macintosh, Pages and TrueType are either registered trademarks or tradem…
10760 msgid "Adobe, Acrobat, GoLive, InDesign, Illustrator, PostScript , PhotoShop and the OpenType logo …
10764 msgid "Macromedia and Macromedia Flash are trademarks of Macromedia, Inc. https://www.adobe.com/leg…
10768 msgid "IBM is a registered trademark of International Business Machines Corporation. https://www.ib…
10772 msgid "Celeron, Celeron Inside, Centrino, Centrino logo, Core Inside, Intel Core, Intel Inside, Int…
10776 msgid "Voice Style"
10780 msgid "The essence of the Ansible writing style is short sentences that flow naturally together. Mi…
10784 msgid "Write how real people speak..."
10788 msgid "...but try to avoid slang and colloquialisms that might not translate well into other langua…
10792 msgid "Say big things with small words."
10796 msgid "Be direct. Tell the reader exactly what you want them to do."
10800 msgid "Be honest."
10804 msgid "Short sentences show confidence."
10808 msgid "Grammar rules are meant to be bent, but only if the reader knows you are doing this."
10812 msgid "Choose words with fewer syllables for faster reading and better understanding."
10816 msgid "Think of copy as one-on-one conversations rather than as a speech. It's more difficult to ig…
10820 msgid "When possible, start task-oriented sentences (those that direct a user to do something) with…
10824 msgid "Active Voice"
10828 msgid "Use the active voice (\"Start Linuxconf by typing...\") rather than passive (\"Linuxconf can…
10832 msgid "Why Use a Style Guide?"
10836 msgid "Style guides are important because they ensure consistency in the content, look, and feel of…
10840 msgid "Remember, a style guide is only useful if it is used, updated, and enforced.  Style Guides a…
10844 msgid "As changes are made to the overall Ansible site design, be sure to update this style guide w…
10848 msgid "This style guide incorporates current Ansible resources and information so that overall site…
10853 msgid "Testing Ansible"
10857 msgid "Why test your Ansible contributions?"
10861 msgid "If you're a developer, one of the most valuable things you can do is to look at GitHub issue…
10865 msgid "Ansible users who understand how to write playbooks and roles should be able to test their w…
10869 msgid "Read on to learn how Ansible is tested, how to test your contributions locally, and how to e…
10873 msgid "If you want to learn about testing collections, read :ref:`testing_collections`"
10877 msgid "Types of tests"
10881 msgid "At a high level we have the following classifications of tests:"
10886 msgid "compile"
10890 msgid ":ref:`testing_compile`"
10894 msgid "Test python code against a variety of Python versions."
10898 msgid "sanity"
10902 msgid "Sanity tests are made up of scripts and tools used to perform static code analysis."
10906 msgid "The primary purpose of these tests is to enforce Ansible coding standards and requirements."
10910 msgid "integration"
10914 msgid "Functional tests of modules and Ansible core functionality."
10918 msgid "units"
10923 msgid ":ref:`testing_units`"
10927 msgid "Tests directly against individual parts of the code base."
10931 msgid "If you're a developer, one of the most valuable things you can do is look at the GitHub issu…
10935 msgid "Even for non developers, helping to test pull requests for bug fixes and features is still i…
10939 msgid "Testing within GitHub & Azure Pipelines"
10943 msgid "Organization"
10947 msgid "When Pull Requests (PRs) are created they are tested using Azure Pipelines, a Continuous Int…
10951 msgid "When Azure Pipelines detects an error and it can be linked back to a file that has been modi…
10955 msgid "From the above example we can see that ``--test pep8`` and ``--test validate-modules`` have …
10959 msgid "If you haven't already got Ansible available, use the local checkout by running::"
10963 msgid "Then run the tests detailed in the GitHub comment::"
10967 msgid "If there isn't a GitHub comment stating what's failed you can inspect the results by clickin…
10971 msgid "Rerunning a failing CI job"
10975 msgid "Occasionally you may find your PR fails due to a reason unrelated to your change. This could…
10979 msgid "a temporary issue accessing an external resource, such as a yum or git repo"
10983 msgid "a timeout creating a virtual machine to run the tests on"
10987 msgid "If either of these issues appear to be the case, you can rerun the Azure Pipelines test by:"
10991 msgid "adding a comment with ``/rebuild`` (full rebuild) or ``/rebuild_failed`` (rebuild only faile…
10995 msgid "closing and re-opening the PR (full rebuild)"
10999 msgid "making another change to the PR and pushing to GitHub"
11003 msgid "If the issue persists, please contact us in the ``#ansible-devel`` irc channel on the `irc.l…
11007 msgid "How to test a PR"
11011 msgid "Ideally, code should add tests that prove that the code works. That's not always possible an…
11015 msgid "Thankfully, helping to test Ansible is pretty straightforward, assuming you are familiar wit…
11019 msgid "Setup: Checking out a Pull Request"
11023 msgid "You can do this by:"
11027 msgid "checking out Ansible"
11031 msgid "fetching the proposed changes into a test branch"
11035 msgid "testing"
11039 msgid "commenting on that particular issue on GitHub"
11043 msgid "Here's how:"
11047 msgid "Testing source code from GitHub pull requests sent to us does have some inherent risk, as th…
11051 msgid "Create a fresh area to work::"
11055 msgid "Next, find the pull request you'd like to test and make note of its number. It will look som…
11059 msgid "Only test ``ansible:devel``"
11063 msgid "It is important that the PR request target be ``ansible:devel``, as we do not accept pull re…
11067 msgid "Use the pull request number when you fetch the proposed changes and create your branch for t…
11071 msgid "The first command fetches the proposed changes from the pull request and creates a new branc…
11075 msgid "If the GitHub user interface shows that the pull request will not merge cleanly, we do not r…
11079 msgid "Some users do not create feature branches, which can cause problems when they have multiple,…
11083 msgid "The Ansible source includes a script that allows you to use Ansible directly from source wit…
11087 msgid "Simply source it (to use the Linux/Unix terminology) to begin using it immediately::"
11091 msgid "This script modifies the ``PYTHONPATH`` environment variables (along with a few other things…
11095 msgid "Testing the Pull Request"
11099 msgid "At this point, you should be ready to begin testing!"
11103 msgid "Some ideas of what to test are:"
11107 msgid "Create a test Playbook with the examples in and check if they function correctly"
11111 msgid "Test to see if any Python backtraces returned (that's a bug)"
11115 msgid "Test on different operating systems, or against different library versions"
11119 msgid "Run sanity tests"
11123 msgid "More information: :ref:`testing_sanity`"
11127 msgid "Run unit tests"
11131 msgid "More information: :ref:`testing_units`"
11135 msgid "Run integration tests"
11139 msgid "More information: :ref:`testing_integration`"
11143 msgid "Any potential issues should be added as comments on the pull request (and it's acceptable to…
11147 msgid "Example::"
11151 msgid "If the PR does not resolve the issue, or if you see any failures from the unit/integration t…
11155 msgid "This change causes errors for me."
11159 msgid "When I ran this Ubuntu 16.04 it failed with the following:"
11163 msgid "\\```"
11167 msgid "some output"
11171 msgid "StackTrace"
11175 msgid "some other output"
11179 msgid "Code Coverage Online"
11183 msgid "`The online code coverage reports <https://codecov.io/gh/ansible/ansible>`_ are a good way t…
11187 msgid "The code coverage reports only cover the ``devel`` branch of Ansible where new feature devel…
11191 msgid "Want to know more about testing?"
11195 msgid "If you'd like to know more about the plans for improving testing Ansible then why not join t…
11199 msgid "action-plugin-docs"
11203 msgid "Each action plugin should have a matching module of the same name to provide documentation."
11207 msgid "ansible-doc"
11211 msgid "Verifies that ``ansible-doc`` can parse module documentation on all supported Python version…
11215 msgid "ansible-requirements"
11219 msgid "``test/lib/ansible_test/_data/requirements/sanity.import-plugins.txt`` must be an identical …
11223 msgid "ansible-var-precedence-check"
11227 msgid "Check the order of precedence for Ansible variables against :ref:`ansible_variable_precedenc…
11231 msgid "azure-requirements"
11235 msgid "Update the Azure integration test requirements file when changes are made to the Azure packa…
11239 msgid "bin-symlinks"
11243 msgid "The ``bin/`` directory in Ansible must contain only symbolic links to executable files. Thes…
11247 msgid "This is required to allow ``ansible-test`` to work with containers and remote hosts when run…
11251 msgid "Symlinks for each entry point in ``bin/`` must also be present in ``test/lib/ansible_test/_d…
11255 msgid "boilerplate"
11259 msgid "Most Python files should include the following boilerplate:"
11263 msgid "botmeta"
11267 msgid "Verifies that ``./github/BOTMETA.yml`` is valid."
11271 msgid "changelog"
11275 msgid "Basic linting of changelog fragments with `antsibull-changelog lint <https://pypi.org/projec…
11279 msgid "One or more of the following sections are required:"
11283 msgid "major_changes"
11287 msgid "minor_changes"
11291 msgid "breaking_changes"
11295 msgid "deprecated_features"
11299 msgid "removed_features"
11303 msgid "security_fixes"
11307 msgid "bugfixes"
11311 msgid "known_issues"
11315 msgid "New modules and plugins must not be included in changelog fragments."
11319 msgid "See :ref:`testing_compile` for more information."
11323 msgid "configure-remoting-ps1"
11327 msgid "The file ``examples/scripts/ConfigureRemotingForAnsible.ps1`` is required and must be a regu…
11331 msgid "deprecated-config"
11335 msgid "``DOCUMENTATION`` config is scheduled for removal"
11339 msgid "docs-build"
11343 msgid "Verifies that ``make singlehtmldocs`` in ``docs/docsite/`` completes without errors."
11347 msgid "empty-init"
11351 msgid "The ``__init__.py`` files under the following directories must be empty.  For some of these …
11355 msgid "``lib/ansible/modules/``"
11359 msgid "``lib/ansible/module_utils/``"
11363 msgid "``test/units/``"
11367 msgid "future-import-boilerplate"
11371 msgid "Most Python files should include the following boilerplate at the top of the file, right aft…
11375 msgid "This uses Python 3 semantics for absolute vs relative imports, division, and print.  By doin…
11379 msgid "When Python 2 encounters an import of a name in a file like ``import copy`` it attempts to l…
11383 msgid "`Absolute and relative imports <https://www.python.org/dev/peps/pep-0328>`_"
11387 msgid "In Python 2, the division operator (``/``) returns integer values when used with integers.  …
11391 msgid "`Changing the division operator <https://www.python.org/dev/peps/pep-0238>`_"
11395 msgid "In Python 2, :func:`python:print` is a keyword.  In Python 3, :func:`python3:print` is a fun…
11399 msgid "`Make print a function <https://www.python.org/dev/peps/pep-3105>`_"
11403 msgid "ignores"
11407 msgid "Sanity tests for individual files can be skipped, and specific errors can be ignored."
11411 msgid "When to Ignore Errors"
11415 msgid "Sanity tests are designed to improve code quality and identify common issues with content. W…
11419 msgid "As development of Ansible continues, sanity tests are expanded to detect issues that previou…
11423 msgid "When code is fixed to resolve sanity test errors, any relevant ignores must also be removed.…
11427 msgid "When to Skip Tests"
11431 msgid "Although rare, there are reasons for skipping a sanity test instead of ignoring the errors i…
11435 msgid "If a sanity test results in a traceback when processing content, that error cannot be ignore…
11439 msgid "Caution should be used when skipping sanity tests instead of ignoring them. Since the test i…
11443 msgid "Ignore File Location"
11447 msgid "The location of the ignore file depends on the type of content being tested."
11451 msgid "Ansible Collections"
11455 msgid "Since sanity tests change between Ansible releases, a separate ignore file is needed for eac…
11459 msgid "The filename is ``tests/sanity/ignore-X.Y.txt`` where ``X.Y`` is the Ansible release being u…
11463 msgid "Maintaining a separate file for each Ansible release allows a collection to pass tests for m…
11467 msgid "When testing Ansible, all ignores are placed in the ``test/sanity/ignore.txt`` file."
11471 msgid "Only a single file is needed because ``ansible-test`` is developed and released as a part of…
11475 msgid "Ignore File Format"
11479 msgid "The ignore file contains one entry per line. Each line consists of two columns, separated by…
11483 msgid "The first column specifies the file path that the entry applies to. File paths must be relat…
11487 msgid "The second column specifies the sanity test that the entry applies to. This will be the name…
11491 msgid "Below are some example ignore entries for an Ansible collection::"
11495 msgid "It is also possible to skip a sanity test for a specific file. This is done by adding ``!ski…
11499 msgid "Below are some example skip entries for an Ansible collection::"
11503 msgid "Ignore File Errors"
11507 msgid "There are various errors that can be reported for the ignore file itself:"
11511 msgid "syntax errors parsing the ignore file"
11515 msgid "references a file path that does not exist"
11519 msgid "references to a sanity test that does not exist"
11523 msgid "ignoring an error that does not occur"
11527 msgid "ignoring a file which is skipped"
11531 msgid "duplicate entries"
11535 msgid "import"
11539 msgid "Ansible allows unchecked imports of some libraries from specific directories, listed at the …
11543 msgid "In modules:"
11547 msgid "In plugins:"
11551 msgid "Ansible allows the following unchecked imports from these specific directories:"
11555 msgid "ansible-core:"
11559 msgid "For ``lib/ansible/modules/`` and ``lib/ansible/module_utils/``, unchecked imports are only a…
11563 msgid "For ``lib/ansible/plugins/``, unchecked imports are only allowed from the Python standard li…
11567 msgid "collections:"
11571 msgid "For ``plugins/modules/`` and ``plugins/module_utils/``, unchecked imports are only allowed f…
11575 msgid "For other directories in ``plugins/`` (see `the community collection requirements <https://g…
11580 msgid "Sanity Tests"
11584 msgid "The following sanity tests are available as ``--test`` options for ``ansible-test sanity``. …
11588 msgid "For information on how to run these tests, see :ref:`sanity testing guide <testing_sanity>`."
11592 msgid "integration-aliases"
11596 msgid "Integration tests are executed by ``ansible-test`` and reside in directories under ``test/in…
11600 msgid "Aliases are explained in the following sections. Each alias must be on a separate line in an…
11604 msgid "Groups"
11608 msgid "Tests must be configured to run in exactly one group. This is done by adding the appropriate…
11612 msgid "The following are examples of some of the available groups:"
11616 msgid "``shippable/posix/group1``"
11620 msgid "``shippable/windows/group2``"
11624 msgid "``shippable/azure/group3``"
11628 msgid "``shippable/aws/group1``"
11632 msgid "``shippable/cloud/group1``"
11636 msgid "Groups are used to balance tests across multiple CI jobs to minimize test run time. They als…
11640 msgid "When selecting a group for a new test, use the same group as existing tests similar to the o…
11644 msgid "Setup"
11648 msgid "Aliases can be used to execute setup targets before running tests:"
11652 msgid "``setup/once/TARGET`` - Run the target ``TARGET`` before the first target that requires it."
11656 msgid "``setup/always/TARGET`` - Run the target ``TARGET`` before each target that requires it."
11660 msgid "Aliases can be used to express some test requirements:"
11664 msgid "``needs/privileged`` - Requires ``--docker-privileged`` when running tests with ``--docker``…
11668 msgid "``needs/root`` - Requires running tests as ``root`` or with ``--docker``."
11672 msgid "``needs/ssh`` - Requires SSH connections to localhost (or the test container with ``--docker…
11676 msgid "``needs/httptester`` - Requires use of the http-test-container to run tests."
11680 msgid "Dependencies"
11684 msgid "Some test dependencies are automatically discovered:"
11688 msgid "Ansible role dependencies defined in ``meta/main.yml`` files."
11692 msgid "Setup targets defined with ``setup/*`` aliases."
11696 msgid "Symbolic links from one target to a file in another target."
11700 msgid "Aliases can be used to declare dependencies that are not handled automatically:"
11704 msgid "``needs/target/TARGET`` - Requires use of the test target ``TARGET``."
11708 msgid "``needs/file/PATH`` - Requires use of the file ``PATH`` relative to the git root."
11712 msgid "Skipping"
11716 msgid "Aliases can be used to skip platforms using one of the following:"
11720 msgid "``skip/freebsd`` - Skip tests on FreeBSD."
11724 msgid "``skip/osx`` - Skip tests on macOS."
11728 msgid "``skip/rhel`` - Skip tests on RHEL."
11732 msgid "``skip/docker`` - Skip tests when running in a Docker container."
11736 msgid "Platform versions, as specified using the ``--remote`` option with ``/`` removed, can also b…
11740 msgid "``skip/freebsd11.1`` - Skip tests on FreeBSD 11.1."
11744 msgid "``skip/rhel7.6`` - Skip tests on RHEL 7.6."
11748 msgid "Windows versions, as specified using the ``--windows`` option can also be skipped:"
11752 msgid "``skip/windows/2008`` - Skip tests on Windows Server 2008."
11756 msgid "``skip/windows/2012-R2`` - Skip tests on Windows Server 2012 R2."
11760 msgid "Aliases can be used to skip Python major versions using one of the following:"
11764 msgid "``skip/python2`` - Skip tests on Python 2.x."
11768 msgid "``skip/python3`` - Skip tests on Python 3.x."
11772 msgid "For more fine grained skipping, use conditionals in integration test playbooks, such as:"
11776 msgid "Miscellaneous"
11780 msgid "There are several other aliases available as well:"
11784 msgid "``destructive`` - Requires ``--allow-destructive`` to run without ``--docker`` or ``--remote…
11788 msgid "``hidden`` - Target is ignored. Usable as a dependency. Automatic for ``setup_`` and ``prepa…
11792 msgid "Unstable"
11796 msgid "Tests which fail sometimes should be marked with the ``unstable`` alias until the instabilit…
11800 msgid "This avoids unnecessary test failures for other pull requests, as well as tests on merge run…
11804 msgid "There are two ways to run unstable tests manually:"
11808 msgid "Use the ``--allow-unstable`` option for ``ansible-test``"
11812 msgid "Prefix the test name with ``unstable/`` when passing it to ``ansible-test``."
11816 msgid "Tests will be marked as unstable by a member of the Ansible Core Team. GitHub issues_ will b…
11820 msgid "Disabled"
11824 msgid "Tests which always fail should be marked with the ``disabled`` alias until they can be fixed…
11828 msgid "Disabled tests are automatically skipped."
11832 msgid "There are two ways to run disabled tests manually:"
11836 msgid "Use the ``--allow-disabled`` option for ``ansible-test``"
11840 msgid "Prefix the test name with ``disabled/`` when passing it to ``ansible-test``."
11844 msgid "Tests will be marked as disabled by a member of the Ansible Core Team. GitHub issues_ will b…
11848 msgid "Unsupported"
11852 msgid "Tests which cannot be run in CI should be marked with the ``unsupported`` alias. Most tests …
11856 msgid "However, if that is not possible then marking a test as unsupported will prevent it from run…
11860 msgid "There are two ways to run unsupported tests manually:"
11864 msgid "Use the ``--allow-unsupported`` option for ``ansible-test``"
11868 msgid "Prefix the test name with ``unsupported/`` when passing it to ``ansible-test``."
11872 msgid "Tests will be marked as unsupported by the contributor of the test."
11876 msgid "Cloud"
11880 msgid "Tests for cloud services and other modules that require access to external APIs usually requ…
11884 msgid "These require an additional alias to indicate the required test plugin."
11888 msgid "Some of the available aliases are:"
11892 msgid "``cloud/aws``"
11896 msgid "``cloud/azure``"
11900 msgid "``cloud/cs``"
11904 msgid "``cloud/foreman``"
11908 msgid "``cloud/openshift``"
11912 msgid "``cloud/tower``"
11916 msgid "``cloud/vcenter``"
11920 msgid "Untested"
11924 msgid "Every module and plugin should have integration tests, even if the tests cannot be run in CI…
11928 msgid "Issues"
11932 msgid "Tests that are marked as unstable_ or disabled_ will have an issue created to track the stat…
11936 msgid "`AWS <https://github.com/ansible/ansible/projects/21>`_"
11940 msgid "`Azure <https://github.com/ansible/ansible/projects/22>`_"
11944 msgid "`Windows <https://github.com/ansible/ansible/projects/23>`_"
11948 msgid "`General <https://github.com/ansible/ansible/projects/25>`_"
11952 msgid "Questions"
11956 msgid "For questions about integration tests reach out to @mattclay or @gundalow on GitHub or ``#an…
11960 msgid "line-endings"
11964 msgid "All files must use ``\\n`` for line endings instead of ``\\r\\n``."
11970 msgid "metaclass-boilerplate"
11974 msgid "Most Python files should include the following boilerplate at the top of the file, right aft…
11978 msgid "Python 2 has \"new-style classes\" and \"old-style classes\" whereas Python 3 only has new-s…
11982 msgid "no-assert"
11986 msgid "Do not use ``assert`` in production Ansible python code. When running Python with optimizati…
11990 msgid "Instead of using ``assert`` you should utilize simple ``if`` statements, that result in rais…
11994 msgid "Modules will not have access to ``AnsibleAssertionError`` and should instead raise ``Asserti…
11998 msgid "no-basestring"
12002 msgid "Do not use ``isinstance(s, basestring)`` as basestring has been removed in Python3.  You can…
12006 msgid "If this is part of code to convert a string to a particular type, ``ansible.module_utils.com…
12010 msgid "no-dict-iteritems"
12014 msgid "The ``dict.iteritems`` method has been removed in Python 3. There are two recommended altern…
12018 msgid "no-dict-iterkeys"
12022 msgid "The ``dict.iterkeys`` method has been removed in Python 3. Use the following instead:"
12026 msgid "no-dict-itervalues"
12030 msgid "The ``dict.itervalues`` method has been removed in Python 3. There are two recommended alter…
12034 msgid "no-get-exception"
12038 msgid "We created a function, ``ansible.module_utils.pycompat24.get_exception`` to help retrieve ex…
12042 msgid "no-illegal-filenames"
12046 msgid "Files and directories should not contain illegal characters or names so that Ansible can be …
12050 msgid "Illegal Characters"
12054 msgid "The following characters are not allowed to be used in any part of the file or directory nam…
12058 msgid "``<``"
12062 msgid "``>``"
12066 msgid "``:``"
12070 msgid "``\"``"
12074 msgid "``/``"
12078 msgid "``\\``"
12082 msgid "``|``"
12086 msgid "``?``"
12090 msgid "``*``"
12094 msgid "Any characters whose integer representations are in the range from 0 through to 31 like ``\\…
12099 msgid "The following characters are not allowed to be used as the last character of a file or direc…
12103 msgid "``.``"
12107 msgid "``\" \"`` (just the space character)"
12111 msgid "Illegal Names"
12115 msgid "The following names are not allowed to be used as the name of a file or directory excluding …
12119 msgid "``CON``"
12123 msgid "``PRN``"
12127 msgid "``AUX``"
12131 msgid "``NUL``"
12135 msgid "``COM1``"
12139 msgid "``COM2``"
12143 msgid "``COM3``"
12147 msgid "``COM4``"
12151 msgid "``COM5``"
12155 msgid "``COM6``"
12159 msgid "``COM7``"
12163 msgid "``COM8``"
12167 msgid "``COM9``"
12171 msgid "``LPT1``"
12175 msgid "``LPT2``"
12179 msgid "``LPT3``"
12183 msgid "``LPT4``"
12187 msgid "``LPT5``"
12191 msgid "``LPT6``"
12195 msgid "``LPT7``"
12199 msgid "``LPT8``"
12203 msgid "``LPT9``"
12207 msgid "For example, the file ``folder/COM1``, ``folder/COM1.txt`` are illegal but ``folder/COM1-fil…
12211 msgid "no-main-display"
12215 msgid "As of Ansible 2.8, ``Display`` should no longer be imported from ``__main__``."
12219 msgid "``Display`` is now a singleton and should be utilized like the following::"
12223 msgid "There is no longer a need to attempt ``from __main__ import display`` inside a ``try/except`…
12227 msgid "no-smart-quotes"
12231 msgid "Smart quotes (``”“‘’``) should not be used.  Use plain ascii quotes (``\"'``) instead."
12235 msgid "no-tests-as-filters"
12239 msgid "Using Ansible provided Jinja2 tests as filters will be removed in Ansible 2.9."
12243 msgid "Prior to Ansible 2.5, Jinja2 tests included within Ansible were most often used as filters. …
12247 msgid "Jinja2 tests are used for comparisons, whereas filters are used for data manipulation, and h…
12251 msgid "As of Ansible 2.5 using an Ansible provided Jinja2 test with filter syntax will display a de…
12255 msgid "no-underscore-variable"
12259 msgid "In the future, Ansible may use the identifier ``_`` to internationalize its message strings.…
12263 msgid "In common practice, ``_`` is frequently used as a dummy variable (a variable to receive a va…
12267 msgid "Example of unfixed code:"
12271 msgid "Example of fixed code:"
12275 msgid "no-unicode_literals"
12279 msgid "The use of :code:`from __future__ import unicode_literals` has been deemed an anti-pattern. …
12283 msgid "It makes it so one can't jump into the middle of a file and know whether a bare literal stri…
12287 msgid "It removes the ability to define native strings (a string which should be a byte string on p…
12291 msgid "It makes for more context switching.  A programmer could be reading one file which has `unic…
12295 msgid "no-unwanted-files"
12299 msgid "Specific file types are allowed in certain directories:"
12303 msgid "``lib`` - All content must reside in the ``lib/ansible`` directory."
12307 msgid "``lib/ansible`` - Only source code with one of the following extensions is allowed:"
12311 msgid "``*.cs`` - C#"
12315 msgid "``*.ps1`` - PowerShell"
12319 msgid "``*.psm1`` - PowerShell"
12323 msgid "``*.py`` - Python"
12327 msgid "no-wildcard-import"
12331 msgid "Using :code:`import *` is a bad habit which pollutes your namespace, hinders debugging, and …
12335 msgid "Examples of unfixed code:"
12339 msgid "Examples of fixed code:"
12343 msgid "obsolete-files"
12347 msgid "Directories in the Ansible source tree are sometimes made obsolete. Files should not exist i…
12351 msgid "Below are some of the obsolete directories and their new locations:"
12355 msgid "All of ``test/runner/`` is now under ``test/lib/ansible_test/`` instead. The organization of…
12359 msgid "Most subdirectories of ``test/sanity/`` (with some exceptions) are now under ``test/lib/ansi…
12363 msgid "This error occurs most frequently for open pull requests which add or modify files in direct…
12367 msgid "package-data"
12371 msgid "Verifies that the combination of ``MANIFEST.in`` and ``package_data`` from ``setup.py`` prop…
12375 msgid "pep8"
12379 msgid "Python static analysis for PEP 8 style guideline compliance."
12383 msgid "See :ref:`testing_pep8` for more information."
12387 msgid "pslint"
12391 msgid "PowerShell static analysis for common programming errors using `PSScriptAnalyzer <https://gi…
12395 msgid "pylint"
12400 msgid "Python static analysis for common programming errors."
12404 msgid "pylint-ansible-test"
12408 msgid "A more strict set of rules applied to ``ansible-test``."
12412 msgid "Release names"
12416 msgid "Verifies that the most recent release name has been added to ``./github/RELEASE_NAMES.yml``"
12420 msgid "replace-urlopen"
12424 msgid "Use ``open_url`` from ``module_utils`` instead of ``urlopen``."
12428 msgid "required-and-default-attributes"
12432 msgid "Use only one of ``default`` or ``required`` with ``FieldAttribute``."
12436 msgid "rstcheck"
12440 msgid "Check reStructuredText files for syntax and formatting issues."
12444 msgid "runtime-metadata.yml"
12448 msgid "Validates the schema for:"
12452 msgid "ansible-core's ``lib/ansible/config/ansible_builtin_runtime.yml``"
12456 msgid "collection's ``meta/runtime.yml``"
12460 msgid "sanity-docs"
12464 msgid "Documentation for each ``ansible-test sanity`` test is required."
12468 msgid "shebang"
12472 msgid "Most executable files should only use one of the following shebangs:"
12476 msgid "``#!/bin/sh``"
12480 msgid "``#!/bin/bash``"
12484 msgid "``#!/usr/bin/make``"
12488 msgid "``#!/usr/bin/env python``"
12492 msgid "``#!/usr/bin/env bash``"
12496 msgid "NOTE: For ``#!/bin/bash``, any of the options ``eux`` may also be used, such as ``#!/bin/bas…
12500 msgid "This does not apply to Ansible modules, which should not be executable and must always use `…
12504 msgid "Some exceptions are permitted. Ask if you have questions."
12508 msgid "shellcheck"
12512 msgid "Static code analysis for shell scripts using the excellent `shellcheck <https://www.shellche…
12516 msgid "symlinks"
12520 msgid "Symbolic links are only permitted for files that exist to ensure proper tarball generation d…
12524 msgid "If other types of symlinks are needed for tests they must be created as part of the test."
12528 msgid "test-constraints"
12532 msgid "Constraints for test requirements should be in ``test/lib/ansible_test/_data/requirements/co…
12536 msgid "update-bundled"
12540 msgid "Check whether any of our known bundled code needs to be updated for a new upstream release."
12544 msgid "This test can error in the following ways:"
12548 msgid "The bundled code is out of date with regard to the latest release on pypi.  Update the code …
12552 msgid "The code is lacking a _BUNDLED_METADATA variable.  This typically happens when a bundled ver…
12556 msgid "A file has a _BUNDLED_METADATA variable but the file isn't specified in :file:`test/sanity/c…
12560 msgid "_BUNDLED_METADATA has the following fields:"
12564 msgid "pypi_name"
12568 msgid "Name of the bundled package on pypi"
12572 msgid "Version of the package that we are including here"
12576 msgid "version_constraints"
12580 msgid "Optional PEP440 specifier for the version range that we are bundling. Currently, the only va…
12584 msgid "use-argspec-type-path"
12588 msgid "The AnsibleModule argument_spec knows of several types beyond the standard python types.  On…
12592 msgid "This test looks for use of :func:`os.path.expanduser <python:os.path.expanduser>` in modules…
12596 msgid "use-compat-six"
12600 msgid "Use ``six`` from ``module_utils`` instead of ``six``."
12605 msgid "validate-modules"
12609 msgid "Analyze modules for common issues in code and documentation."
12613 msgid "See :ref:`testing_validate-modules` for more information."
12617 msgid "yamllint"
12621 msgid "Check YAML files for syntax and formatting issues."
12625 msgid "Compile Tests"
12630 msgid "Overview"
12634 msgid "Compile tests check source files for valid syntax on all supported python versions:"
12638 msgid "2.4 (Ansible 2.3 only)"
12642 msgid "2.6"
12646 msgid "2.7"
12650 msgid "3.5"
12654 msgid "3.6"
12658 msgid "3.7"
12662 msgid "3.8"
12666 msgid "3.9"
12670 msgid "NOTE: In Ansible 2.4 and earlier the compile test was provided by a dedicated sub-command ``…
12674 msgid "Running compile tests locally"
12678 msgid "Compile tests can be run across the whole code base by doing:"
12683 msgid "Against a single file by doing:"
12688 msgid "Or against a specific Python version by doing:"
12692 msgid "For advanced usage see the help:"
12697 msgid "Installing dependencies"
12701 msgid "``ansible-test`` has a number of dependencies , for ``compile`` tests we suggest running the…
12705 msgid "The dependencies can be installed using the ``--requirements`` argument. For example:"
12709 msgid "The full list of requirements can be found at `test/lib/ansible_test/_data/requirements <htt…
12713 msgid "Extending compile tests"
12717 msgid "If you believe changes are needed to the compile tests please add a comment on the `Testing …
12721 msgid "Before you submit a module for inclusion in the main Ansible repo, you must test your module…
12725 msgid "To check the HTML output of your module documentation:"
12729 msgid "Ensure working :ref:`development environment <environment_setup>`."
12734 msgid "Install required Python packages (drop '--user' in venv/virtualenv):"
12738 msgid "Ensure your module is in the correct directory: ``lib/ansible/modules/$CATEGORY/mymodule.py`…
12742 msgid "Build HTML from your module documentation: ``MODULES=mymodule make webdocs``."
12746 msgid "To build the HTML documentation for multiple modules, use a comma-separated list of module n…
12750 msgid "View the HTML page at ``file:///path/to/docs/docsite/_build/html/modules/mymodule_module.htm…
12754 msgid "To ensure that your module documentation matches your ``argument_spec``:"
12758 msgid "run the ``validate-modules`` test::"
12762 msgid "httptester"
12766 msgid "``httptester`` is a docker container used to host certain resources required by :ref:`testin…
12770 msgid "HTTP Testing endpoint which provides the following capabilities:"
12774 msgid "httpbin"
12778 msgid "nginx"
12782 msgid "SSL"
12786 msgid "SNI"
12790 msgid "Negotiate Authentication"
12794 msgid "Source files can be found in the `http-test-container <https://github.com/ansible/http-test-…
12798 msgid "Extending httptester"
12802 msgid "If you have sometime to improve ``httptester`` please add a comment on the `Testing Working …
12806 msgid "The Ansible integration Test system."
12810 msgid "Tests for playbooks, by playbooks."
12814 msgid "Some tests may require credentials.  Credentials may be specified with `credentials.yml`."
12818 msgid "Some tests may require root."
12822 msgid "Quick Start"
12826 msgid "It is highly recommended that you install and activate the ``argcomplete`` python package. I…
12830 msgid "Configuration"
12834 msgid "ansible-test command"
12838 msgid "The example below assumes ``bin/`` is in your ``$PATH``. An easy way to achieve that is to i…
12842 msgid "You can also call ``ansible-test`` with the full path::"
12846 msgid "integration_config.yml"
12850 msgid "Making your own version of ``integration_config.yml`` can allow for setting some tunable par…
12854 msgid "Some tests assume things like hg, svn, and git are installed, and in path.  Some tests (such…
12858 msgid "(Complete list pending)"
12862 msgid "Non-destructive Tests"
12866 msgid "These tests will modify files in subdirectories, but will not do things that install or remo…
12870 msgid "Running integration tests within Docker"
12874 msgid "To protect your system from any potential changes caused by integration tests, and to ensure…
12878 msgid "Avoiding pulling new Docker images"
12882 msgid "Use the ``--docker-no-pull`` option to avoid pulling the latest container image. This is req…
12886 msgid "Run as follows for all POSIX platform tests executed by our CI system in a fedora32 docker c…
12890 msgid "You can target a specific tests as well, such as for individual modules::"
12894 msgid "You can use the ``-v`` option to make the output more verbose::"
12898 msgid "Use the following command to list all the available targets::"
12902 msgid "Bash users"
12906 msgid "If you use ``bash`` with ``argcomplete``, obtain a full list by doing: ``ansible-test integr…
12910 msgid "Destructive Tests"
12914 msgid "These tests are allowed to install and remove some trivial packages.  You will likely want t…
12918 msgid "Windows Tests"
12922 msgid "These tests exercise the ``winrm`` connection plugin and Windows modules.  You'll need to de…
12926 msgid "Running these tests may result in changes to your Windows host, so don't run them against a …
12930 msgid "Enable PowerShell Remoting (run on the Windows host via Remote Desktop)::"
12934 msgid "Define Windows inventory::"
12938 msgid "Run the Windows tests executed by our CI system::"
12942 msgid "Tests in Docker containers"
12946 msgid "If you have a Linux system with Docker installed, running integration tests using the same D…
12950 msgid "Docker on non-Linux"
12954 msgid "Using Docker Engine to run Docker on a non-Linux host (such as macOS) is not recommended. So…
12958 msgid "Running Integration Tests"
12962 msgid "To run all CI integration test targets for POSIX platforms in a Ubuntu 18.04 container::"
12966 msgid "You can also run specific tests or select a different Linux distribution. For example, to ru…
12970 msgid "Container Images"
12974 msgid "Python 2"
12978 msgid "Most container images are for testing with Python 2:"
12982 msgid "centos6"
12986 msgid "centos7"
12990 msgid "opensuse15py2"
12994 msgid "Python 3"
12998 msgid "To test with Python 3 use the following images:"
13002 msgid "alpine3"
13006 msgid "centos8"
13010 msgid "fedora32"
13014 msgid "fedora33"
13018 msgid "opensuse15"
13022 msgid "ubuntu1804"
13026 msgid "ubuntu2004"
13030 msgid "Legacy Cloud Tests"
13034 msgid "Some of the cloud tests run as normal integration tests, and others run as legacy tests; see…
13038 msgid "Other configuration for Cloud Tests"
13042 msgid "In order to run some tests, you must provide access credentials in a file named ``cloud-conf…
13047 msgid "IAM policies for AWS"
13051 msgid "Ansible needs fairly wide ranging powers to run the tests in an AWS account.  This rights ca…
13055 msgid "testing-policies"
13059 msgid "The GitHub repository `mattclay/aws-terminator <https://github.com/mattclay/aws-terminator/>…
13063 msgid "`ansible-integration-ci` will have the policies applied necessary to run any integration tes…
13067 msgid "`ansible-integration-unsupported` will have the additional policies applied necessary to run…
13071 msgid "Once the groups have been created, you'll need to create a user and make the user a member o…
13076 msgid "Other Definitions required"
13081 msgid "Apart from installing the policy and giving it to the user identity running the tests, a lam…
13085 msgid "Network Tests"
13089 msgid "For guidance on writing network test see :ref:`testing_resource_modules`."
13093 msgid "Where to find out more"
13097 msgid "If you'd like to know more about the plans for improving testing Ansible, join the `Testing …
13101 msgid "Testing using the Legacy Integration system"
13105 msgid "This page details how to run the integration tests that haven't been ported to the new ``ans…
13109 msgid "The following areas are still tested using the legacy ``make tests`` command:"
13113 msgid "amazon (some)"
13117 msgid "azure"
13121 msgid "cloudflare"
13125 msgid "cloudscale"
13129 msgid "cloudstack"
13133 msgid "consul"
13137 msgid "exoscale"
13141 msgid "gce"
13145 msgid "jenkins"
13149 msgid "rackspace"
13153 msgid "Over time the above list will be reduced as tests are ported to the ``ansible-test`` framewo…
13157 msgid "Running Cloud Tests"
13161 msgid "Cloud tests exercise capabilities of cloud modules (for example, ec2_key).  These are not 't…
13165 msgid "Some AWS tests may use environment variables. It is recommended to either unset any AWS envi…
13169 msgid "Subsets of tests may be run by ``#commenting`` out unnecessary roles in the appropriate play…
13173 msgid "In order to run cloud tests, you must provide access credentials in a file named ``credentia…
13177 msgid "Provide cloud credentials::"
13181 msgid "Other configuration"
13185 msgid "In order to run some tests, you must provide access credentials in a file named ``credential…
13189 msgid "In order to run the tests in an AWS account ansible needs fairly wide ranging powers which c…
13193 msgid "testing-iam-policy.json.j2"
13197 msgid "The testing-iam-policy.json.j2 file contains a policy which can be given to the user running…
13202 msgid "Running Tests"
13206 msgid "The tests are invoked via a ``Makefile``."
13210 msgid "If you haven't already got Ansible available use the local checkout by doing::"
13214 msgid "Run the tests by doing::"
13218 msgid "Possible cost of running cloud tests"
13222 msgid "Running cloud integration tests will create and destroy cloud resources. Running these tests…
13226 msgid "PEP 8"
13230 msgid "`PEP 8`_ style guidelines are enforced by `pycodestyle`_ on all python files in the reposito…
13234 msgid "Running Locally"
13238 msgid "The `PEP 8`_ check can be run locally with::"
13242 msgid "This document describes how to:"
13246 msgid "Run tests locally using ``ansible-test``"
13250 msgid "Extend"
13254 msgid "There are no special requirements for running ``ansible-test`` on Python 2.7 or later. The `…
13258 msgid "Test Environments"
13262 msgid "Most ``ansible-test`` commands support running in one or more isolated test environments to …
13266 msgid "Remote"
13270 msgid "The ``--remote`` option runs tests in a cloud hosted environment. An API key is required to …
13274 msgid "Recommended for integration tests."
13278 msgid "See the `list of supported platforms and versions <https://github.com/ansible/ansible/blob/d…
13282 msgid "Environment Variables"
13286 msgid "When using environment variables to manipulate tests there some limitations to keep in mind.…
13290 msgid "Not propagated from the host to the test environment when using the ``--docker`` or ``--remo…
13294 msgid "Not exposed to the test environment unless enabled in ``test/lib/ansible_test/_internal/util…
13298 msgid "Example: ``ANSIBLE_KEEP_REMOTE_FILES=1`` can be set when running ``ansible-test integration …
13302 msgid "Interactive Shell"
13306 msgid "Use the ``ansible-test shell`` command to get an interactive shell in the same environment u…
13310 msgid "``ansible-test shell --docker`` - Open a shell in the default docker container."
13314 msgid "``ansible-test shell --venv --python 3.6`` - Open a shell in a Python 3.6 virtual environmen…
13318 msgid "Code Coverage"
13322 msgid "Code coverage reports make it easy to identify untested code for which more tests should be …
13326 msgid "Add the ``--coverage`` option to any test command to collect code coverage data.  If you are…
13331 msgid "Reports can be generated in several different formats:"
13336 msgid "``ansible-test coverage report`` - Console report."
13341 msgid "``ansible-test coverage html`` - HTML report."
13346 msgid "``ansible-test coverage xml`` - XML report."
13350 msgid "To clear data between test runs, use the ``ansible-test coverage erase`` command. For a full…
13354 msgid "Sanity tests are made up of scripts and tools used to perform static code analysis. The prim…
13358 msgid "Tests are run with ``ansible-test sanity``. All available tests are run unless the ``--test`…
13362 msgid "How to run"
13366 msgid "To run sanity tests using docker, always use the default docker image by passing the ``--doc…
13370 msgid "When using docker and the ``--base-branch`` argument, also use the ``--docker-keep-git`` arg…
13375 msgid "Available Tests"
13379 msgid "Tests can be listed with ``ansible-test sanity --list-tests``."
13383 msgid "See the full list of :ref:`sanity tests <all_sanity_tests>`, which details the various tests…
13387 msgid "Unit Tests"
13391 msgid "Unit tests are small isolated tests that target a specific library or module.  Unit tests in…
13395 msgid "Unit tests can be found in `test/units <https://github.com/ansible/ansible/tree/devel/test/u…
13399 msgid "To run unit tests using docker, always use the default docker image by passing the ``--docke…
13403 msgid "The Ansible unit tests can be run across the whole code base by doing:"
13407 msgid "If you are running unit tests against things other than modules, such as module utilities, s…
13411 msgid "For advanced usage see the online help::"
13415 msgid "You can also run tests in Ansible's continuous integration system by opening a pull request.…
13419 msgid "If you are running ``ansible-test`` with the ``--docker`` or ``--venv`` option you do not ne…
13423 msgid "Otherwise you can install dependencies using the ``--requirements`` option, which will insta…
13427 msgid "The list of unit test requirements can be found at `test/units/requirements.txt <https://git…
13431 msgid "This does not include the list of unit test requirements for ``ansible-test`` itself, which …
13435 msgid "See also the `constraints <https://github.com/ansible/ansible/blob/devel/test/lib/ansible_te…
13439 msgid "Extending unit tests"
13443 msgid "What a unit test isn't"
13447 msgid "If you start writing a test that requires external services then you may be writing an integ…
13451 msgid "Structuring Unit Tests"
13455 msgid "Ansible drives unit tests through `pytest <https://docs.pytest.org/en/latest/>`_. This means…
13459 msgid "Here is an example of a function::"
13463 msgid "Here is an example of a class::"
13467 msgid "Both methods work fine in most circumstances; the function-based interface is simpler and qu…
13471 msgid "Assertions using the simple ``assert`` function inside the tests will give full information …
13475 msgid "A number of the unit test suites include functions that are shared between several modules, …
13479 msgid "Module test case common code"
13483 msgid "Keep common code as specific as possible within the `test/units/` directory structure. Don't…
13487 msgid "Don't import other unit tests from a unit test. Any common code should be in dedicated files…
13491 msgid "Fixtures files"
13495 msgid "To mock out fetching results from devices, or provide other complex data structures that com…
13499 msgid "You can check how `fixtures <https://github.com/ansible/ansible/tree/devel/test/units/module…
13503 msgid "If you are simulating APIs you may find that Python placebo is useful.  See :ref:`testing_un…
13507 msgid "Code Coverage For New or Updated Unit Tests"
13511 msgid "New code will be missing from the codecov.io coverage reports (see :ref:`developing_testing`…
13515 msgid "To collect coverage data add the ``--coverage`` argument to your ``ansible-test`` command li…
13519 msgid "Results will be written to ``test/results/reports/coverage/index.html``"
13523 msgid "To clear data between test runs, use the ``ansible-test coverage erase`` command.  See :ref:…
13527 msgid ":ref:`testing_units_modules`"
13531 msgid "Special considerations for unit testing modules"
13536 msgid ":ref:`testing_running_locally`"
13541 msgid "Running tests locally including gathering and reporting coverage data"
13546 msgid "`Python 3 documentation - 26.4. unittest — Unit testing framework <https://docs.python.org/3…
13551 msgid "The documentation of the unittest framework in python 3"
13556 msgid "`Python 2 documentation - 25.3. unittest — Unit testing framework <https://docs.python.org/3…
13561 msgid "The documentation of the earliest supported unittest framework - from Python 2.6"
13566 msgid "`pytest: helps you write better programs <https://docs.pytest.org/en/latest/>`_"
13571 msgid "The documentation of pytest - the framework actually used to run Ansible unit tests"
13575 msgid "Unit Testing Ansible Modules"
13579 msgid "This document explains why, how and when you should use unit tests for Ansible modules. The …
13583 msgid "What Are Unit Tests?"
13587 msgid "Ansible includes a set of unit tests in the :file:`test/units` directory. These tests primar…
13591 msgid "Integration tests can be used for most modules, but there are situations where cases cannot …
13595 msgid "Why Use Unit Tests?"
13599 msgid "Ansible unit tests have advantages and disadvantages. It is important to understand these. A…
13603 msgid "Most unit tests are much faster than most Ansible integration tests. The complete suite of u…
13607 msgid "Unit tests can be run by developers who don't have access to the system which the module is …
13611 msgid "Unit tests can easily substitute system functions allowing testing of software that would be…
13615 msgid "Unit tests are run on different Python versions. This allows us to ensure that the code beha…
13619 msgid "There are also some potential disadvantages of unit tests. Unit tests don't normally directl…
13623 msgid "Unit tests that test the internal, non-visible features of software may make refactoring dif…
13627 msgid "Even if the internal feature is working correctly it is possible that there will be a proble…
13631 msgid "Normally the Ansible integration tests (which are written in Ansible YAML) provide better te…
13635 msgid "When To Use Unit Tests"
13639 msgid "There are a number of situations where unit tests are a better choice than integration tests…
13643 msgid "Forcing rare / strange / random situations that can't be forced, such as specific network fa…
13647 msgid "Extensive testing of slow configuration APIs"
13651 msgid "Situations where the integration tests cannot be run as part of the main Ansible continuous …
13655 msgid "Providing quick feedback"
13659 msgid "A single step of the rds_instance test cases can take up to 20 minutes (the time to create a…
13663 msgid "The time saving provided by being able to run the code in a unit test makes it worth creatin…
13667 msgid "Ensuring correct use of external interfaces"
13671 msgid "Unit tests can check the way in which external services are run to ensure that they match sp…
13675 msgid "Package managers are often far more efficient when installing multiple packages at once rath…
13679 msgid "Another related use is in the situation where an API has versions which behave differently. …
13683 msgid "Providing specific design tests"
13687 msgid "By building a requirement for a particular part of the code and then coding to that requirem…
13691 msgid "Unit tests that test internal implementation details of code, on the other hand, almost alwa…
13695 msgid "How to unit test Ansible modules"
13699 msgid "There are a number of techniques for unit testing modules. Beware that most modules without …
13703 msgid "Naming unit tests"
13707 msgid "Unit tests should have logical names. If a developer working on the module being tested brea…
13711 msgid "As an example, ``test_v2_state_present_should_call_create_server_with_name()`` would be a go…
13715 msgid "Use of Mocks"
13719 msgid "Mock objects (from https://docs.python.org/3/library/unittest.mock.html) can be very useful …
13723 msgid "Ensuring failure cases are visible with mock objects"
13727 msgid "Functions like :meth:`module.fail_json` are normally expected to terminate execution. When y…
13731 msgid "This applies not only to calling the main module but almost any other function in a module w…
13735 msgid "Mocking of the actual module"
13739 msgid "The setup of an actual module is quite complex (see `Passing Arguments`_ below) and often is…
13743 msgid "API definition with unit test cases"
13747 msgid "API interaction is usually best tested with the function tests defined in Ansible's integrat…
13751 msgid "Defining a module against an API specification"
13755 msgid "This case is especially important for modules interacting with web services, which provide a…
13759 msgid "By writing a custom emulation of the calls that return data from the API, we can ensure that…
13763 msgid "*Example:  in rds_instance unit tests a simple instance state is defined*::"
13767 msgid "This is then used to create a list of states::"
13771 msgid "These states are then used as returns from a mock object to ensure that the ``await`` functi…
13775 msgid "By doing this we check that the ``await`` function will keep waiting through potentially unu…
13779 msgid "Defining a module to work against multiple API versions"
13783 msgid "This case is especially important for modules interacting with many different versions of so…
13787 msgid "By using previously stored data from various versions of an API we can ensure that the code …
13791 msgid "Ansible special cases for unit testing"
13795 msgid "There are a number of special cases for unit testing the environment of an Ansible module. T…
13799 msgid "Module argument processing"
13803 msgid "There are two problems with running the main function of a module:"
13807 msgid "Since the module is supposed to accept arguments on ``STDIN`` it is a bit difficult to set u…
13811 msgid "All modules should finish by calling either the :meth:`module.fail_json` or :meth:`module.ex…
13815 msgid "Passing Arguments"
13819 msgid "To pass arguments to a module correctly, use the ``set_module_args`` method which accepts a …
13823 msgid "Handling exit correctly"
13827 msgid "The :meth:`module.exit_json` function won't work properly in a testing environment since it …
13831 msgid "Now you can ensure that the first function called is the one you expected simply by testing …
13835 msgid "The same technique can be used to replace :meth:`module.fail_json` (which is used for failur…
13839 msgid "Running the main function"
13843 msgid "If you do want to run the actual main function of a module you must import the module, set t…
13847 msgid "Handling calls to external executables"
13851 msgid "Module must use :meth:`AnsibleModule.run_command` in order to execute an external command. T…
13855 msgid "Here is a simple mock of :meth:`AnsibleModule.run_command` (taken from :file:`test/units/mod…
13859 msgid "A Complete Example"
13863 msgid "The following example is a complete skeleton that reuses the mocks explained above and adds …
13867 msgid "Restructuring modules to enable testing module set up and other processes"
13871 msgid "Often modules have a ``main()`` function which sets up the module and then performs other ac…
13875 msgid "This now makes it possible to run tests against the module initiation function::"
13879 msgid "See also ``test/units/module_utils/aws/test_rds.py``"
13883 msgid "Note that the ``argument_spec`` dictionary is visible in a module variable. This has advanta…
13887 msgid "The same restructuring technique can be valuable for testing other functionality, such as th…
13891 msgid "Traps for maintaining Python 2 compatibility"
13895 msgid "If you use the ``mock`` library from the Python 2.6 standard library, a number of the assert…
13899 msgid "A helpful development approach to this should be to ensure that all of the tests have been r…
13903 msgid "Maintain Python 2.6 compatibility"
13907 msgid "Please remember that modules need to maintain compatibility with Python 2.6 so the unittests…
13911 msgid "Ansible unit tests documentation"
13915 msgid "Get started developing a module"
13919 msgid "`Testing Your Code (from The Hitchhiker's Guide to Python!) <https://docs.python-guide.org/w…
13923 msgid "General advice on testing Python code"
13927 msgid "`Uncle Bob's many videos on YouTube <https://www.youtube.com/watch?v=QedpQjxBPMA&list=PLlu0C…
13931 msgid "Unit testing is a part of the of various philosophies of software development, including Ext…
13935 msgid "`\"Why Most Unit Testing is Waste\" <https://rbcs-us.com/documents/Why-Most-Unit-Testing-is-…
13939 msgid "An article warning against the costs of unit testing"
13943 msgid "`'A Response to \"Why Most Unit Testing is Waste\"' <https://henrikwarne.com/2014/09/04/a-re…
13947 msgid "An response pointing to how to maintain the value of unit tests"
13951 msgid "Python program to help test or validate Ansible modules."
13955 msgid "``validate-modules`` is one of the ``ansible-test`` Sanity Tests, see :ref:`testing_sanity` …
13959 msgid "Originally developed by Matt Martz (@sivel)"
13963 msgid "Usage"
13967 msgid "Help"
13971 msgid "Extending validate-modules"
13975 msgid "The ``validate-modules`` tool has a `schema.py <https://github.com/ansible/ansible/blob/deve…
13979 msgid "Codes"
13983 msgid "**Error Code**"
13987 msgid "**Type**"
13991 msgid "**Level**"
13995 msgid "**Sample Message**"
13999 msgid "ansible-deprecated-version"
14072 msgid "Documentation"
14171 msgid "Error"
14175 msgid "A feature is deprecated and supposed to be removed in the current or an earlier Ansible vers…
14179 msgid "ansible-module-not-initialized"
14190 msgid "Syntax"
14194 msgid "Execution of the module did not result in initialization of AnsibleModule"
14198 msgid "collection-deprecated-version"
14202 msgid "A feature is deprecated and supposed to be removed in the current or an earlier collection v…
14206 msgid "deprecated-date"
14210 msgid "A date before today appears as ``removed_at_date`` or in ``deprecated_aliases``"
14214 msgid "deprecation-mismatch"
14218 msgid "Module marked as deprecated or removed in at least one of the filename, its metadata, or in …
14222 msgid "doc-choices-do-not-match-spec"
14226 msgid "Value for \"choices\" from the argument_spec does not match the documentation"
14230 msgid "doc-choices-incompatible-type"
14234 msgid "Choices value from the documentation is not compatible with type defined in the argument_spe…
14238 msgid "doc-default-does-not-match-spec"
14242 msgid "Value for \"default\" from the argument_spec does not match the documentation"
14246 msgid "doc-default-incompatible-type"
14250 msgid "Default value from the documentation is not compatible with type defined in the argument_spe…
14254 msgid "doc-elements-invalid"
14258 msgid "Documentation specifies elements for argument, when \"type\" is not ``list``."
14262 msgid "doc-elements-mismatch"
14266 msgid "Argument_spec defines elements different than documentation does"
14270 msgid "doc-missing-type"
14274 msgid "Documentation doesn't specify a type but argument in ``argument_spec`` use default type (``s…
14278 msgid "doc-required-mismatch"
14282 msgid "argument in argument_spec is required but documentation says it is not, or vice versa"
14286 msgid "doc-type-does-not-match-spec"
14290 msgid "Argument_spec defines type different than documentation does"
14294 msgid "documentation-error"
14298 msgid "Unknown ``DOCUMENTATION`` error"
14302 msgid "documentation-syntax-error"
14306 msgid "Invalid ``DOCUMENTATION`` schema"
14310 msgid "illegal-future-imports"
14327 msgid "Imports"
14331 msgid "Only the following ``from __future__`` imports are allowed: ``absolute_import``, ``division`…
14335 msgid "import-before-documentation"
14339 msgid "Import found before documentation variables. All imports must appear below ``DOCUMENTATION``…
14343 msgid "import-error"
14347 msgid "``Exception`` attempting to import module for ``argument_spec`` introspection"
14351 msgid "import-placement"
14355 msgid "Locations"
14364 msgid "Warning"
14369 msgid "Imports should be directly below ``DOCUMENTATION``/``EXAMPLES``/``RETURN``"
14373 msgid "imports-improper-location"
14377 msgid "incompatible-choices"
14381 msgid "Choices value from the argument_spec is not compatible with type defined in the argument_spe…
14385 msgid "incompatible-default-type"
14389 msgid "Default value from the argument_spec is not compatible with type defined in the argument_spe…
14393 msgid "invalid-argument-name"
14397 msgid "Argument in argument_spec must not be one of 'message', 'syslog_facility' as it is used inte…
14401 msgid "invalid-argument-spec"
14405 msgid "Argument in argument_spec must be a dictionary/hash when used"
14409 msgid "invalid-argument-spec-options"
14413 msgid "Suboptions in argument_spec are invalid"
14417 msgid "invalid-documentation"
14421 msgid "``DOCUMENTATION`` is not valid YAML"
14425 msgid "invalid-documentation-options"
14429 msgid "``DOCUMENTATION.options`` must be a dictionary/hash when used"
14433 msgid "invalid-examples"
14437 msgid "``EXAMPLES`` is not valid YAML"
14441 msgid "invalid-extension"
14445 msgid "Official Ansible modules must have a ``.py`` extension for python modules or a ``.ps1`` for …
14449 msgid "invalid-module-schema"
14453 msgid "``AnsibleModule`` schema validation error"
14457 msgid "invalid-removal-version"
14461 msgid "The version at which a feature is supposed to be removed cannot be parsed (for collections, …
14465 msgid "invalid-requires-extension"
14469 msgid "Module ``#AnsibleRequires -CSharpUtil`` should not end in .cs, Module ``#Requires`` should n…
14473 msgid "last-line-main-call"
14477 msgid "Call to ``main()`` not the last line (or ``removed_module()`` in the case of deprecated & do…
14481 msgid "missing-doc-fragment"
14485 msgid "``DOCUMENTATION`` fragment missing"
14489 msgid "missing-existing-doc-fragment"
14493 msgid "Pre-existing ``DOCUMENTATION`` fragment missing"
14497 msgid "missing-documentation"
14501 msgid "No ``DOCUMENTATION`` provided"
14505 msgid "missing-examples"
14509 msgid "No ``EXAMPLES`` provided"
14513 msgid "missing-gplv3-license"
14517 msgid "GPLv3 license header not found"
14521 msgid "missing-if-name-main"
14525 msgid "Next to last line is not ``if __name__ == \"__main__\":``"
14529 msgid "missing-main-call"
14533 msgid "Did not find a call to ``main()`` (or ``removed_module()`` in the case of deprecated & docs …
14537 msgid "missing-module-utils-basic-import"
14541 msgid "Did not find ``ansible.module_utils.basic`` import"
14545 msgid "missing-module-utils-import-csharp-requirements"
14549 msgid "No ``Ansible.ModuleUtils`` or C# Ansible util requirements/imports found"
14553 msgid "missing-powershell-interpreter"
14557 msgid "Interpreter line is not ``#!powershell``"
14561 msgid "missing-python-doc"
14565 msgid "Missing python documentation file"
14569 msgid "missing-python-interpreter"
14573 msgid "Interpreter line is not ``#!/usr/bin/python``"
14577 msgid "missing-return"
14581 msgid "No ``RETURN`` documentation provided"
14585 msgid "missing-return-legacy"
14589 msgid "No ``RETURN`` documentation provided for legacy module"
14593 msgid "missing-suboption-docs"
14597 msgid "Argument in argument_spec has sub-options but documentation does not define sub-options"
14601 msgid "module-incorrect-version-added"
14605 msgid "Module level ``version_added`` is incorrect"
14609 msgid "module-invalid-version-added"
14613 msgid "Module level ``version_added`` is not a valid version number"
14617 msgid "module-utils-specific-import"
14621 msgid "``module_utils`` imports should import specific components, not ``*``"
14625 msgid "multiple-utils-per-requires"
14629 msgid "``Ansible.ModuleUtils`` requirements do not support multiple modules per statement"
14633 msgid "multiple-csharp-utils-per-requires"
14637 msgid "Ansible C# util requirements do not support multiple utils per statement"
14641 msgid "no-default-for-required-parameter"
14645 msgid "Option is marked as required but specifies a default. Arguments with a default should not be…
14649 msgid "no-log-needed"
14657 msgid "Parameters"
14661 msgid "Option name suggests that the option contains a secret value, while ``no_log`` is not specif…
14665 msgid "nonexistent-parameter-documented"
14669 msgid "Argument is listed in DOCUMENTATION.options, but not accepted by the module"
14673 msgid "option-incorrect-version-added"
14677 msgid "``version_added`` for new option is incorrect"
14681 msgid "option-invalid-version-added"
14685 msgid "``version_added`` for option is not a valid version number"
14689 msgid "parameter-invalid"
14693 msgid "Argument in argument_spec is not a valid python identifier"
14697 msgid "parameter-invalid-elements"
14701 msgid "Value for \"elements\" is valid only when value of \"type\" is ``list``"
14705 msgid "implied-parameter-type-mismatch"
14709 msgid "Argument_spec implies ``type=\"str\"`` but documentation defines it as different data type"
14713 msgid "parameter-type-not-in-doc"
14717 msgid "Type value is defined in ``argument_spec`` but documentation doesn't specify a type"
14721 msgid "parameter-alias-repeated"
14725 msgid "argument in argument_spec has at least one alias specified multiple times in aliases"
14729 msgid "parameter-alias-self"
14733 msgid "argument in argument_spec is specified as its own alias"
14737 msgid "parameter-documented-multiple-times"
14741 msgid "argument in argument_spec with aliases is documented multiple times"
14745 msgid "parameter-list-no-elements"
14749 msgid "argument in argument_spec \"type\" is specified as ``list`` without defining \"elements\""
14753 msgid "parameter-state-invalid-choice"
14757 msgid "Argument ``state`` includes ``get``, ``list`` or ``info`` as a choice.  Functionality should…
14761 msgid "python-syntax-error"
14765 msgid "Python ``SyntaxError`` while parsing module"
14769 msgid "removal-version-must-be-major"
14773 msgid "According to the semantic versioning specification (https://semver.org/), the only versions …
14777 msgid "return-syntax-error"
14781 msgid "``RETURN`` is not valid YAML, ``RETURN`` fragments missing  or invalid"
14785 msgid "return-invalid-version-added"
14789 msgid "``version_added`` for return value is not a valid version number"
14793 msgid "subdirectory-missing-init"
14797 msgid "Ansible module subdirectories must contain an ``__init__.py``"
14801 msgid "try-except-missing-has"
14805 msgid "Try/Except ``HAS_`` expression missing"
14809 msgid "undocumented-parameter"
14813 msgid "Argument is listed in the argument_spec, but not documented in the module"
14817 msgid "unidiomatic-typecheck"
14821 msgid "Type comparison using ``type()`` found. Use ``isinstance()`` instead"
14825 msgid "unknown-doc-fragment"
14829 msgid "Unknown pre-existing ``DOCUMENTATION`` error"
14833 msgid "use-boto3"
14837 msgid "``boto`` import found, new modules should use ``boto3``"
14841 msgid "use-fail-json-not-sys-exit"
14845 msgid "``sys.exit()`` call found. Should be ``exit_json``/``fail_json``"
14849 msgid "use-module-utils-urls"
14853 msgid "``requests`` import found, should use ``ansible.module_utils.urls`` instead"
14857 msgid "use-run-command-not-os-call"
14861 msgid "``os.call`` used instead of ``module.run_command``"
14865 msgid "use-run-command-not-popen"
14869 msgid "``subprocess.Popen`` used instead of ``module.run_command``"
14873 msgid "use-short-gplv3-license"
14877 msgid "GPLv3 license header should be the :ref:`short form <copyright>` for new modules"
14881 msgid "mutually_exclusive-type"
14885 msgid "mutually_exclusive entry contains non-string value"
14889 msgid "mutually_exclusive-collision"
14893 msgid "mutually_exclusive entry has repeated terms"
14897 msgid "mutually_exclusive-unknown"
14901 msgid "mutually_exclusive entry contains option which does not appear in argument_spec (potentially…
14905 msgid "required_one_of-type"
14909 msgid "required_one_of entry contains non-string value"
14913 msgid "required_one_of-collision"
14917 msgid "required_one_of entry has repeated terms"
14921 msgid "required_one_of-unknown"
14925 msgid "required_one_of entry contains option which does not appear in argument_spec (potentially an…
14929 msgid "required_together-type"
14933 msgid "required_together entry contains non-string value"
14937 msgid "required_together-collision"
14941 msgid "required_together entry has repeated terms"
14945 msgid "required_together-unknown"
14949 msgid "required_together entry contains option which does not appear in argument_spec (potentially …
14953 msgid "required_if-is_one_of-type"
14957 msgid "required_if entry has a fourth value which is not a bool"
14961 msgid "required_if-requirements-type"
14965 msgid "required_if entry has a third value (requirements) which is not a list or tuple"
14969 msgid "required_if-requirements-collision"
14973 msgid "required_if entry has repeated terms in requirements"
14977 msgid "required_if-requirements-unknown"
14981 msgid "required_if entry's requirements contains option which does not appear in argument_spec (pot…
14985 msgid "required_if-unknown-key"
14989 msgid "required_if entry's key does not appear in argument_spec (potentially an alias of an option?…
14993 msgid "required_if-key-in-requirements"
14997 msgid "required_if entry contains its key in requirements list/tuple"
15001 msgid "required_if-value-type"
15005 msgid "required_if entry's value is not of the type specified for its key"
15009 msgid "required_by-collision"
15013 msgid "required_by entry has repeated terms"
15017 msgid "required_by-unknown"
15021 msgid "required_by entry contains option which does not appear in argument_spec (potentially an ali…
15025 msgid "version-added-must-be-major-or-minor"
15029 msgid "According to the semantic versioning specification (https://semver.org/), the only versions …
15032 #~ msgid "All Python imports in ``lib/ansible/modules/`` and ``lib/ansible/module_utils/`` which ar…
15035 #~ msgid "Collections are a distribution format for Ansible content. You can use collections to pac…
15038 #~ msgid "For details on how to *use* collections see :ref:`collections`."
15041 #~ msgid "For the current development status of Collections and FAQ see `Ansible Collections Overvi…
15044 #~ msgid "Create a collection skeleton with the ``collection init`` command. See :ref:`creating_col…
15047 #~ msgid "You can publish collections to Galaxy using the ``ansible-galaxy collection publish`` com…
15050 #~ msgid "Once you upload a version of a collection, you cannot delete or modify that version. Ensu…
15053 #~ msgid "To upload your collection to Galaxy, you must first obtain an API token (``--token`` in t…
15056 #~ msgid "Storing or using your API token"
15059 #~ msgid "When uploading collections it doesn't matter which namespace you select. The collection w…
15062 #~ msgid "BOTMETA.yml"
15065 #~ msgid "We assume that you have included ``~/dev/ansible/collections/`` in :ref:`COLLECTIONS_PATH…
15068 #~ msgid "For collections hosted in the ``ansible_collections`` GitHub org, create a branch and com…
15071 #~ msgid "We recommend that you use the `antsibull-changelog <https://github.com/ansible-community/…
15074 #~ msgid "Porting Guide entries"
15077 #~ msgid "The following changelog fragment categories are consumed by the Ansible changelog generat…
15080 #~ msgid ":ref:`collections_galaxy_meta`"
15083 #~ msgid "Understand the collections metadata structure."
15086 #~ msgid "When called with the argument ``--host <hostname>`` (where <hostname> is a host from abov…
15089 #~ msgid "`Ansible Tower <https://www.ansible.com/products/tower>`_"
15092 #~ msgid "``L()`` for links with a heading. For example: ``See L(Ansible Tower,https://www.ansible.…
15095 #~ msgid "``removed_in_version`` indicates which version of ansible-base or a collection a deprecat…
15098 #~ msgid "``removed_at_date`` indicates that a deprecated argument will be removed in a minor ansib…
15101 #~ msgid "If a module matures, we will remove the 'preview' mark in the documentation. We support (…
15104 #~ msgid "When a module has been deprecated for four release cycles, we remove the code and mark th…
15107 #~ msgid "Deprecating modules"
15110 #~ msgid "Mention the deprecation in the relevant ``CHANGELOG``."
15113 #~ msgid "note: with the advent of collections and ``routing.yml`` we might soon require another en…
15116 #~ msgid "Changing a module name"
15119 #~ msgid "If the underlying ``describe_some_resources`` API call throws a ``ResourceNotFound`` exce…
15122 #~ msgid "To handle authorization failures or parameter validation errors in ``describe_some_resour…
15125 #~ msgid "Ansible Tower®"
15128 #~ msgid "fedora28"
15131 #~ msgid "ubuntu1404"
15134 #~ msgid "ubuntu1604"
15137 #~ msgid "`irc.freenode.net <http://irc.freenode.net>`_"
15140 #~ msgid "Please make sure your module meets these requirements before you submit your PR/proposal.…