msgid "A key component of an Ansible collection is the ``galaxy.yml`` file placed in the root directory of a collection. This file contains the metadata of the collection that is used to generate a collection artifact."
msgid "May only contain alphanumeric lowercase characters and underscores. Namespaces cannot start with underscores or numbers and cannot contain consecutive underscores."
msgid "Ansible modules are put together as a zip file consisting of the module file and the various Python module boilerplate inside of a wrapper script. To see what is actually happening in the module, you need to extract the file from the wrapper. The wrapper script provides helper methods that let you do that."
msgstr "Ansible モジュールは、モジュールファイルとラッパースクリプト内のさまざまな Python モジュールボイラープレートで構成される zip ファイルとしてまとめて置かれます。モジュールで実際に何が発生しているかを確認するには、ラッパーからファイルを抽出する必要があります。ラッパースクリプトは、これを可能にするヘルパーメソッドを提供します。"
#: ../../rst/dev_guide/debugging.rst:17
msgid "The following steps use ``localhost`` as the target host, but you can use the same steps to debug against remote hosts as well. For a simpler approach to debugging without using the temporary files, see :ref:`simple debugging <simple_debugging>`."
msgid "Set :envvar:`ANSIBLE_KEEP_REMOTE_FILES` to ``1`` on the control host so Ansible will keep the remote module files instead of deleting them after the module finishes executing. Use the ``-vvv`` option to make Ansible more verbose. This will display the file name of the temporary module file."
msgid "Navigate to the temporary directory from the previous step. If the previous command was run against a remote host, connect to that host first before trying to navigate to the temporary directory."
msgid "If you want to examine the wrapper file you can. It will show a small Python script with a large base64 encoded string. The string contains the module to execute."
msgid "When you look into the temporary directory you'll see a structure like this:"
msgstr "一時ディレクトリーを確認すると、以下のような構造が表示されます。"
#: ../../rst/dev_guide/debugging.rst:80
msgid "``AnsiballZ_ping.py`` is the Python script with the module code stored in a base64 encoded string. It contains various helper functions for executing the module."
msgid "``ping.py`` is the code for the module itself. You can modify this code to see what effect it would have on your module, or for debugging purposes."
msgid "The ``args`` file contains a JSON string. The string is a dictionary containing the module arguments and other variables that Ansible passes into the module to change its behavior. Modify this file to change the parameters passed to the module."
msgid "The ``ansible`` directory contains the module code in ``modules`` as well as code from :mod:`ansible.module_utils` that is used by the module. Ansible includes files for any :mod:`ansible.module_utils` imports in the module but not any files from any other module. If your module uses :mod:`ansible.module_utils.url` Ansible will include it for you. But if your module includes `requests <https://requests.readthedocs.io/en/master/api/>`_, then you'll have to make sure that the Python `requests library <https://pypi.org/project/requests/>`_ is installed on the system before running the module."
msgid "You can modify files in this directory if you suspect that the module is having a problem in some of this boilerplate code rather than in the module code you have written."
msgid "This subcommand inserts the absolute path to ``debug_dir`` as the first item in ``sys.path`` and invokes the script using the arguments in the ``args`` file. You can continue to run the module like this until you understand the problem. Then you can copy the changes back into your real module file and test that the real module works via ``ansible`` or ``ansible-playbook``."
msgid "The easiest way to run a debugger in a module, either local or remote, is to use `epdb <https://pypi.org/project/epdb/>`_. Add ``import epdb; epdb.serve()`` in the module code on the control node at the desired break point. To connect to the debugger, run ``epdb.connect()``. See the `epdb documentation <https://pypi.org/project/epdb/>`_ for how to specify the ``host`` and ``port``. If connecting to a remote node, make sure to use a port that is allowed by any firewall between the control node and the remote node."
msgid "Since ``print()`` statements do not work inside modules, raising an exception is a good approach if you just want to see some specific data. Put ``raise Exception(some_value)`` somewhere in the module and run it normally. Ansible will handle this exception, pass the message back to the control node, and display it."
msgid "This API is intended for internal Ansible use. Ansible may make changes to this API at any time that could break backward compatibility with older versions of the API. Because of this, external use is not supported by Ansible. If you want to use Python API only for executing playbooks or modules, consider `ansible-runner <https://ansible-runner.readthedocs.io/en/latest/>`_ first."
msgstr "この API は、内部 Ansible の使用を目的としています。Ansible は、古いバージョンの API との後方互換性を妨げる可能性がある時点でこの API に変更を加える可能性があるため、Ansible では外部の使用はサポートされません。Playbook またはモジュールの実行のみに Python API を使用する場合は、まず `ansible-runner <https://ansible-runner.readthedocs.io/en/latest/>`_ を考慮してください。"
#: ../../rst/dev_guide/developing_api.rst:11
msgid "There are several ways to use Ansible from an API perspective. You can use the Ansible Python API to control nodes, you can extend Ansible to respond to various Python events, you can write plugins, and you can plug in inventory data from external data sources. This document gives a basic overview and examples of the Ansible execution and playbook API."
msgstr "API パースペクティブから Ansible を使用する方法は複数あります。Ansible Python API を使用してノードを制御し、Ansible を拡張してさまざまな Python イベントに応答でき、プラグインを作成したり、外部データソースからのインベントリーデータへのプラグインを行うことができます。本書では、Ansible の実行および Playbook API の基本的な概要と例を紹介します。"
#: ../../rst/dev_guide/developing_api.rst:16
msgid "If you would like to use Ansible programmatically from a language other than Python, trigger events asynchronously, or have access control and logging demands, please see the `Ansible Tower documentation <https://docs.ansible.com/ansible-tower/>`_."
msgid "The source code for the ``ansible`` command line tools (``lib/ansible/cli/``) is `available on GitHub <https://github.com/ansible/ansible/tree/devel/lib/ansible/cli>`_."
msgid "Collections are a distribution format for Ansible content. You can use collections to package and distribute playbooks, roles, modules, and plugins. You can publish and use collections through `Ansible Galaxy <https://galaxy.ansible.com>`_."
msgid "For the current development status of Collections and FAQ see `Ansible Collections Overview and FAQ <https://github.com/ansible-collections/overview/blob/main/README.rst>`_."
msgstr "コレクションおよび FAQ の現在の開発ステータスは、「`Ansible Collections Overview and FAQ <https://github.com/ansible-collections/overview/blob/main/README.rst>`_」を参照してください。"
msgid "Collections follow a simple data structure. None of the directories are required unless you have specific content that belongs in one of them. A collection does require a ``galaxy.yml`` file at the root level of the collection. This file contains all of the metadata that Galaxy and other tools need in order to package, build and publish the collection::"
msgid "A collection must have a ``galaxy.yml`` file that contains the necessary information to build a collection artifact. See :ref:`collections_galaxy_meta` for details."
msgid "Put general documentation for the collection here. Keep the specific documentation for plugins and modules embedded as Python docstrings. Use the ``docs`` folder to describe how to use the roles and plugins the collection provides, role requirements, and so on. Use markdown and do not add subfolders."
msgid "The ``ansible-doc`` command requires the fully qualified collection name (FQCN) to display specific plugin documentation. In this example, ``my_namespace`` is the Galaxy namespace and ``my_collection`` is the collection name within that namespace."
msgid "The Galaxy namespace of an Ansible collection is defined in the ``galaxy.yml`` file. It can be different from the GitHub organization or repository name."
msgid "Add a 'per plugin type' specific subdirectory here, including ``module_utils`` which is usable not only by modules, but by most plugins by using their FQCN. This is a way to distribute modules, lookups, filters, and so on without having to import a role in every play."
msgid "Vars plugins are unsupported in collections. Cache plugins may be used in collections for fact caching, but are not supported for inventory plugins."
msgid "When coding with ``module_utils`` in a collection, the Python ``import`` statement needs to take into account the FQCN along with the ``ansible_collections`` convention. The resulting Python import will look like ``from ansible_collections.{namespace}.{collection}.plugins.module_utils.{util} import {something}``"
msgid "The following example snippets show a Python and PowerShell module using both default Ansible ``module_utils`` and those provided by a collection. In this example the namespace is ``community``, the collection is ``test_collection``. In the Python example the ``module_util`` in question is called ``qradar`` such that the FQCN is ``community.test_collection.plugins.module_utils.qradar``:"
msgid "In the PowerShell example the ``module_util`` in question is called ``hyperv`` such that the FQCN is ``community.test_collection.plugins.module_utils.hyperv``:"
msgid "Roles in a collection cannot contain plugins any more. Plugins must live in the collection ``plugins`` directory tree. Each plugin is accessible to all roles in the collection."
msgid "The directory name of the role is used as the role name. Therefore, the directory name must comply with the above role name rules. The collection import into Galaxy will fail if a role name does not comply with these rules."
msgid "You can migrate 'traditional roles' into a collection but they must follow the rules above. You may need to rename roles if they don't conform. You will have to move or link any role-based plugins to the collection specific directories."
msgid "For roles imported into Galaxy directly from a GitHub repository, setting the ``role_name`` value in the role's metadata overrides the role name used by Galaxy. For collections, that value is ignored. When importing a collection, Galaxy uses the role directory as the name of the role and ignores the ``role_name`` metadata value."
msgid "Ansible Collections are tested much like Ansible itself, by using the `ansible-test` utility which is released as part of Ansible, version 2.9.0 and newer. Because Ansible Collections are tested using the same tooling as Ansible itself, via `ansible-test`, all Ansible developer documentation for testing is applicable for authoring Collections Tests with one key concept to keep in mind."
msgid "When reading the :ref:`developing_testing` documentation, there will be content that applies to running Ansible from source code via a git clone, which is typical of an Ansible developer. However, it's not always typical for an Ansible Collection author to be running Ansible from source but instead from a stable release, and to create Collections it is not necessary to run Ansible from source. Therefore, when references of dealing with `ansible-test` binary paths, command completion, or environment variables are presented throughout the :ref:`developing_testing` documentation; keep in mind that it is not needed for Ansible Collection Testing because the act of installing the stable release of Ansible containing `ansible-test` is expected to setup those things for you."
msgid "A collection can store some additional metadata in a ``runtime.yml`` file in the collection's ``meta`` directory. The ``runtime.yml`` file supports the top level keys:"
msgid "although the version is a `PEP440 Version Specifier <https://www.python.org/dev/peps/pep-0440/#version-specifiers>`_ under the hood, Ansible deviates from PEP440 behavior by truncating prerelease segments from the Ansible version. This means that Ansible 2.11.0b1 is compatible with something that ``requires_ansible: \">=2.11\"``."
msgid "Content in a collection that Ansible needs to load from another location or that has been deprecated/removed. The top level keys of ``plugin_routing`` are types of plugins, with individual plugin names as subkeys. To define a new location for a plugin, set the ``redirect`` field to another name. To deprecate a plugin, use the ``deprecation`` field to provide a custom warning message and the removal version or date. If the plugin has been renamed or moved to a new location, the ``redirect`` field should also be provided. If a plugin is being removed entirely, ``tombstone`` can be used for the fatal error message and removal version or date."
msgid "Both the namespace and collection names use the same strict set of requirements. See `Galaxy namespaces <https://galaxy.ansible.com/docs/contributing/namespaces.html#galaxy-namespaces>`_ on the Galaxy docsite for those requirements."
msgid "Once the skeleton exists, you can populate the directories with the content you want inside the collection. See `ansible-collections <https://github.com/ansible-collections/>`_ GitHub Org to get a better idea of what you can place inside a collection."
msgid ":ref:`module_docs_fragments` covers the basics for documentation fragments. The `kubernetes <https://github.com/ansible-collections/kubernetes>`_ collection includes a complete example."
msgid "Certain files and folders are excluded when building the collection artifact. See :ref:`ignoring_files_and_folders_collections` to exclude other files you would not want to distribute."
msgid "If you used the now-deprecated ``Mazer`` tool for any of your collections, delete any and all files it added to your :file:`releases/` directory before you build your collection with ``ansible-galaxy``."
msgid "This tarball is mainly intended to upload to Galaxy as a distribution method, but you can use it directly to install the collection on target systems."
msgid "To exclude other files and folders when building the collection, you can set a list of file glob-like patterns in the ``build_ignore`` key in the collection's ``galaxy.yml`` file. These patterns use the following special characters for wildcard matching:"
msgid "For example, if you wanted to exclude the :file:`sensitive` folder within the ``playbooks`` folder as well any ``.tar.gz`` archives you can set the following in your ``galaxy.yml`` file:"
msgid "You can try your collection locally by installing it from the tarball. The following will enable an adjacent playbook to access the collection:"
msgid "You should use one of the values configured in :ref:`COLLECTIONS_PATHS` for your path. This is also where Ansible itself will expect to find collections when attempting to use them. If you don't specify a path value, ``ansible-galaxy collection install`` installs the collection in the first path defined in :ref:`COLLECTIONS_PATHS`, which by default is ``~/.ansible/collections``."
msgid "You can install a collection in a git repository by providing the URI to the repository instead of a collection name or path to a ``tar.gz`` file. The collection must contain a ``galaxy.yml`` or ``MANIFEST.json`` file, which will be used to generate the would-be collection artifact data from the directory. The URI should be prefixed with ``git+`` (or with ``git@`` to use a private repository with ssh authentication) and optionally supports a comma-separated `git commit-ish <https://git-scm.com/docs/gitglossary#def_commit-ish>`_ version (for example, a commit or tag)."
msgid "Embedding credentials into a git URI is not secure. Make sure to use safe auth options for security reasons. For example, use `SSH <https://help.github.com/en/github/authenticating-to-github/connecting-to-github-with-ssh>`_, `netrc <https://linux.die.net/man/5/netrc>`_ or `http.extraHeader <https://git-scm.com/docs/git-config#Documentation/git-config.txt-httpextraHeader>`_/`url.<base>.pushInsteadOf <https://git-scm.com/docs/git-config#Documentation/git-config.txt-urlltbasegtpushInsteadOf>`_ in Git config to prevent your creds from being exposed in logs."
msgid "In a ``requirements.yml`` file, you can also use the ``type`` and ``version`` keys in addition to using the ``git+repo,version`` syntax for the collection name."
msgid "Git repositories can be used for collection dependencies as well. This can be helpful for local development and testing but built/published artifacts should only have dependencies on other artifacts."
msgid "The first is the ``galaxy.yml`` or ``MANIFEST.json`` file in the top level of the repository path. If the file exists it's used as the collection metadata and the individual collection will be installed."
msgid "The second is a ``galaxy.yml`` or ``MANIFEST.json`` file in each directory in the repository path (one level deep). In this scenario, each directory with a metadata file is installed as a collection."
msgid "If you have a different repository structure or only want to install a subset of collections, you can add a fragment to the end of your URI (before the optional comma-separated version) to indicate which path ansible-galaxy should inspect for metadata file(s). The path should be a directory to a collection or multiple collections (rather than the path to a ``galaxy.yml`` file or ``MANIFEST.json`` file)."
msgid "You can publish collections to Galaxy using the ``ansible-galaxy collection publish`` command or the Galaxy UI itself. You need a namespace on Galaxy to upload your collection. See `Galaxy namespaces <https://galaxy.ansible.com/docs/contributing/namespaces.html#galaxy-namespaces>`_ on the Galaxy docsite for details."
msgid "To upload your collection to Galaxy, you must first obtain an API token (``--token`` in the ``ansible-galaxy`` CLI command or ``token`` in the :file:`ansible.cfg` file under the ``galaxy_server`` section). The API token is a secret token used to protect your content."
msgid "You can use the ``--token`` argument with the ``ansible-galaxy`` command (in conjunction with the ``--server`` argument or :ref:`GALAXY_SERVER` setting in your :file:`ansible.cfg` file). You cannot use ``apt-key`` with any servers defined in your :ref:`Galaxy server list <galaxy_server_config>`."
msgid "With this option, you configure one or more servers for Galaxy in your :file:`ansible.cfg` file under the ``galaxy_server_list`` section. For each server, you also configure the token."
msgid "By default, ``ansible-galaxy`` uses https://galaxy.ansible.com as the Galaxy server (as listed in the :file:`ansible.cfg` file under :ref:`galaxy_server`). If you are only publishing your collection to Ansible Galaxy, you do not need any further configuration. If you are using Red Hat Automation Hub or any other Galaxy server, see :ref:`Configuring the ansible-galaxy client <galaxy_server_config>`."
msgid "The above command assumes you have retrieved and stored your API token as part of a Galaxy server list. See :ref:`galaxy_get_token` for details."
msgid "The ``ansible-galaxy collection publish`` command triggers an import process, just as if you uploaded the collection through the Galaxy website. The command waits until the import process completes before reporting the status back. If you want to continue without waiting for the import result, use the ``--no-wait`` argument and manually look at the import progress in your `My Imports <https://galaxy.ansible.com/my-imports/>`_ page."
msgid "Go to the `My Content <https://galaxy.ansible.com/my-content/namespaces>`_ page, and click the **Add Content** button on one of your namespaces."
msgid "When uploading collections it doesn't matter which namespace you select. The collection will be uploaded to the namespace specified in the collection metadata in the ``galaxy.yml`` file. If you're not an owner of the namespace, the upload request will fail."
msgid "Once Galaxy uploads and accepts a collection, you will be redirected to the **My Imports** page, which displays output from the import process, including any errors or warnings about the metadata and content contained in the collection."
msgid "Once you upload a version of a collection, you cannot delete or modify that version. Ensure that everything looks okay before uploading. The only way to change a collection is to release a new version. The latest version of a collection (by highest version number) will be the version displayed everywhere in Galaxy; however, users will still be able to download older versions."
msgid "Collection versions use `Semantic Versioning <https://semver.org/>`_ for version numbers. Please read the official documentation for details and examples. In summary:"
msgid "Increment minor (for example: y in `x.y.z`) version number for new functionality in a backwards compatible manner (for example new modules/plugins, parameters, return values)."
msgid "To migrate content from one collection to another, if the collections are parts of `Ansible distribution <https://github.com/ansible-community/ansible-build-data/blob/main/2.10/ansible.in>`_:"
msgid "Deprecate the module/plugin with ``removal_version`` scheduled for the next major version in ``meta/runtime.yml`` of the old collection. The deprecation must be released after the copied content has been included in a release of the new collection."
msgid "remove the symlink stored in ``plugin/modules`` directory if appropriate (mainly when removing from ``community.general`` and ``community.network``)"
msgid "add a changelog fragment containing entries for ``removed_features`` and ``breaking_changes``; you can see an example of a changelog fragment in this `pull request <https://github.com/ansible-collections/community.general/pull/1304>`_"
msgid "remove changelog fragments for removed content that are not yet part of the changelog (in other words, do not modify `changelogs/changelog.yaml` and do not delete files mentioned in it)"
msgid "Create a PR against the source collection repository to remove the modules, module_utils, plugins, and docs_fragments related to this migration:"
msgid "Maintainers for the old collection have to make sure that the PR is merged in a way that it does not break user experience and semantic versioning:"
msgid "A new version containing the merged PR must not be released before the collection the content has been moved to has been released again, with that content contained in it. Otherwise the redirects cannot work and users relying on that content will experience breakage."
msgid "Once 1.0.0 of the collection from which the content has been removed has been released, such PRs can only be merged for a new **major** version (in other words, 2.0.0, 3.0.0, and so on)."
msgid "The ``BOTMETA.yml``, for example in `community.general collection repository <https://github.com/ansible-collections/community.general/blob/main/.github/BOTMETA.yml>`_, is the source of truth for:"
msgid "Ansibulbot will know how to redirect existing issues and PRs to the new repo. The build process for docs.ansible.com will know where to find the module docs."
msgid "The ``migrated_to:`` key must be added explicitly for every *file*. You cannot add ``migrated_to`` at the directory level. This is to allow module and plugin webdocs to be redirected to the new collection docs."
msgstr "``migrated_to:`` キーは、*ファイル* ごとに明示的に追加する必要があります。ディレクトリーレベルで ``migrated_to`` を追加することはできません。モジュールとプラグインの Web ドキュメントを新しいコレクションにリダイレクトすることです。"
msgid "The main tool for testing collections is ``ansible-test``, Ansible's testing tool described in :ref:`developing_testing`. You can run several compile and sanity checks, as well as run unit and integration tests for plugins using ``ansible-test``. When you test collections, test against the ansible-base version(s) you are targeting."
msgid "You must always execute ``ansible-test`` from the root directory of a collection. You can run ``ansible-test`` in Docker containers without installing any special requirements. The Ansible team uses this approach in Shippable both in the ansible/ansible GitHub repository and in the large community collections such as `community.general <https://github.com/ansible-collections/community.general/>`_ and `community.network <https://github.com/ansible-collections/community.network/>`_. The examples below demonstrate running tests in Docker containers."
msgid "See :ref:`testing_compile` and :ref:`testing_sanity` for more information. See the :ref:`full list of sanity tests <all_sanity_tests>` for details on the sanity tests and how to fix identified issues."
msgid "You must place unit tests in the appropriate``tests/unit/plugins/`` directory. For example, you would place tests for ``plugins/module_utils/foo/bar.py`` in ``tests/unit/plugins/module_utils/foo/test_bar.py`` or ``tests/unit/plugins/module_utils/foo/bar/test_bar.py``. For examples, see the `unit tests in community.general <https://github.com/ansible-collections/community.general/tree/master/tests/unit/>`_."
msgid "You can specify Python requirements in the ``tests/unit/requirements.txt`` file. See :ref:`testing_units` for more information, especially on fixture files."
msgid "You must place integration tests in the appropriate ``tests/integration/targets/`` directory. For module integration tests, you can use the module name alone. For example, you would place integration tests for ``plugins/modules/foo.py`` in a directory called ``tests/integration/targets/foo/``. For non-module plugin integration tests, you must add the plugin type to the directory name. For example, you would place integration tests for ``plugins/connections/bar.py`` in a directory called ``tests/integration/targets/connection_bar/``. For lookup plugins, the directory must be called ``lookup_foo``, for inventory plugins, ``inventory_foo``, and so on."
msgid "Ansible role tests run with ``ansible-playbook`` and validate various aspects of the module. They can depend on other integration tests (usually named ``prepare_bar`` or ``setup_bar``, which prepare a service or install a requirement named ``bar`` in order to test module ``foo``) to set-up required resources, such as installing required libraries or setting up server services."
msgid "``runme.sh`` tests run directly as scripts. They can set up inventory files, and execute ``ansible-playbook`` or ``ansible-inventory`` with various settings."
msgid "For examples, see the `integration tests in community.general <https://github.com/ansible-collections/community.general/tree/master/tests/integration/targets/>`_. See also :ref:`testing_integration` for more details."
msgid "Since integration tests can install requirements, and set-up, start and stop services, we recommended running them in docker containers or otherwise restricted environments whenever possible. By default, ``ansible-test`` supports Docker images for several operating systems. See the `list of supported docker images <https://github.com/ansible/ansible/blob/devel/test/lib/ansible_test/_data/completion/docker.txt>`_ for all options. Use the ``default`` image mainly for platform-independent integration tests, such as those for cloud modules. The following examples use the ``centos8`` image."
msgid "If you want more detailed output, run the command with ``-vvv`` instead of ``-v``. Alternatively, specify ``--retry-on-error`` to automatically re-run failed tests with higher verbosity levels."
msgid "If you want to add functionality to an existing collection, modify a collection you are using to fix a bug, or change the behavior of a module in a collection, clone the git repository for that collection and make changes on a branch. You can combine changes to a collection with a local checkout of Ansible (``source hacking/env-setup``)."
msgid "This section describes the process for `community.general <https://github.com/ansible-collections/community.general/>`_. To contribute to other collections, replace the folder names ``community`` and ``general`` with the namespace and collection name of a different collection."
msgid "We assume that you have included ``~/dev/ansible/collections/`` in :ref:`COLLECTIONS_PATHS`, and if that path mentions multiple directories, that you made sure that no other directory earlier in the search path contains a copy of ``community.general``. Create the directory ``~/dev/ansible/collections/ansible_collections/community``, and in it clone `the community.general Git repository <https://github.com/ansible-collections/community.general/>`_ or a fork of it into the folder ``general``::"
msgid "Now you can use this checkout of ``community.general`` in playbooks and roles with whichever version of Ansible you have installed locally, including a local checkout of ``ansible/ansible``'s ``devel`` branch."
msgid "For collections hosted in the ``ansible_collections`` GitHub org, create a branch and commit your changes on the branch. When you are done (remember to add tests, see :ref:`testing_collections`), push your changes to your fork of the collection and create a Pull Request. For other collections, especially for collections not hosted on GitHub, check the ``README.md`` of the collection for information on contributing to it."
msgid "We recommend that you use the `antsibull-changelog <https://github.com/ansible-community/antsibull-changelog>`_ tool to generate Ansible-compatible changelogs for your collection. The Ansible changelog uses the output of this tool to collate all the collections included in an Ansible release into one combined changelog for the release."
msgid "The ``antsibull-changelog`` tool allows you to create and update changelogs for Ansible collections that are compatible with the combined Ansible changelogs. This is an update to the changelog generator used in prior Ansible releases. The tool adds three new changelog fragment categories: ``breaking_changes``, ``security_fixes`` and ``trivial``. The tool also generates the ``changelog.yaml`` file that Ansible uses to create the combined ``CHANGELOG.rst`` file and Porting Guide for the release."
msgid "See :ref:`changelogs_how_to` and the `antsibull-changelog documentation <https://github.com/ansible-community/antsibull-changelog/tree/main/docs>`_ for complete details."
msgid "The collection maintainers set the changelog policy for their collections. See the individual collection contributing guidelines for complete details."
msgid "Optionally, edit the ``changelogs/config.yaml`` file to customize the location of the generated changelog ``.rst`` file or other options. See `Bootstrapping changelogs for collections <https://github.com/ansible-community/antsibull-changelog/blob/main/docs/changelogs.rst#bootstrapping-changelogs-for-collections>`_ for details."
msgid "Add the ``--reload-plugins`` option if you ran the ``antsibull-changelog release`` command previously and the version of the collection has not changed. ``antsibull-changelog`` caches the information on all plugins and does not update its cache until the collection version changes."
msgid "If are not using this tool, include the properly formatted ``changelog.yaml`` file into your collection. See the `changelog.yaml format <https://github.com/ansible-community/antsibull-changelog/blob/main/docs/changelog.yaml-format.md>`_ for details."
msgid "Add a link to own changelogs or release notes in any format by opening an issue at https://github.com/ansible-community/ansible-build-data/ with the HTML link to that information."
msgid "For the first two options, Ansible pulls the changelog details from Galaxy so your changelogs must be included in the collection version on Galaxy that is included in the upcoming Ansible release."
msgid "Understand the collections metadata structure."
msgstr "コレクションのメタデータ構造を理解します。"
#: ../../rst/dev_guide/developing_core.rst:3
msgid "Developing ``ansible-base``"
msgstr "``ansible-base`` の開発"
#: ../../rst/dev_guide/developing_core.rst:5
msgid "Although ``ansible-base`` (the code hosted in the `ansible/ansible repository <https://github.com/ansible/ansible>`_ on GitHub) includes a few plugins that can be swapped out via playbook directives or configuration, much of the code there is not modular. The documents here give insight into how the parts of ``ansible-base`` work together."
msgid "Learn about the Python API for task execution"
msgstr "タスク実行用の Python API について"
#: ../../rst/dev_guide/developing_core.rst:17
msgid "Learn about developing plugins"
msgstr "プラグインの開発について"
#: ../../rst/dev_guide/developing_core.rst:21
msgid "#ansible-devel IRC chat channel"
msgstr "IRC チャットチャンネル (#ansible-devel)"
#: ../../rst/dev_guide/developing_inventory.rst:5
msgid "Developing dynamic inventory"
msgstr "動的インベントリーの開発"
#: ../../rst/dev_guide/developing_inventory.rst:7
msgid "Ansible can pull inventory information from dynamic sources, including cloud sources, by using the supplied :ref:`inventory plugins <inventory_plugins>`. For details about how to pull inventory information, see :ref:`dynamic_inventory`. If the source you want is not currently covered by existing plugins, you can create your own inventory plugin as with any other plugin type."
msgid "In previous versions, you had to create a script or program that could output JSON in the correct format when invoked with the proper arguments. You can still use and write inventory scripts, as we ensured backwards compatibility via the :ref:`script inventory plugin <script_inventory>` and there is no restriction on the programming language used. If you choose to write a script, however, you will need to implement some features yourself such as caching, configuration management, dynamic variable and group composition, and so on. If you use :ref:`inventory plugins <inventory_plugins>` instead, you can leverage the Ansible codebase and add these common features automatically."
msgid "Inventory sources are the input strings that inventory plugins work with. An inventory source can be a path to a file or to a script, or it can be raw data that the plugin can interpret."
msgid "Like most plugin types (except modules), inventory plugins must be developed in Python. They execute on the controller and should therefore adhere to the :ref:`control_node_requirements`."
msgid "Most of the documentation in :ref:`developing_plugins` also applies here. You should read that document first for a general understanding and then come back to this document for specifics on inventory plugins."
msgid "Normally, inventory plugins are executed at the start of a run, and before the playbooks, plays, or roles are loaded. However, you can use the ``meta: refresh_inventory`` task to clear the current inventory and execute the inventory plugins again, and this task will generate a new inventory."
msgid "If you use the persistent cache, inventory plugins can also use the configured cache plugin to store and retrieve data. Caching inventory avoids making repeated and costly external calls."
msgid "If the inventory plugin is in a collection, the NAME should be in the 'namespace.collection_name.myplugin' format. The base class has a couple of methods that each plugin should implement and a few helpers for parsing the inventory source and updating the inventory."
msgid "Ansible uses this method to quickly determine if the inventory source is usable by the plugin. The determination does not need to be 100% accurate, as there might be an overlap in what plugins can handle and by default Ansible will try the enabled plugins as per their sequence."
msgid "In the above example, from the :ref:`virtualbox inventory plugin <virtualbox_inventory>`, we screen for specific file name patterns to avoid attempting to consume any valid YAML file. You can add any type of condition here, but the most common one is 'extension matching'. If you implement extension matching for YAML configuration files, the path suffix <plugin_name>.<yml|yaml> should be accepted. All valid extensions should be documented in the plugin description."
msgid "The following is another example that does not use a 'file' but the inventory source string itself, from the :ref:`host list <host_list_inventory>` plugin:"
msgstr "以下は、「ファイル」を使用せず、:ref:`host list <host_list_inventory>` プラグインからインベントリソース文字列自体を使用する別の例です。"
msgid "This method is just to expedite the inventory process and avoid unnecessary parsing of sources that are easy to filter out before causing a parse error."
msgid "It is up to the plugin now to parse the provided inventory source and translate it into Ansible inventory. To facilitate this, the example below uses a few helper functions:"
msgid "The specifics will vary depending on API and structure returned. Remember that if you get an inventory source error or any other issue, you should ``raise AnsibleParserError`` to let Ansible know that the source was invalid or the process failed."
msgid "For examples on how to implement an inventory plugin, see the source code here: `lib/ansible/plugins/inventory <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/inventory>`_."
msgid "To cache the inventory, extend the inventory plugin documentation with the inventory_cache documentation fragment and use the Cacheable base class."
msgid "Next, load the cache plugin specified by the user to read from and update the cache. If your inventory plugin uses YAML-based configuration files and the ``_read_config_data`` method, the cache plugin is loaded within that method. If your inventory plugin does not use ``_read_config_data``, you must load the cache explicitly with ``load_cache_plugin``."
msgid "Before using the cache plugin, you must retrieve a unique cache key by using the ``get_cache_key`` method. This task needs to be done by all inventory modules using the cache, so that you don't use/overwrite other parts of the cache."
msgid "Now that you've enabled caching, loaded the correct plugin, and retrieved a unique cache key, you can set up the flow of data between the cache and your inventory using the ``cache`` parameter of the ``parse`` method. This value comes from the inventory manager and indicates whether the inventory is being refreshed (such as via ``--flush-cache`` or the meta task ``refresh_inventory``). Although the cache shouldn't be used to populate the inventory when being refreshed, the cache should be updated with the new inventory if the user has enabled caching. You can use ``self._cache`` like a dictionary. The following pattern allows refreshing the inventory to work in conjunction with caching."
msgid "After the ``parse`` method is complete, the contents of ``self._cache`` is used to set the cache plugin if the contents of the cache have changed."
msgid "``clear_cache`` flushes the cache, ultimately by calling the cache plugin's ``flush()`` method, whose implementation is dependent upon the particular cache plugin in use. Note that if the user is using the same cache backend for facts and inventory, both will get flushed. To avoid this, the user can specify a distinct cache backend in their inventory plugin configuration."
msgid "To simplify development, most plugins use a standard YAML-based configuration file as the inventory source. The file has only one required field ``plugin``, which should contain the name of the plugin that is expected to consume the file. Depending on other common features used, you might need other fields, and you can add custom options in each plugin as required. For example, if you use the integrated caching, ``cache_plugin``, ``cache_timeout`` and other cache-related fields could be present."
msgid "From Ansible 2.5 onwards, we include the :ref:`auto inventory plugin <auto_inventory>` and enable it by default. If the ``plugin`` field in your standard configuration file matches the name of your inventory plugin, the ``auto`` inventory plugin will load your plugin. The 'auto' plugin makes it easier to use your plugin without having to update configurations."
msgid "Even though we now have inventory plugins, we still support inventory scripts, not only for backwards compatibility but also to allow users to leverage other programming languages."
msgid "Inventory scripts must accept the ``--list`` and ``--host <hostname>`` arguments. Although other arguments are allowed, Ansible will not use them. Such arguments might still be useful for executing the scripts directly."
msgid "When the script is called with the single argument ``--list``, the script must output to stdout a JSON-encoded hash or dictionary that contains all the groups to be managed. Each group's value should be either a hash or dictionary containing a list of each host, any child groups, and potential group variables, or simply a list of hosts::"
msgid "When called with the argument ``--host <hostname>`` (where <hostname> is a host from above), the script must print either an empty JSON hash/dictionary, or a hash/dictionary of variables to make them available to templates and playbooks. For example::"
msgid "The stock inventory script system mentioned above works for all versions of Ansible, but calling ``--host`` for every host can be rather inefficient, especially if it involves API calls to a remote subsystem."
msgstr "上記のストックのインベントリースクリプトシステムは、すべてのバージョンの Ansible に対して動作しますが、特にリモートサブシステムへの API 呼び出しが必要になる場合は、すべてのホストに対して ``--host`` を呼び出すこともできます。"
msgid "To avoid this inefficiency, if the inventory script returns a top-level element called \"_meta\", it is possible to return all the host variables in a single script execution. When this meta element contains a value for \"hostvars\", the inventory script will not be invoked with ``--host`` for each host. This behavior results in a significant performance increase for large numbers of hosts."
msgid "To satisfy the requirements of using ``_meta``, to prevent ansible from calling your inventory with ``--host`` you must at least populate ``_meta`` with an empty ``hostvars`` dictionary. For example::"
msgid "If you intend to replace an existing static inventory file with an inventory script, it must return a JSON object which contains an 'all' group that includes every host in the inventory as a member and every group in the inventory as a child. It should also include an 'ungrouped' group which contains all hosts which are not members of any other group. A skeleton example of this JSON object is:"
msgid "An easy way to see how this should look is using :ref:`ansible-inventory`, which also supports ``--list`` and ``--host`` parameters like an inventory script would."
msgid "REST API endpoint and GUI for Ansible, syncs with dynamic inventory"
msgstr "Ansible の REST API エンドポイントおよび GUI (動的インベントリーと同期)"
#: ../../rst/dev_guide/developing_locally.rst:6
msgid "Adding modules and plugins locally"
msgstr "モジュールおよびプラグインをローカルで追加"
#: ../../rst/dev_guide/developing_locally.rst:8
msgid "The easiest, quickest, and the most popular way to extend Ansible is to use a local module or a plugin. You can create them or copy existing ones for local use. You can store a local module or plugin on your Ansible control node and share it with your team or organization. You can also share a local plugin or module by including it in a collection or embedding it in a role, then publishing the collection or role on Ansible Galaxy. If you are using roles on Ansible Galaxy, then you are already using local modules and plugins without realizing it."
msgid "If you are using an existing module or plugin but Ansible can't find it, this page is all you need. However, if you want to create a plugin or a module, go to :ref:`developing_plugins` and :ref:`developing_modules_general` topics and then return to this page to know how to add it locally."
msgid "You can copy other people's modules and plugins."
msgstr "他のユーザーのモジュールおよびプラグインをコピーできます。"
#: ../../rst/dev_guide/developing_locally.rst:15
msgid "When writing a new module, you can choose any programming language you like."
msgstr "新しいモジュールを作成する場合は、任意のプログラミング言語を選択できます。"
#: ../../rst/dev_guide/developing_locally.rst:16
msgid "You do not have to clone any repositories."
msgstr "リポジトリーのクローンを作成する必要はありません。"
#: ../../rst/dev_guide/developing_locally.rst:17
msgid "You do not have to open a pull request."
msgstr "プルリクエストを開く必要はありません。"
#: ../../rst/dev_guide/developing_locally.rst:18
msgid "You do not have to add tests (though we recommend that you do!)."
msgstr "テストを追加する必要はありません (ただし、この操作を推奨しています)。"
#: ../../rst/dev_guide/developing_locally.rst:20
msgid "To save a local module or plugin such that Ansible can find and use it, add the module or plugin in the appropriate directory (the directories are specified in later parts of this topic)."
msgid "Modules and plugins: what is the difference?"
msgstr "モジュールおよびプラグイン: 相違点"
#: ../../rst/dev_guide/developing_locally.rst:29
msgid "If you are looking to add local functionality to Ansible, you might wonder whether you need a module or a plugin. Here is a quick overview to help you decide between the two:"
msgid "Modules are reusable, standalone scripts that can be used by the Ansible API, the :command:`ansible` command, or the :command:`ansible-playbook` command. Modules provide a defined interface. Each module accepts arguments and returns information to Ansible by printing a JSON string to stdout before exiting. Modules execute on the target system (usually that means on a remote system) in separate processes."
msgid ":ref:`Plugins <plugins_lookup>` augment Ansible's core functionality and execute on the control node within the ``/usr/bin/ansible`` process. Plugins offer options and extensions for the core features of Ansible - transforming data, logging output, connecting to inventory, and more."
msgid "For local modules, use the name of the file as the module name: for example, if the module file is ``~/.ansible/plugins/modules/local_users.py``, use ``local_users`` as the module name."
msgid "Currently, the ``ansible-doc`` command can parse module documentation only from modules written in Python. If you have a module written in a programming language other than Python, please write the documentation in a Python file adjacent to the module file."
msgid "You can limit the availability of your local module. If you want to use a local module only with selected playbooks or only with a single role, load it in one of the following locations:"
msgid "Ansible loads plugins automatically too, and loads each type of plugin separately from a directory named for the type of plugin. Here's the full list of plugin directory names:"
msgid "After you add the plugins and verify that they are available for use, you can see the documentation for all the plugins except for the ones marked with an asterisk (*) above."
msgid "To load your local plugins automatically, add them in any of these locations:"
msgstr "ローカルプラグインを自動的に読み込むには、以下のいずれかの場所に追加します。"
#: ../../rst/dev_guide/developing_locally.rst:92
msgid "any directory added to the relevant ``ANSIBLE_plugin_type_PLUGINS`` environment variable (these variables, such as ``$ANSIBLE_INVENTORY_PLUGINS`` and ``$ANSIBLE_VARS_PLUGINS`` take colon-separated lists like ``$PATH``)"
msgid "the directory named for the correct ``plugin_type`` within ``/usr/share/ansible/plugins/`` - for example, ``/usr/share/ansible/plugins/action``"
msgid "After your plugin file is in one of these locations, Ansible loads it and you can use it in any local module, task, playbook, or role. Alternatively, you can edit your ``ansible.cfg`` file to add directories that contain local plugins. For details about adding directories of local plugins, see :ref:`ansible_configuration_settings`."
msgid "type ``ansible-doc -t <plugin_type> my_custom_lookup_plugin``. For example, ``ansible-doc -t lookup my_custom_lookup_plugin``. You should see the documentation for that plugin. This works for all plugin types except the ones marked with ``*`` in the list above - see :ref:`ansible-doc` for more details."
msgid "You can limit the availability of your local plugin. If you want to use a local plugin only with selected playbooks or only with a single role, load it in one of the following locations:"
msgid "In a selected playbook or playbooks: Store the plugin in a subdirectory for the correct ``plugin_type`` (for example, ``callback_plugins`` or ``inventory_plugins``) in the directory that contains the playbooks."
msgid "In a single role: Store the plugin in a subdirectory for the correct ``plugin_type`` (for example, ``cache_plugins`` or ``strategy_plugins``) within that role. When shipped as part of a role, the plugin is available as soon as the role is executed."
msgid "Ansible provides a number of module utilities, or snippets of shared code, that provide helper functions you can use when developing your own modules. The ``basic.py`` module utility provides the main entry point for accessing the Ansible library, and all Python Ansible modules must import something from ``ansible.module_utils``. A common option is to import ``AnsibleModule``::"
msgid "The ``ansible.module_utils`` namespace is not a plain Python package: it is constructed dynamically for each task invocation, by extracting imports and resolving those matching the namespace against a :ref:`search path <ansible_search_path>` derived from the active configuration."
msgid "To reduce the maintenance burden in a collection or in local modules, you can extract duplicated code into one or more module utilities and import them into your modules. For example, if you have your own custom modules that import a ``my_shared_code`` library, you can place that into a ``./module_utils/my_shared_code.py`` file like this::"
msgid "When you run ``ansible-playbook``, Ansible will merge any files in your local ``module_utils`` directories into the ``ansible.module_utils`` namespace in the order defined by the :ref:`Ansible search path <ansible_search_path>`."
msgid "You can generally tell what a module utility does from its name and/or its location. Generic utilities (shared code used by many different kinds of modules) live in the main ansible/ansible codebase, in the ``common`` subdirectory or in the root directory of ``lib/ansible/module_utils``. Utilities used by a particular set of modules generally live in the same collection as those modules. For example:"
msgid "Ansible ships with an extensive library of ``module_utils`` files. You can find the module utility source code in the ``lib/ansible/module_utils`` directory under your main Ansible path. We describe the most widely used utilities below. For more details on any specific module utility, please see the `source code for module_utils <https://github.com/ansible/ansible/tree/devel/lib/ansible/module_utils>`_."
msgid "A file in ``module_utils`` used **only** for a specific vendor's hardware, provider, or service may be licensed under GPLv3+. Adding a new file under ``module_utils`` with GPLv3+ needs to be approved by the core team."
msgid "If there's doubt about the appropriate license for a file in ``module_utils``, the Ansible Core Team will decide during an Ansible Core Community Meeting."
msgstr "``module_utils`` のファイルに適切なライセンスについて疑問がある場合は、Ansible Core Team が Ansible Core Community Meeting 中に決定します。"
msgid "``facts/`` - Directory of utilities for modules that return facts. See `PR 23012 <https://github.com/ansible/ansible/pull/23012>`_ for more information"
msgid "``six/__init__.py`` - Bundled copy of the `Six Python library <https://pypi.org/project/six/>`_ to aid in writing code compatible with both Python 2 and Python 3"
msgid "For a list of migrated content with destination collections, see https://github.com/ansible/ansible/blob/devel/lib/ansible/config/ansible_builtin_runtime.yml."
msgid "An existing module may cover the functionality you want. Ansible collections include thousands of modules. Search our :ref:`list of included collections <list_of_collections>` or `Ansible Galaxy <https://galaxy.ansible.com>`_ to see if an existing module does what you need."
msgid "An action plugin may be the best way to get the functionality you want. Action plugins run on the control node instead of on the managed node, and their functionality is available to all modules. For more information about developing plugins, read the :ref:`developing plugins page <developing_plugins>`."
msgid "Should you use a role instead of a module?"
msgstr "モジュールの代わりにロールを使用する必要があるか。"
#: ../../rst/dev_guide/developing_modules.rst:20
msgid "A combination of existing modules may cover the functionality you want. You can write a role for this type of use case. Check out the :ref:`roles documentation<playbooks_reuse_roles>`."
msgid "Should you create a collection instead of a single module?"
msgstr "1 つのモジュールの代わりにコレクションを作成する必要があるか。"
#: ../../rst/dev_guide/developing_modules.rst:24
msgid "The functionality you want may be too large for a single module. If you want to connect Ansible to a new cloud provider, database, or network platform, you may need to :ref:`develop a new collection<developing_modules_in_groups>`."
msgid "A module should not require that a user know all the underlying options of an API/tool to be used. For instance, if the legal values for a required module parameter cannot be documented, that's a sign that the module would be rejected."
msgstr "モジュールは、使用する API またはツールの基礎となるすべてのオプションを把握する必要がありません。たとえば、必要なモジュールパラメーターの有効な値を文書化できない場合、それはモジュールが拒否されることを示しています。"
#: ../../rst/dev_guide/developing_modules.rst:30
msgid "Modules should typically encompass much of the logic for interacting with a resource. A lightweight wrapper around an API that does not contain much logic would likely cause users to offload too much logic into a playbook, and for this reason the module would be rejected. Instead try creating multiple modules for interacting with smaller individual pieces of the API."
msgstr "モジュールは通常、リソースと対話するロジックの多くを網羅する必要があります。ロジックをあまり含まない API の軽量ラッパーを使用すると、ユーザーがあまりにも多くのロジックを Playbook にオフロードする原因となる可能性があるため、モジュールが拒否されます。代わりに、API の小さな個々の部分と対話するための複数のモジュールを作成してみてください。"
#: ../../rst/dev_guide/developing_modules.rst:32
msgid "If your use case isn't covered by an existing module, an action plugin, or a role, and you don't need to create multiple modules, then you're ready to start developing a new module. Choose from the topics below for next steps:"
msgid "Especially if you want to contribute your module(s) to an existing Ansible Collection, make sure each module includes enough logic and functionality, but not too much. If these guidelines seem confusing, consider :ref:`whether you really need to write a module <module_dev_should_you>` at all."
msgid "Modules should not require that a user know all the underlying options of an API/tool to be used. For instance, if the legal values for a required module option cannot be documented, the module does not belong in Ansible Core."
msgstr "モジュールでは、使用する API またはツールの基礎となるオプションをすべてユーザーが把握する必要がありません。たとえば、必要なモジュールパラメーターの有効な値を文書化できない場合、そのモジュールは Ansible Core に属しません。"
msgid "Modules should encompass much of the logic for interacting with a resource. A lightweight wrapper around a complex API forces users to offload too much logic into their playbooks. If you want to connect Ansible to a complex API, :ref:`create multiple modules <developing_modules_in_groups>` that interact with smaller individual pieces of the API."
msgstr "モジュールは、リソースと対話するためのロジックを多数組み込む必要があります。複雑な API に関連した軽量ラッパーにより、ユーザーは Playbook に非常に多くのロジックをオフロードします。Ansible を複雑な API に接続する場合は、より複雑な API と対話する :ref:`複数のモジュールを作成 <developing_modules_in_groups>` する必要があります。"
msgid "Avoid creating a module that does the work of other modules; this leads to code duplication and divergence, and makes things less uniform, unpredictable and harder to maintain. Modules should be the building blocks. If you are asking 'how can I have a module execute other modules' ... you want to write a role."
msgid "If your module is addressing an object, the option for that object should be called ``name`` whenever possible, or accept ``name`` as an alias."
msgid "Modules accepting boolean status should accept ``yes``, ``no``, ``true``, ``false``, or anything else a user may likely throw at them. The AnsibleModule common code supports this with ``type='bool'``."
msgid "Module name MUST use underscores instead of hyphens or spaces as a word separator. Using hyphens and spaces will prevent ``ansible-base`` from importing your module."
msgid "Eliminate or minimize dependencies. If your module has dependencies, document them at the top of the module file and raise JSON error messages when dependency import fails."
msgid "Don't write to files directly; use a temporary file and then use the ``atomic_move`` function from ``ansible.module_utils.basic`` to move the updated temporary file into place. This prevents data corruption and ensures that the correct context for the file is kept."
msgid "Avoid creating caches. Ansible is designed without a central server or authority, so you cannot guarantee it will not run with different permissions, options or locations. If you need a central authority, have it on top of Ansible (for example, using bastion/cm/ci server or tower); do not try to build it into modules."
msgid "If you package your module(s) in an RPM, install the modules on the control machine in ``/usr/share/ansible``. Packaging modules in RPMs is optional."
msgid "If your code is too nested, that's usually a sign the loop body could benefit from being a function. Parts of our existing code are not the best examples of this at times."
msgid "Use shared code whenever possible - don't reinvent the wheel. Ansible offers the ``AnsibleModule`` common Python code, plus :ref:`utilities <developing_module_utilities>` for many common use cases and patterns. You can also create documentation fragments for docs that apply to multiple modules."
msgid "Do NOT use wildcards (*) for importing other python modules; instead, list the function(s) you are importing (for example, ``from some.other_python_module.basic import otherFunction``)."
msgid "When your module fails, help users understand what went wrong. If you are using the ``AnsibleModule`` common Python code, the ``failed`` element will be included for you automatically when you call ``fail_json``. For polite module failure behavior:"
msgid "Include a key of ``failed`` along with a string explanation in ``msg``. If you don't do this, Ansible will use standard return codes: 0=success and non-zero=failure."
msgid "Don't raise a traceback (stacktrace). Ansible can deal with stacktraces and automatically converts anything unparsable into a failed result, but raising a stacktrace on module failure is not user-friendly."
msgid "Fail predictably--if we must fail, do it in a way that is the most expected. Either mimic the underlying tool or the general way the system works."
msgid "Return diff if in diff mode. This is not required for all modules, as it won't make sense for certain ones, but please include it when applicable."
msgid "Enable your return values to be serialized as JSON with Python's standard `JSON encoder and decoder <https://docs.python.org/3/library/json.html>`_ library. Basic python types (strings, int, dicts, lists, and so on) are serializable."
msgid "Do not return an object using exit_json(). Instead, convert the fields you need from the object into the fields of a dictionary and return the dictionary."
msgid "Results from many hosts will be aggregated at once, so your module should return only relevant output. Returning the entire contents of a log file is generally bad form."
msgid "If a module returns stderr or otherwise fails to produce valid JSON, the actual output will still be shown in Ansible, but the command will not succeed."
msgid "Ansible conventions offer a predictable user interface across all modules, playbooks, and roles. To follow Ansible conventions in your module development:"
msgid "Normalize options with other modules - if Ansible and the API your module connects to use different names for the same option, add aliases to your options so the user can choose which names to use in tasks and playbooks."
msgstr "他のモジュールでオプションを正規化します。Ansible と、モジュールが接続する API が同じオプションに異なる名前を使用している場合は、オプションにエイリアスを追加して、ユーザーがタスクおよび Playbook で使用する名前を選択できるようにします。"
msgid "Return facts from ``*_facts`` modules in the ``ansible_facts`` field of the :ref:`result dictionary<common_return_values>` so other modules can access them."
msgid "Implement ``check_mode`` in all ``*_info`` and ``*_facts`` modules. Playbooks which conditionalize based on fact information will only conditionalize correctly in ``check_mode`` if the facts are returned in ``check_mode``. Usually you can add ``supports_check_mode=True`` when instantiating ``AnsibleModule``."
msgid "Use module-specific environment variables. For example, if you use the helpers in ``module_utils.api`` for basic authentication with ``module_utils.urls.fetch_url()`` and you fall back on environment variables for default values, use a module-specific environment variable like :code:`API_<MODULENAME>_USERNAME` to avoid conflicts between modules."
msgid "Keep module options simple and focused - if you're loading a lot of choices/states on an existing option, consider adding a new, simple option instead."
msgid "Keep options small when possible. Passing a large data structure to an option might save us a few tasks, but it adds a complex requirement that we cannot easily validate before passing on to the module."
msgid "If you want to pass complex data to an option, write an expert module that allows this, along with several smaller modules that provide a more 'atomic' operation against the underlying APIs and services. Complex operations require complex data. Let the user choose whether to reflect that complexity in tasks and plays or in vars files."
msgstr "複雑なデータをオプションに渡したいのであれば、それを可能にするエキスパートモジュールと、基礎となる API やサービスに対してより「アトミックな」操作を提供するいくつかの小さなモジュールを作成します。複雑な操作には複雑なデータが必要です。その複雑さをタスクやプレイに反映させるか、vars ファイルに反映させるかをユーザが選択できるようにします。"
msgid "Implement declarative operations (not CRUD) so the user can ignore existing state and focus on final state. For example, use ``started/stopped``, ``present/absent``."
msgid "Strive for a consistent final state (aka idempotency). If running your module twice in a row against the same system would result in two different states, see if you can redesign or rewrite to achieve consistent final state. If you can't, document the behavior and the reasons for it."
msgid "Provide consistent return values within the standard Ansible return structure, even if NA/None are used for keys normally returned under other options."
msgid "Follow additional guidelines that apply to families of modules if applicable. For example, AWS modules should follow the :ref:`Amazon development checklist <AWS_module_development>`."
msgstr "該当する場合は、モジュールのファミリーに適用される追加のガイドラインに従います。たとえば、AWS モジュールは :ref:`Amazon development checklist <AWS_module_development>` に従う必要があります。"
msgid "When fetching URLs, use ``fetch_url`` or ``open_url`` from ``ansible.module_utils.urls``. Do not use ``urllib2``, which does not natively verify TLS certificates and so is insecure for https."
msgid "Sensitive values marked with ``no_log=True`` will automatically have that value stripped from module return values. If your module could return these sensitive values as part of a dictionary key name, you should call the ``ansible.module_utils.basic.sanitize_keys()`` function to strip the values from the keys. See the ``uri`` module for an example."
msgid "If you want to contribute a module to an existing collection, you must meet the community's objective and subjective requirements. Please read the details below, and also review our :ref:`tips for module development <developing_modules_best_practices>`."
msgid "Modules accepted into certain collections are included in every Ansible release on PyPI. However, contributing to one of these collections is not the only way to distribute a module - you can :ref:`create your own collection <developing_collections>`, embed modules in roles on Galaxy or simply share copies of your module code for :ref:`local use <developing_locally>`."
msgid "support Python 2.6 and Python 3.5 - if your module cannot support Python 2.6, explain the required minimum Python version and rationale in the requirements section in ``DOCUMENTATION``"
msgid "if a module is named ``<something>_facts``, it should be because its main purpose is returning ``ansible_facts``. Do not name modules that do not do this with ``_facts``. Only use ``ansible_facts`` for information that is specific to the host machine, for example network interfaces and their configuration, which operating system and which programs are installed."
msgid "Modules that query/return general information (and not ``ansible_facts``) should be named ``_info``. General information is non-host specific information, for example information on online/cloud services (you can access different accounts for the same online service from the same host), or information on VMs and containers accessible from the machine."
msgid "Please make sure your module meets these requirements before you submit your PR/proposal. If you have questions, reach out via `Ansible's IRC chat channel <http://irc.freenode.net>`_ or the `Ansible development mailing list <https://groups.google.com/group/ansible-devel>`_."
msgid "If your module meets these objective requirements, collection maintainers will review your code to see if they think it's clear, concise, secure, and maintainable. They will consider whether your module provides a good user experience, helpful error messages, reasonable defaults, and more. This process is subjective, with no exact standards for acceptance. For the best chance of getting your module accepted, follow our :ref:`tips for module development <developing_modules_best_practices>`."
msgid "If you want to contribute your module to most Ansible collections, you must write your module in Python and follow the standard format described below. (Unless you're writing a Windows module, in which case the :ref:`Windows guidelines <developing_modules_general_windows>` apply.) In addition to following this format, you should review our :ref:`submission checklist <developing_modules_checklist>`, :ref:`programming tips <developing_modules_best_practices>`, and :ref:`strategy for maintaining Python 2 and Python 3 compatibility <developing_python_3>`, as well as information about :ref:`testing <developing_testing>` before you open a pull request."
msgid "Every Ansible module written in Python must begin with seven standard sections in a particular order, followed by the code. The sections in order are:"
msgid "Keen Python programmers may notice that contrary to PEP 8's advice we don't put ``imports`` at the top of the file. This is because the ``DOCUMENTATION`` through ``RETURN`` sections are not used by the module code itself; they are essentially extra docstrings for the file. The imports are placed after these special variables for the same reason as PEP 8 puts the imports after the introductory comments and docstrings. This keeps the active parts of the code together and the pieces which are purely informational apart. The decision to exclude E402 is based on readability (which is what PEP 8 is about). Documentation strings in a module are much more similar to module level docstrings, than code, and are never utilized by the module itself. Placing the imports below this documentation and closer to the code, consolidates and groups all related code in a congruent manner to improve readability, debugging and understanding."
msgid "Some older Ansible modules have ``imports`` at the bottom of the file, ``Copyright`` notices with the full GPL prefix, and/or ``DOCUMENTATION`` fields in the wrong order. These are legacy files that need updating - do not copy them into new modules. Over time we are updating and correcting older modules. Please follow the guidelines on this page!"
msgid "Begin your Ansible module with ``#!/usr/bin/python`` - this \"shebang\" allows ``ansible_python_interpreter`` to work. Follow the shebang immediately with ``# -*- coding: utf-8 -*-`` to clarify that the file is UTF-8 encoded."
msgid "After the shebang and UTF-8 coding, add a `copyright line <https://www.gnu.org/licenses/gpl-howto.en.html>`_ with the original copyright holder and a license declaration. The license declaration should be ONLY one line, not the full GPL prefix.:"
msgid "Major additions to the module (for instance, rewrites) may add additional copyright lines. Any legal review will include the source control history, so an exhaustive copyright header is not necessary. Please do not edit the existing copyright year. This simplifies project administration and is unlikely to cause any interesting legal issues. When adding a second copyright line for a significant feature or rewrite, add the newer line above the older one:"
msgid "Since we moved to collections we have deprecated the METADATA functionality, it is no longer required for modules, but it will not break anything if present."
msgid "After the shebang, the UTF-8 coding, the copyright line, and the license section comes the ``DOCUMENTATION`` block. Ansible's online module documentation is generated from the ``DOCUMENTATION`` blocks in each module's source code. The ``DOCUMENTATION`` block must be valid YAML. You may find it easier to start writing your ``DOCUMENTATION`` string in an :ref:`editor with YAML syntax highlighting <other_tools_and_programs>` before you include it in your Python file. You can start by copying our `example documentation string <https://github.com/ansible/ansible/blob/devel/examples/DOCUMENTATION.yml>`_ into your module file and modifying it. If you run into syntax issues in your YAML, you can validate it on the `YAML Lint <http://www.yamllint.com/>`_ website."
msgid "Module documentation should briefly and accurately define what each module and option does, and how it works with others in the underlying system. Documentation should be written for broad audience--readable both by experts and non-experts."
msgid "For arguments that seem to contain sensitive information but **do not** contain secrets, such as \"password_length\", set ``no_log=False`` to disable the warning message."
msgid "As long as your module file is :ref:`available locally <local_modules>`, you can use ``ansible-doc -t module my_module_name`` to view your module documentation at the command line. Any parsing errors will be obvious - you can view details by adding ``-vvv`` to the command."
msgid "The ``short_description`` is displayed by ``ansible-doc -l`` without any category grouping, so it needs enough detail to explain the module's purpose without the context of the directory structure in which it lives."
msgid "If the option is a boolean value, you can use any of the boolean values recognized by Ansible: (such as true/false or yes/no). Choose the one that reads better in the context of the option."
msgid "Only needed if this option was extended after initial Ansible release, in other words, this is greater than the top level `version_added` field."
msgid "See :ref:`ansible_collections.azure.azcollection.azure_rm_securitygroup_module`, :ref:`ansible_collections.azure.azcollection.azure_rm_azurefirewall_module`, and :ref:`ansible_collections.openstack.cloud.baremetal_node_action_module` for examples."
msgid "You can link from your module documentation to other module docs, other resources on docs.ansible.com, and resources elsewhere on the internet with the help of some pre-defined macros. The correct formats for these macros are:"
msgid "``L()`` for links with a heading. For example: ``See L(Ansible Tower,https://www.ansible.com/products/tower).`` As of Ansible 2.10, do not use ``L()`` for relative links between Ansible documentation and collection documentation."
msgid "``R()`` for cross-references with a heading (added in Ansible 2.10). For example: ``See R(Cisco IOS Platform Guide,ios_platform_options)``. Use the RST anchor for the cross-reference. See :ref:`adding_anchors_rst` for details."
msgid "``C()`` for files, option values, and inline code. For example: ``If not set the environment variable C(ACME_PASSWORD) will be used.`` or ``Use C(var | foo.bar.my_filter) to transform C(var) into the required format.`` This displays with a mono-space font in the documentation."
msgstr "ファイル、オプション値、およびインラインコードの場合は ``C()`` (例 ``If not set the environment variable C(ACME_PASSWORD) will be used.`` または ``Use C(var | foo.bar.my_filter) to transform C(var) into the required format.``)。これは、ドキュメントでは Monospace フォントと表示されます。"
msgid "``HORIZONTALLINE`` is used sparingly as a separator in long descriptions. It becomes a horizontal rule (the ``<hr>`` html tag) in the documentation."
msgstr "``HORIZONTALLINE`` は、長い説明では、区切り文字として慎重に使用されており、ドキュメント内の水平ルール (``<hr>`` html タグ) になります。"
msgid "For links between modules and documentation within a collection, you can use any of the options above. For links outside of your collection, use ``R()`` if available. Otherwise, use ``U()`` or ``L()`` with full URLs (not relative links). For modules, use ``M()`` with the FQCN or ``ansible.builtin`` as shown in the example. If you are creating your own documentation site, you will need to use the `intersphinx extension <https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html>`_ to convert ``R()`` and ``M()`` to the correct links."
msgid "If you are writing multiple related modules, they may share common documentation, such as authentication details, file mode settings, ``notes:`` or ``seealso:`` entries. Rather than duplicate that information in each module's ``DOCUMENTATION`` block, you can save it once as a doc_fragment plugin and use it in each module's documentation. In Ansible, shared documentation fragments are contained in a ``ModuleDocFragment`` class in `lib/ansible/plugins/doc_fragments/ <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/doc_fragments>`_ or the equivalent directory in a collection. To include a documentation fragment, add ``extends_documentation_fragment: FRAGMENT_NAME`` in your module documentation. Use the fully qualified collection name for the FRAGMENT_NAME (for example, ``community.kubernetes.k8s_auth_options``)."
msgid "Modules should only use items from a doc fragment if the module will implement all of the interface documented there in a manner that behaves the same as the existing modules which import that fragment. The goal is that items imported from the doc fragment will behave identically when used in another module that imports the doc fragment."
msgid "By default, only the ``DOCUMENTATION`` property from a doc fragment is inserted into the module documentation. It is possible to define additional properties in the doc fragment in order to import only certain parts of a doc fragment or mix and match as appropriate. If a property is defined in both the doc fragment and the module, the module value overrides the doc fragment."
msgid "Since Ansible 2.8, you can have user-supplied doc_fragments by using a ``doc_fragments`` directory adjacent to play or role, just like any other plugin."
msgid "After the shebang, the UTF-8 coding, the copyright line, the license section, and the ``DOCUMENTATION`` block comes the ``EXAMPLES`` block. Here you show users how your module works with real-world examples in multi-line plain-text YAML format. The best examples are ready for the user to copy and paste into a playbook. Review and update your examples with every change to your module."
msgid "Use a fully qualified collection name (FQCN) as a part of the module's name like in the example above. For modules in ``ansible-base``, use the ``ansible.builtin.`` identifier, for example ``ansible.builtin.debug``."
msgid "If your examples use boolean options, use yes/no values. Since the documentation generates boolean values as yes/no, having the examples use these values as well makes the module documentation more consistent."
msgid "After the shebang, the UTF-8 coding, the copyright line, the license section, ``DOCUMENTATION`` and ``EXAMPLES`` blocks comes the ``RETURN`` block. This section documents the information the module returns for use by other modules."
msgid "If your module doesn't return anything (apart from the standard returns), this section of your module should read: ``RETURN = r''' # '''`` Otherwise, for each value returned, provide the following fields. All fields are required unless specified otherwise."
msgid "Only needed if this return was extended after initial Ansible release, in other words, this is greater than the top level `version_added` field. This is a string, and not a float, for example, ``version_added: '2.3'``."
msgid "Optional. To describe nested return values, set ``type: dict``, or ``type: list``/``elements: dict``, or if you really have to, ``type: complex``, and repeat the elements above for each sub-field."
msgid "After the shebang, the UTF-8 coding, the copyright line, the license, and the sections for ``DOCUMENTATION``, ``EXAMPLES``, and ``RETURN``, you can finally add the python imports. All modules must use Python imports in the form:"
msgid "A module is a reusable, standalone script that Ansible runs on your behalf, either locally or remotely. Modules interact with your local machine, an API, or a remote system to perform specific tasks like changing a database password or spinning up a cloud instance. Each module can be used by the Ansible API, or by the :command:`ansible` or :command:`ansible-playbook` programs. A module provides a defined interface, accepts arguments, and returns information to Ansible by printing a JSON string to stdout before exiting."
msgid "If you need functionality that is not available in any of the thousands of Ansible modules found in collections, you can easily write your own custom module. When you write a module for local use, you can choose any programming language and follow your own rules. Use this topic to learn how to create an Ansible module in Python. After you create a module, you must add it locally to the appropriate directory so that Ansible can find and execute it. For details about adding a module locally, see :ref:`developing_locally`."
msgid "Create a virtual environment: ``$ python3 -m venv venv`` (or for Python 2 ``$ virtualenv venv``. Note, this requires you to install the virtualenv package: ``$ pip install virtualenv``)"
msgid "After the initial setup above, every time you are ready to start developing Ansible you should be able to just run the following from the root of the Ansible repo: ``$ . venv/bin/activate && . hacking/env-setup``"
msgid "Ansible gathers information about the target machines using facts modules, and gathers information on other objects or files using info modules. If you find yourself trying to add ``state: info`` or ``state: list`` to an existing module, that is often a sign that a new dedicated ``_facts`` or ``_info`` module is needed."
msgid "If a module is named ``<something>_facts``, it should be because its main purpose is returning ``ansible_facts``. Do not name modules that do not do this with ``_facts``. Only use ``ansible_facts`` for information that is specific to the host machine, for example network interfaces and their configuration, which operating system and which programs are installed."
msgid "Modules that query/return general information (and not ``ansible_facts``) should be named ``_info``. General information is non-host specific information, for example information on online/cloud services (you can access different accounts for the same online service from the same host), or information on VMs and containers accessible from the machine, or information on individual files or programs."
msgid "Fact ``*_facts`` modules MUST return in the ``ansible_facts`` field of the :ref:`result dictionary<common_return_values>` so other modules can access them."
msgid "Navigate to the correct directory for your new module: ``$ cd lib/ansible/modules/``. If you are developing module using collection, ``$ cd plugins/modules/`` inside your collection development tree."
msgstr "新しいモジュールの正しいディレクトリーに移動します (``$ cd lib/ansible/modules/``)。コレクションを使用してモジュールを開発する場合は、コレクション開発ツリー内で ``$ cd plugins/modules/`` を実行します。"
msgid "Paste the content below into your new info module file. It includes the :ref:`required Ansible format and documentation <developing_modules_documenting>`, a simple :ref:`argument spec for declaring the module options <argument_spec>`, and some example code."
msgid "Modify and extend the code to do what you want your new info module to do. See the :ref:`programming tips <developing_modules_best_practices>` and :ref:`Python 3 compatibility <developing_python_3>` pages for pointers on writing clean and concise module code."
msgid "Navigate to the correct directory for your new module: ``$ cd lib/ansible/modules/``. If you are developing a module in a :ref:`collection <developing_collections>`, ``$ cd plugins/modules/`` inside your collection development tree."
msgstr "新しいモジュールの正しいディレクトリーに移動します (``$ cd lib/ansible/modules/``)。:ref:`コレクション <developing_collections>` でモジュールを開発する場合は、コレクション開発ツリー内で ``$ cd plugins/modules/`` を実行します。"
msgid "Paste the content below into your new module file. It includes the :ref:`required Ansible format and documentation <developing_modules_documenting>`, a simple :ref:`argument spec for declaring the module options <argument_spec>`, and some example code."
msgid "Modify and extend the code to do what you want your new module to do. See the :ref:`programming tips <developing_modules_best_practices>` and :ref:`Python 3 compatibility <developing_python_3>` pages for pointers on writing clean and concise module code."
msgid "After you modify the sample code above to do what you want, you can try out your module. Our :ref:`debugging tips <debugging_modules>` will help if you run into bugs as you verify your module code."
msgid "Create an arguments file, a basic JSON config file that passes parameters to your module so that you can run it. Name the arguments file ``/tmp/args.json`` and add the following content:"
msgid "The following two examples will get you started with testing your module code. Please review our :ref:`testing <developing_testing>` section for more detailed information, including instructions for :ref:`testing module documentation <testing_module_documentation>`, adding :ref:`integration tests <testing_integration>`, and more."
msgid "Every new module and plugin should have integration tests, even if the tests cannot be run on Ansible CI infrastructure. In this case, the tests should be marked with the ``unsupported`` alias in `aliases file <https://docs.ansible.com/ansible/latest/dev_guide/testing/sanity/integration-aliases.html>`_."
msgid "Note that this example requires Docker to be installed and running. If you'd rather not use a container for this, you can choose to use ``--venv`` instead of ``--docker``."
msgid "You can add unit tests for your module in ``./test/units/modules``. You must first set up your testing environment. In this example, we're using Python 3.5."
msgid "To run all tests do the following: ``$ ansible-test units --python 3.5``. If you are using a CI environment, these tests will run automatically."
msgstr "すべてのテストを実行するには、``$ ansible-test units --python 3.5`` で CI 環境を使用している場合は、これらのテストが自動的に実行されます。"
msgid "To run pytest against a single test module, you can run the following command. Ensure that you are providing the correct path of the test module:"
msgid "If you would like to contribute to ``ansible-base`` by adding a new feature or fixing a bug, `create a fork <https://help.github.com/articles/fork-a-repo/>`_ of the ansible/ansible repository and develop against a new feature branch using the ``devel`` branch as a starting point. When you you have a good working code change, you can submit a pull request to the Ansible repository by selecting your feature branch as a source and the Ansible devel branch as a target."
msgid "If you want to contribute a module to an :ref:`Ansible collection <contributing_maintained_collections>`, review our :ref:`submission checklist <developing_modules_checklist>`, :ref:`programming tips <developing_modules_best_practices>`, and :ref:`strategy for maintaining Python 2 and Python 3 compatibility <developing_python_3>`, as well as information about :ref:`testing <developing_testing>` before you open a pull request."
msgid "The `cisco.aci collection <https://galaxy.ansible.com/cisco/aci>`_ already includes a large number of Cisco ACI modules, however the ACI object model is huge and covering all possible functionality would easily cover more than 1500 individual modules."
msgid "The first line adds the standard connection parameters to the module. After that, the next section will update the ``argument_spec`` dictionary with module-specific parameters. The module-specific parameters should include:"
msgid "The following section creates an AnsibleModule instance. The module should support check-mode, so we pass the ``argument_spec`` and ``supports_check_mode`` arguments. Since these modules support querying the APIC for all objects of the module's class, the object/parent IDs should only be required if ``state: absent`` or ``state: present``."
msgid "Once the AnsibleModule object has been initiated, the necessary parameter values should be extracted from ``params`` and any data validation should be done. Usually the only params that need to be extracted are those related to the ACI object configuration and its child configuration. If you have integer objects that you would like to validate, then the validation should be done here, and the ``ACIModule.payload()`` method will handle the string conversion."
msgid "The ACIModule class handles most of the logic for the ACI modules. The ACIModule extends functionality to the AnsibleModule object, so the module instance must be passed into the class instantiation."
msgid "The ``construct_url()`` method is used to dynamically build the appropriate URL to interact with the object, and the appropriate filter string that should be appended to the URL to filter the results."
msgid "When the ``state`` is not ``query``, the URL is the base URL to access the APIC plus the distinguished name to access the object. The filter string will restrict the returned data to just the configuration data."
msgid "When ``state`` is ``query``, the URL and filter string used depends on what parameters are passed to the object. This method handles the complexity so that it is easier to add new modules and so that all modules are consistent in what type of data is returned."
msgid "Our design goal is to take all ID parameters that have values, and return the most specific data possible. If you do not supply any ID parameters to the task, then all objects of the class will be returned. If your task does consist of ID parameters sed, then the data for the specific object is returned. If a partial set of ID parameters are passed, then the module will use the IDs that are passed to build the URL and filter strings appropriately."
msgstr "この設計の目的は、値があるすべての ID パラメーターを取り、最も具体的なデータを返すことです。ID パラメーターをタスクに指定しないと、クラスのすべてのオブジェクトが返されます。タスクが ID パラメーターで構成されている場合は、特定のオブジェクトのデータが返されます。ID パラメーターの一部が渡されると、モジュールは URL およびフィルター文字列を適切にビルドするために渡された ID を使用します。"
msgid "**target_filter**: A dictionary with key-value pairs that make up the query string for selecting a subset of entries, for example ``{'name': 'ACME'}``"
msgid "The ``construct_url()`` method takes 4 optional arguments, the first three imitate the root class as described above, but are for child objects:"
msgid "Sometimes the APIC will require special characters ([, ], and -) or will use object metadata in the name (\"vlanns\" for VLAN pools); the module should handle adding special characters or joining of multiple parameters in order to keep expected inputs simple."
msgid "``state: present`` retrieves the configuration to use as a comparison against what was entered in the task. All values that are different than the existing values will be updated."
msgid "When ``state: present``, the module needs to perform a diff against the existing configuration and the task entries. If any value needs to be updated, then the module will make a POST request with only the items that need to be updated. Some modules have children that are in a 1-to-1 relationship with another object; for these cases, the module can be used to manage the child objects."
msgstr "``state: present`` の場合、モジュールは既存の設定とタスクエントリーに対して diff を実行する必要があります。値を更新する必要がある場合は、モジュールは更新が必要なアイテムのみが含まれる POST リクエストを行います。モジュールによっては、別のオブジェクトと 1-to-1 の関係にある子があります。これらの場合、モジュールは子オブジェクトを管理するために使用できます。"
msgid "The ``aci.payload()`` method is used to build a dictionary of the proposed object configuration. All parameters that were not provided a value in the task will be removed from the dictionary (both for the object and its children). Any parameter that does have a value will be converted to a string and added to the final dictionary object that will be used for comparison against the existing configuration."
msgid "The ``get_diff()`` method is used to perform the diff, and takes only one required argument, ``aci_class``. Example: ``aci.get_diff(aci_class='fvBD')``"
msgid "The ``post_config()`` method is used to make the POST request to the APIC if needed. This method doesn't take any arguments and handles check mode. Example: ``aci.post_config()``"
msgstr "``post_config()`` メソッドは、必要に応じて APIC への POST リクエストを行うために使用されます。このメソッドは引数を受け付けず、チェックモードを処理します。以下に例を示します。たとえば、``aci.post_config()`` になります。"
msgid "If the task sets the state to absent, then the ``delete_config()`` method is all that is needed. This method does not take any arguments, and handles check mode."
msgstr "タスクが state を absent に設定すると、``delete_config()`` メソッドのみが必要になります。このメソッドは引数を取らず、チェックモードを処理します。"
msgid "To have the module exit, call the ACIModule method ``exit_json()``. This method automatically takes care of returning the common return values for you."
msgid "Because Windows modules are written in Powershell and need to be run on a Windows host, this guide differs from the usual development walkthrough guide."
msgid "Unlike Python module development which can be run on the host that runs Ansible, Windows modules need to be written and tested for Windows hosts. While evaluation editions of Windows can be downloaded from Microsoft, these images are usually not ready to be used by Ansible without further modification. The easiest way to set up a Windows host so that it is ready to by used by Ansible is to set up a virtual machine using Vagrant. Vagrant can be used to download existing OS images called *boxes* that are then deployed to a hypervisor like VirtualBox. These boxes can either be created and stored offline or they can be downloaded from a central repository called Vagrant Cloud."
msgstr "Ansible を実行するホストで実行できる Python モジュール開発とは異なり、Windows ホスト用に Windows モジュールを作成およびテストする必要があります。Windows の評価エディションを Microsoft からダウンロードできますが、通常はこれらのイメージを追加の変更なしで Ansible で使用することはできません。Ansible で使用する準備が整うように Windows ホストを設定する最も簡単な方法は、Vagrant を使用して仮想マシンを設定することにあります。Vagrant を使用すると、*ボックス* と呼ばれる既存の OS イメージをダウンロードし、VirtualBox のようなハイパーバイザーにデプロイされます。これらのボックスは、オフラインで作成および保存するか、Vagrant Cloud と呼ばれる中央リポジトリーからダウンロードできます。"
msgid "This guide will use the Vagrant boxes created by the `packer-windoze <https://github.com/jborean93/packer-windoze>`_ repository which have also been uploaded to `Vagrant Cloud <https://app.vagrantup.com/boxes/search?utf8=%E2%9C%93&sort=downloads&provider=&q=jborean93>`_. To find out more info on how these images are created, please go to the GitHub repo and look at the ``README`` file."
msgid "Before you can get started, the following programs must be installed (please consult the Vagrant and VirtualBox documentation for installation instructions):"
msgid "This will download the Vagrant box from Vagrant Cloud and add it to the local boxes on your host and then start up that instance in VirtualBox. When starting for the first time, the Windows VM will run through the sysprep process and then create a HTTP and HTTPS WinRM listener automatically. Vagrant will finish its process once the listeners are online, after which the VM can be used by Ansible."
msgid "The port ``55986`` is automatically forwarded by Vagrant to the Windows host that was created, if this conflicts with an existing local port then Vagrant will automatically use another one at random and display show that in the output."
msgstr "ポート ``55986`` は、Vagrant によって作成された Windows ホストに自動的に転送されます。これが既存のローカルポートと競合する場合、Vagrant は自動的に別のポートをランダムに使用し、出力にそれを表示します。"
msgid "When the host is online, it can accessible by RDP on ``127.0.0.1:3389`` but the port may differ depending if there was a conflict. To get rid of the host, run ``vagrant destroy --force`` and Vagrant will automatically remove the VM and any other files associated with that VM."
msgid "While this is useful when testing modules on a single Windows instance, these host won't work without modification with domain based modules. The Vagrantfile at `ansible-windows <https://github.com/jborean93/ansible-windows/tree/master/vagrant>`_ can be used to create a test domain environment to be used in Ansible. This repo contains three files which are used by both Ansible and Vagrant to create multiple Windows hosts in a domain environment. These files are:"
msgstr "これは、単一の Windows インスタンスでモジュールをテストする際に役立ちますが、これらのホストはドメインベースのモジュールで変更せずに動作しません。`ansible-windows <https://github.com/jborean93/ansible-windows/tree/master/vagrant>`_ の Vagrant を使用して、Ansible で使用するテストドメイン環境を作成できます。このリポジトリーには、Ansible と Vagrant で使用されている 3 つのファイルが含まれ、ドメイン環境で複数の Windows ホストを作成するのに使用できます。このファイルは、以下のようになります。"
msgid "The domain name and accounts can be modified by changing the variables ``domain_*`` in the ``inventory.yml`` file if it is required. The inventory file can also be modified to provision more or less servers by changing the hosts that are defined under the ``domain_children`` key. The host variable ``ansible_host`` is the private IP that will be assigned to the VirtualBox host only network adapter while ``vagrant_box`` is the box that will be used to create the VM."
msgid "Vagrant provisions each host sequentially so this can take some time to complete. If any errors occur during the Ansible phase of setting up the domain, run ``vagrant provision`` to rerun just that step."
msgid "Unlike setting up a single Windows instance with Vagrant, these hosts can also be accessed using the IP address directly as well as through the forwarded ports. It is easier to access it over the host only network adapter as the normal protocol ports are used, for example RDP is still over ``3389``. In cases where the host cannot be resolved using the host only network IP, the following protocols can be access over ``127.0.0.1`` using these forwarded ports:"
msgstr "Vagrant で単一の Windows インスタンスをセットアップするのとは異なり、これらのホストは、転送されたポートを介してだけでなく、IP アドレスを使用して直接アクセスすることもできます。ホストのみのネットワークアダプターを使用してアクセスする方が、通常のプロトコルのポートが使用されるため簡単です。たとえば、RDP はまだ ``3389`` でした。ホストのみのネットワーク IP を使用してホストを解決できない場合、以下のプロトコルは、これらの転送されたポートを使用して ``127.0.0.1`` を介してアクセスできます。"
msgid "Replace ``xx`` with the entry number in the inventory file where the domain controller started with ``00`` and is incremented from there. For example, in the default ``inventory.yml`` file, WinRM over HTTPS for ``SERVER2012R2`` is forwarded over port ``29804`` as it's the fourth entry in ``domain_children``."
msgstr "``xx`` を、ドメインコントローラーが ``00`` から開始したインベントリーファイルのエントリー番号で、インクリメントされていきます。たとえば、デフォルトでは、``domain_children`` の 4番目のエントリーであるため、``inventory.yml``ファイル (WinRM over HTTPS for ``SERVER2012R2``) がポート ``29804`` 経由で転送されます。"
msgid "While an SSH server is available on all Windows hosts but Server 2008 (non R2), it is not a support connection for Ansible managing Windows hosts and should not be used with Ansible."
msgstr "SSH サーバーはすべての Windows ホストで利用できますが、Server 2008 (R2 以外) は、Ansible による Windows ホストの管理接続ではなく、Ansible では使用できません。"
msgid "To fail a module, call ``$module.FailJson(\"failure message here\")``, an Exception or ErrorRecord can be set to the second argument for a more descriptive error message"
msgid "Look for common functions in ``./lib/ansible/module_utils/powershell/`` and use the code there instead of duplicating work. These can be imported by adding the line ``#Requires -Module *`` where * is the filename to import, and will be automatically included with the module code sent to the Windows target when run via Ansible"
msgid "As well as PowerShell module utils, C# module utils are stored in ``./lib/ansible/module_utils/csharp/`` and are automatically imported in a module execution if the line ``#AnsibleRequires -CSharpUtil *`` is present"
msgid "C# and PowerShell module utils achieve the same goal but C# allows a developer to implement low level tasks, such as calling the Win32 API, and can be faster in some cases"
msgstr "C# と PowerShell モジュールのユーティリティーは同じ目標を達成しますが、C# を使用すると、開発者は Win32 API の呼び出しなどの低レベルのタスクを実装でき、場合によってはより高速になります。"
msgid "Ensure the code runs under Powershell v3 and higher on Windows Server 2008 and higher; if higher minimum Powershell or OS versions are required, ensure the documentation reflects this clearly"
msgstr "このコードが Windows Server 2008 以降の Powershell v3 以降で動作することを確認してください。最小バージョンより新しい Powershell または OS が必要な場合は、ドキュメントにこの内容が明確に反映されていることを確認してください。"
msgid "Ansible runs modules under strictmode version 2.0. Be sure to test with that enabled by putting ``Set-StrictMode -Version 2.0`` at the top of your dev script"
msgid "A very basic Powershell module `win_environment <https://github.com/ansible-collections/ansible.windows/blob/master/plugins/modules/win_environment.ps1>`_ incorporates best practices for Powershell modules. It demonstrates how to implement check-mode and diff-support, and also shows a warning to the user when a specific condition is met."
msgid "A slightly more advanced module is `win_uri <https://github.com/ansible-collections/ansible.windows/blob/master/plugins/modules/win_uri.ps1>`_ which additionally shows how to use different parameter types (bool, str, int, list, dict, path) and a selection of choices for parameters, how to fail a module and how to handle exceptions."
msgid "As part of the new ``AnsibleModule`` wrapper, the input parameters are defined and validated based on an argument spec. The following options can be set at the root level of the argument spec:"
msgid "An optional fourth element is a boolean that states whether all module options in the third elements are required (default: ``$false``) or only one (``$true``)"
msgid "The actual input options for a module are set within the ``options`` value as a dictionary. The keys of this dictionary are the module option names while the values are the spec of that module option. Each spec can have the following options set:"
msgid "``choices``: A list of valid values for the module option, if ``type=list`` then each list value is validated against the choices and not the list itself"
msgid "``deprecated_aliases``: A list of hashtables that define aliases that are deprecated and the versions they will be removed in. Each entry must contain the keys ``name`` and ``collection_name`` with either ``version`` or ``date``"
msgid "``removed_at_date``: States the date (YYYY-MM-DD) when a deprecated module option will be removed, a warning is displayed to the end user if set"
msgid "``removed_from_collection``: States from which collection the deprecated module option will be removed; must be specified if one of ``removed_in_version`` and ``removed_at_date`` is specified"
msgid "``list``: A list of values, ``elements=<type>`` can convert the individual list value types if set. If ``elements=dict`` then ``options`` is defined, the values will be validated against the argument spec. When the input is a string then the string is split by ``,`` and any whitespace is trimmed"
msgid "``path``: A string where values likes ``%TEMP%`` are expanded based on environment values. If the input value starts with ``\\\\?\\`` then no expansion is run"
msgid "``sid``: Will convert Windows security identifier values or Windows account names to a `SecurityIdentifier <https://docs.microsoft.com/en-us/dotnet/api/system.security.principal.securityidentifier?view=netframework-4.7.2>`_ value"
msgstr "``sid``: Windows セキュリティー識別子の値または Windows アカウント名を `SecurityIdentifier <https://docs.microsoft.com/en-us/dotnet/api/system.security.principal.securityidentifier?view=netframework-4.7.2>`_ 値に変換します。"
msgid "``apply_defaults``: The value is based on the ``options`` spec defaults for that key if ``True`` and null if ``False``. Only valid when the module option is not defined by the user and ``type=dict``."
msgid "A module type can also be a delegate function that converts the value to whatever is required by the module option. For example the following snippet shows how to create a custom type that creates a ``UInt64`` value:"
msgid "PowerShell modules support a small subset of the ``#Requires`` options built into PowerShell as well as some Ansible-specific requirements specified by ``#AnsibleRequires``. These statements can be placed at any point in the script, but are most commonly near the top. They are used to make it easier to state the requirements of the module without writing any of the checks. Each ``requires`` statement must be on its own line, but there can be multiple requires statements in one script."
msgid "``#Requires -Version x.y``: Added in Ansible 2.5, specifies the version of PowerShell that is required by the module. The module will fail if this requirement is not met."
msgid "``#AnsibleRequires -OSVersion x.y``: Added in Ansible 2.5, specifies the OS build version that is required by the module and will fail if this requirement is not met. The actual OS version is derived from ``[Environment]::OSVersion.Version``."
msgstr "``#AnsibleRequires -OSVersion x.y``: Ansible 2.5 で追加され、モジュールが必要とする OS ビルドバージョンを指定します。この要件を満たしていない場合は失敗します。実際の OS バージョンは ``[Environment]::OSVersion.Version`` から由来します。"
msgid "``#AnsibleRequires -Become``: Added in Ansible 2.5, forces the exec runner to run the module with ``become``, which is primarily used to bypass WinRM restrictions. If ``ansible_become_user`` is not specified then the ``SYSTEM`` account is used instead."
msgid "C# module utils can reference other C# utils by adding the line ``using Ansible.<module_util>;`` to the top of the script with all the other using statements."
msgid "Like Python modules, PowerShell modules also provide a number of module utilities that provide helper functions within PowerShell. These module_utils can be imported by adding the following line to a PowerShell module:"
msgid "This will import the module_util at ``./lib/ansible/module_utils/powershell/Ansible.ModuleUtils.Legacy.psm1`` and enable calling all of its functions. As of Ansible 2.8, Windows module utils can also be written in C# and stored at ``lib/ansible/module_utils/csharp``. These module_utils can be imported by adding the following line to a PowerShell module:"
msgid "This will import the module_util at ``./lib/ansible/module_utils/csharp/Ansible.Basic.cs`` and automatically load the types in the executing process. C# module utils can reference each other and be loaded together by adding the following line to the using statements at the top of the util:"
msgstr "これにより、``./lib/ansible/module_utils/csharp/Ansible.Basic.cs`` でモジュールユーティリティーがインポートされ、実行中のプロセスでタイプが自動的に読み込まれます。C# モジュールユーティリティーは相互に参照でき、次の行を、ユーティリティーの上部にある using ステートメントに追加して読み込むことができます。"
msgid "There are special comments that can be set in a C# file for controlling the compilation parameters. The following comments can be added to the script;"
msgid "``//AssemblyReference -Name <assembly dll> [-CLR [Core|Framework]]``: The assembly DLL to reference during compilation, the optional ``-CLR`` flag can also be used to state whether to reference when running under .NET Core, Framework, or both (if omitted)"
msgid "``//NoWarn -Name <error id> [-CLR [Core|Framework]]``: A compiler warning ID to ignore when compiling the code, the optional ``-CLR`` works the same as above. A list of warnings can be found at `Compiler errors <https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/compiler-messages/index>`_"
msgid "A combination of these flags help to make a module util interoperable on both .NET Framework and .NET Core, here is an example of them in action:"
msgid "For more details on any specific module utility and their requirements, please see the `Ansible module utilities source code <https://github.com/ansible/ansible/tree/devel/lib/ansible/module_utils/powershell>`_."
msgid "PowerShell module utilities can be stored outside of the standard Ansible distribution for use with custom modules. Custom module_utils are placed in a folder called ``module_utils`` located in the root folder of the playbook or role directory."
msgid "C# module utilities can also be stored outside of the standard Ansible distribution for use with custom modules. Like PowerShell utils, these are stored in a folder called ``module_utils`` and the filename must end in the extension ``.cs``, start with ``Ansible.`` and be named after the namespace defined in the util."
msgid "The below example is a role structure that contains two PowerShell custom module_utils called ``Ansible.ModuleUtils.ModuleUtil1``, ``Ansible.ModuleUtils.ModuleUtil2``, and a C# util containing the namespace ``Ansible.CustomUtil``::"
msgid "Each PowerShell module_util must contain at least one function that has been exported with ``Export-ModuleMember`` at the end of the file. For example"
msgid "PowerShell module utils can easily expose common module options that a module can use when building its argument spec. This allows common features to be stored and maintained in one location and have those features used by multiple modules with minimal effort. Any new features or bugfixes added to one of these utils are then automatically used by the various modules that call that util."
msgid "An example of this would be to have a module util that handles authentication and communication against an API This util can be used by multiple modules to expose a common set of module options like the API endpoint, username, password, timeout, cert validation, and so on without having to add those options to each module spec."
msgstr "この例としては、認証と API に対する通信を処理するモジュールユーティリティーがあります。このユーティリティーは、API エンドポイント、ユーザー名、パスワード、タイムアウト、認定検証などの共通のモジュールオプションセットを公開するため、各モジュール仕様にそれらのオプションを追加しなくても、複数のモジュールによって使用できます。"
msgid "Because these options can be shared across various module it is highly recommended to keep the module option names and aliases in the shared spec as specific as they can be. For example do not have a util option called ``password``, rather you should prefix it with a unique name like ``acme_password``."
msgid "Failure to have a unique option name or alias can prevent the util being used by module that also use those names or aliases for its own options."
msgid "The following is an example module util called ``ServiceAuth.psm1`` in a collection that implements a common way for modules to authentication with a service."
msgid "Options defined in the module spec will always have precedence over a util spec. Any list values under the same key in a util spec will be appended to the module spec for that same key. Dictionary values will add any keys that are missing from the module spec and merge any values that are lists or dictionaries. This is similar to how the doc fragment plugins work when extending module documentation."
msgid "To document these shared util options for a module, create a doc fragment plugin that documents the options implemented by the module util and extend the module docs for every module that implements the util to include that fragment in its docs."
msgid "Debugging a module currently can only be done on a Windows host. This can be useful when developing a new module or implementing bug fixes. These are some steps that need to be followed to set this up:"
msgstr "現在、モジュールのデバッグは Windows ホストでのみ実行できます。これは、新しいモジュールまたはバグ修正の開発時に便利です。これらの手順は、以下を設定します。"
msgid "Add an extra ``#`` to the start of any ``#Requires -Module`` lines in the module code, this is only required for any lines starting with ``#Requires -Module``"
msgid "Prefix the Ansible command with :envvar:`ANSIBLE_KEEP_REMOTE_FILES=1<ANSIBLE_KEEP_REMOTE_FILES>` to specify that Ansible should keep the exec files on the server."
msgid "In this script is a raw JSON script under ``$json_raw`` which contains the module arguments under ``module_args``. These args can be assigned manually to the ``$complex_args`` variable that is defined on your debug script or put in the ``args.json`` file."
msgid "Integration tests for Ansible modules are typically written as Ansible roles. These test roles are located in ``./test/integration/targets``. You must first set up your testing environment, and configure a test inventory for Ansible to connect to."
msgid "To execute the integration tests, run ``ansible-test windows-integration win_stat``; you can replace ``win_stat`` with the role you want to test."
msgid "This will execute all the tests currently defined for that role. You can set the verbosity level using the ``-v`` argument just as you would with ansible-playbook."
msgid "When developing tests for a new module, it is recommended to test a scenario once in check mode and twice not in check mode. This ensures that check mode does not make any changes but reports a change, as well as that the second run is idempotent and does not report changes. For example:"
msgid "Starting with Ansible 2.10, related modules should be developed in a collection. The Ansible core team and community compiled these module development tips and tricks to help companies developing Ansible modules for their products and users developing Ansible modules for third-party products. See :ref:`developing_collections` for a more detailed description of the collections format and additional development guidelines."
msgid "This list of prerequisites is designed to help ensure that you develop high-quality modules that work well with ansible-base and provide a seamless user experience."
msgid "With great power comes great responsibility: Ansible collection maintainers have a duty to help keep content up to date and release collections they are responsible for regularly. As with all successful community projects, collection maintainers should keep a watchful eye for reported issues and contributions."
msgid "We strongly recommend unit and/or integration tests. Unit tests are especially valuable when external resources (such as cloud or network devices) are required. For more information see :ref:`developing_testing` and the `Testing Working Group <https://github.com/ansible/community/blob/master/meetings/README.md>`_."
msgid "It is convenient if the organization and repository names on GitHub (or elsewhere) match your namespace and collection names on Ansible Galaxy, but it is not required. The plugin names you select, however, are always the same in your code repository and in your collection artifact on Galaxy."
msgid "Circulating your ideas before coding helps you adopt good practices and avoid common mistakes. After reading the \"Before you start coding\" section you should have a reasonable idea of the structure of your modules. Write a list of your proposed plugin and/or module names, with a short description of what each one does. Circulate that list on IRC or a mailing list so the Ansible community can review your ideas for consistency and familiarity. Names and functionality that are consistent, predictable, and familiar make your collection easier to use."
msgid "``#ansible-devel`` - We have found that IRC ``#ansible-devel`` on FreeNode's IRC network works best for developers so we can have an interactive dialogue."
msgid "if needed, one or more ``/plugins/module_utils/$topic.py`` files - Code shared between more than one module, such as common arguments. *Optional*"
msgid "When you have these files ready, review the :ref:`developing_modules_checklist` again. If you are creating a new collection, you are responsible for all procedures related to your repository, including setting rules for contributions, finding reviewers, and testing and maintaining the code in your collection."
msgid "`How to create a Pull Request (PR) <https://help.github.com/articles/about-pull-requests/>`_"
msgstr "`How to create a Pull Request (PR) <https://help.github.com/articles/about-pull-requests/>`_"
#: ../../rst/dev_guide/developing_plugins.rst:6
msgid "Developing plugins"
msgstr "プラグインの開発"
#: ../../rst/dev_guide/developing_plugins.rst:11
msgid "Plugins augment Ansible's core functionality with logic and features that are accessible to all modules. Ansible collections include a number of handy plugins, and you can easily write your own. All plugins must:"
msgid "You must write your plugin in Python so it can be loaded by the ``PluginLoader`` and returned as a Python object that any module can use. Since your plugin will execute on the controller, you must write it in a :ref:`compatible version of Python <control_node_requirements>`."
msgid "You should return errors encountered during plugin execution by raising ``AnsibleError()`` or a similar class with a message describing the error. When wrapping other exceptions into error messages, you should always use the ``to_native`` Ansible function to ensure proper string compatibility across Python versions:"
msgid "Check the different `AnsibleError objects <https://github.com/ansible/ansible/blob/devel/lib/ansible/errors/__init__.py>`_ and see which one applies best to your situation."
msgid "You must convert any strings returned by your plugin into Python's unicode type. Converting to unicode ensures that these strings can run through Jinja2. To convert strings:"
msgid "To define configurable options for your plugin, describe them in the ``DOCUMENTATION`` section of the python file. Callback and connection plugins have declared configuration requirements this way since Ansible version 2.4; most plugin types now do the same. This approach ensures that the documentation of your plugin's options will always be correct and up-to-date. To add a configurable option to your plugin, define it in this format:"
msgid "To access the configuration settings in your plugin, use ``self.get_option(<option_name>)``. For most plugin types, the controller pre-populates the settings. If you need to populate settings explicitly, use a ``self.set_options()`` call."
msgid "Plugins that support embedded documentation (see :ref:`ansible-doc` for the list) should include well-formed doc strings. If you inherit from a plugin, you must document the options it takes, either via a documentation fragment or as a copy. See :ref:`module_documenting` for more information on correct documentation. Thorough documentation is a good idea even if you're developing a plugin for local use."
msgid "From there, execute the module using the ``_execute_module`` method to call the original module. After successful execution of the module, you can modify the module return data."
msgid "For example, if you wanted to check the time difference between your Ansible controller and your target machine(s), you could write an action plugin to check the local time and compare it to the return data from Ansible's ``setup`` module:"
msgid "This code checks the time on the controller, captures the date and time for the remote machine using the ``setup`` module, and calculates the difference between the captured time and the local time, returning the time delta in days, seconds and microseconds."
msgid "For practical examples of action plugins, see the source code for the `action plugins included with Ansible Core <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/action>`_"
msgid "Import cache plugins using the cache_loader so you can use ``self.set_options()`` and ``self.get_option(<option_name>)``. If you import a cache plugin directly in the code base, you can only access options via ``ansible.constants``, and you break the cache plugin's ability to be used by an inventory plugin."
msgid "There are two base classes for cache plugins, ``BaseCacheModule`` for database-backed caches, and ``BaseCacheFileModule`` for file-backed caches."
msgid "To create a cache plugin, start by creating a new ``CacheModule`` class with the appropriate base class. If you're creating a plugin using an ``__init__`` method you should initialize the base class with any provided args and kwargs to be compatible with inventory plugin cache options. The base class calls ``self.set_options(direct=kwargs)``. After the base class ``__init__`` method is called ``self.get_option(<option_name>)`` should be used to access cache options."
msgid "If you use the ``BaseCacheModule``, you must implement the methods ``get``, ``contains``, ``keys``, ``set``, ``delete``, ``flush``, and ``copy``. The ``contains`` method should return a boolean that indicates if the key exists and has not expired. Unlike file-based caches, the ``get`` method does not raise a KeyError if the cache has expired."
msgid "If you use the ``BaseFileCacheModule``, you must implement ``_load`` and ``_dump`` methods that will be called from the base class methods ``get`` and ``set``."
msgid "If your cache plugin stores JSON, use ``AnsibleJSONEncoder`` in the ``_dump`` or ``set`` method and ``AnsibleJSONDecoder`` in the ``_load`` or ``get`` method."
msgid "For example cache plugins, see the source code for the `cache plugins included with Ansible Core <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/cache>`_."
msgid "Callback plugins add new behaviors to Ansible when responding to events. By default, callback plugins control most of the output you see when running the command line programs."
msgid "From there, override the specific methods from the CallbackBase that you want to provide a callback for. For plugins intended for use with Ansible version 2.0 and later, you should only override methods that start with ``v2``. For a complete list of methods that you can override, please see ``__init__.py`` in the `lib/ansible/plugins/callback <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/callback>`_ directory."
msgid "The following is a modified example of how Ansible's timer plugin is implemented, but with an extra option so you can see how configuration works in Ansible version 2.4 and later:"
msgid "Note that the ``CALLBACK_VERSION`` and ``CALLBACK_NAME`` definitions are required for properly functioning plugins for Ansible version 2.0 and later. ``CALLBACK_TYPE`` is mostly needed to distinguish 'stdout' plugins from the rest, since you can only load one plugin that writes to stdout."
msgid "For example callback plugins, see the source code for the `callback plugins included with Ansible Core <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/callback>`_"
msgid "New in ansible-base 2.11, callback plugins are notified (via ``v2_playbook_on_task_start``) of :ref:`meta<meta_module>` tasks. By default, only explicit ``meta`` tasks that users list in their plays are sent to callbacks."
msgid "There are also some tasks which are generated internally and implicitly at various points in execution. Callback plugins can opt-in to receiving these implicit tasks as well, by setting ``self.wants_implicit_tasks = True``. Any ``Task`` object received by a callback hook will have an ``.implicit`` attribute, which can be consulted to determine whether the ``Task`` originated from within Ansible, or explicitly by the user."
msgid "Connection plugins allow Ansible to connect to the target hosts so it can execute tasks on them. Ansible ships with many connection plugins, but only one can be used per host at a time. The most commonly used connection plugins are the ``paramiko`` SSH, native ssh (just called ``ssh``), and ``local`` connection types. All of these can be used in playbooks and with ``/usr/bin/ansible`` to connect to remote machines."
msgid "Ansible version 2.1 introduced the ``smart`` connection plugin. The ``smart`` connection type allows Ansible to automatically select either the ``paramiko`` or ``openssh`` connection plugin based on system capabilities, or the ``ssh`` connection plugin if OpenSSH supports ControlPersist."
msgid "To create a new connection plugin (for example, to support SNMP, Message bus, or other transports), copy the format of one of the existing connection plugins and drop it into ``connection`` directory on your :ref:`local plugin path <local_plugins>`."
msgid "Connection plugins can support common options (such as the ``--timeout`` flag) by defining an entry in the documentation for the attribute name (in this case ``timeout``). If the common option has a non-null default, the plugin should define the same default since a different default would be ignored."
msgid "For example connection plugins, see the source code for the `connection plugins included with Ansible Core <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/connection>`_."
msgid "Filter plugins manipulate data. They are a feature of Jinja2 and are also available in Jinja2 templates used by the ``template`` module. As with all plugins, they can be easily extended, but instead of having a file for each one you can have several per file. Most of the filter plugins shipped with Ansible reside in a ``core.py``."
msgid "For example filter plugins, see the source code for the `filter plugins included with Ansible Core <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/filter>`_."
msgid "Inventory plugins parse inventory sources and form an in-memory representation of the inventory. Inventory plugins were added in Ansible version 2.4."
msgid "Lookup plugins pull in data from external data stores. Lookup plugins can be used within playbooks both for looping --- playbook language constructs like ``with_fileglob`` and ``with_items`` are implemented via lookup plugins --- and to return values into a variable or parameter."
msgid "Lookup plugins are very flexible, allowing you to retrieve and return any type of data. When writing lookup plugins, always return data of a consistent type that can be easily consumed in a playbook. Avoid parameters that change the returned data type. If there is a need to return a single value sometimes and a complex dictionary other times, write two different lookup plugins."
msgid "Ansible includes many :ref:`filters <playbooks_filters>` which can be used to manipulate the data returned by a lookup plugin. Sometimes it makes sense to do the filtering inside the lookup plugin, other times it is better to return results that can be filtered in the playbook. Keep in mind how the data will be referenced when determining the appropriate level of filtering to be done inside the lookup plugin."
msgid "The following is an example of how this lookup is called:"
msgstr "以下は、このルックアップがどのように呼び出されるかの例になります。"
#: ../../rst/dev_guide/developing_plugins.rst:408
msgid "For example lookup plugins, see the source code for the `lookup plugins included with Ansible Core <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/lookup>`_."
msgid "Test plugins verify data. They are a feature of Jinja2 and are also available in Jinja2 templates used by the ``template`` module. As with all plugins, they can be easily extended, but instead of having a file for each one you can have several per file. Most of the test plugins shipped with Ansible reside in a ``core.py``. These are specially useful in conjunction with some filter plugins like ``map`` and ``select``; they are also available for conditional directives like ``when:``."
msgid "Test plugins do not use the standard configuration and documentation system described above."
msgstr "Test プラグインは、上記の標準設定およびドキュメントシステムを使用しません。"
#: ../../rst/dev_guide/developing_plugins.rst:421
msgid "For example test plugins, see the source code for the `test plugins included with Ansible Core <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/test>`_."
msgid "Vars plugins inject additional variable data into Ansible runs that did not come from an inventory source, playbook, or command line. Playbook constructs like 'host_vars' and 'group_vars' work using vars plugins."
msgid "Vars plugins were partially implemented in Ansible 2.0 and rewritten to be fully implemented starting with Ansible 2.4. Vars plugins are unsupported by collections."
msgid "Ansible 2.0 did not pass passwords to older plugins, so vaults were unavailable. Most of the work now happens in the ``get_vars`` method which is called from the VariableManager when needed."
msgid "path: this is 'directory data' for every inventory source and the current play's playbook directory, so they can search for data in reference to them. ``get_vars`` will be called at least once per available path."
msgid "entities: these are host or group names that are pertinent to the variables needed. The plugin will get called once for hosts and again for groups."
msgid "Since Ansible version 2.4, vars plugins only execute as needed when preparing to execute a task. This avoids the costly 'always execute' behavior that occurred during inventory construction in older versions of Ansible. Since Ansible version 2.10, vars plugin execution can be toggled by the user to run when preparing to execute a task or after importing an inventory source."
msgid "You can create vars plugins that are not enabled by default using the class variable ``REQUIRES_ENABLED``. If your vars plugin resides in a collection, it cannot be enabled by default. You must use ``REQUIRES_ENABLED`` in all collections-based vars plugins. To require users to enable your plugin, set the class variable ``REQUIRES_ENABLED``:"
msgstr "クラス変数 ``REQUIRES_ENABLED`` を使用して、デフォルトで有効になっていない vars プラグインを作成できます。vars プラグインがコレクションに存在する場合は、デフォルトで有効にはできません。すべてのコレクションベースの vars プラグインで ``REQUIRES_ENABLED`` を使用する必要があります。ユーザーがプラグインを有効にするには、クラス変数 ``REQUIRES_ENABLED`` を設定します。"
#: ../../rst/dev_guide/developing_plugins.rst:465
msgid "Include the ``vars_plugin_staging`` documentation fragment to allow users to determine when vars plugins run."
msgstr "``vars_plugin_staging`` ドキュメントフラグメントを追加して、ユーザーが when vars プラグインの実行を判別できるようにします。"
#: ../../rst/dev_guide/developing_plugins.rst:485
msgid "For example vars plugins, see the source code for the `vars plugins included with Ansible Core <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/vars>`_."
msgstr "vars プラグインの例は、`Ansible Core に含まれる vars プラグイン <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/vars>`_ のソースコードを参照してください。"
#: ../../rst/dev_guide/developing_plugins.rst:495
msgid "Learn about how to develop dynamic inventory sources"
msgid "If you are working on the ``ansible-base`` code, writing an Ansible module, or developing an action plugin, you may need to understand how Ansible's program flow executes. If you are just using Ansible Modules in playbooks, you can skip this section."
msgid "Ansible supports several different types of modules in its code base. Some of these are for backwards compatibility and others are to enable flexibility."
msgid "Action plugins look like modules to anyone writing a playbook. Usage documentation for most action plugins lives inside a module of the same name. Some action plugins do all the work, with the module providing only documentation. Some action plugins execute modules. The ``normal`` action plugin executes modules that don't have special action plugins. Action plugins always execute on the controller."
msgid "Some action plugins do all their work on the controller. For example, the :ref:`debug <debug_module>` action plugin (which prints text for the user to see) and the :ref:`assert <assert_module>` action plugin (which tests whether values in a playbook satisfy certain criteria) execute entirely on the controller."
msgid "Most action plugins set up some values on the controller, then invoke an actual module on the managed node that does something with these values. For example, the :ref:`template <template_module>` action plugin takes values from the user to construct a file in a temporary location on the controller using variables from the playbook environment. It then transfers the temporary file to a temporary file on the remote system. After that, it invokes the :ref:`copy module <copy_module>` which operates on the remote system to move the file into its final location, sets file permissions, and so on."
msgid "All of the modules that ship with Ansible fall into this category. While you can write modules in any language, all official modules (shipped with Ansible) use either Python or PowerShell."
msgid "New-style modules have the arguments to the module embedded inside of them in some manner. Old-style modules must copy a separate file over to the managed node, which is less efficient as it requires two over-the-wire connections instead of only one."
msgid "New-style Python modules use the :ref:`Ansiballz` framework for constructing modules. These modules use imports from :code:`ansible.module_utils` to pull in boilerplate module code, such as argument parsing, formatting of return values as :term:`JSON`, and various file operations."
msgid "In Ansible, up to version 2.0.x, the official Python modules used the :ref:`module_replacer` framework. For module authors, :ref:`Ansiballz` is largely a superset of :ref:`module_replacer` functionality, so you usually do not need to understand the differences between them."
msgid "New-style PowerShell modules use the :ref:`module_replacer` framework for constructing modules. These modules get a library of PowerShell code embedded in them before being sent to the managed node."
msgid "These modules are scripts that include the string ``<<INCLUDE_ANSIBLE_MODULE_JSON_ARGS>>`` in their body. This string is replaced with the JSON-formatted argument string. These modules typically set a variable to that value like this:"
msgid "Ansible outputs a :term:`JSON` string with bare quotes. Double quotes are used to quote string values, double quotes inside of string values are backslash escaped, and single quotes may appear unescaped inside of a string value. To use JSONARGS, your scripting language must have a way to handle this type of string. The example uses Python's triple quoted strings to do this. Other scripting languages may have a similar quote character that won't be confused by any quotes in the JSON or it may allow you to define your own start-of-quote and end-of-quote characters. If the language doesn't give you any of these then you'll need to write a :ref:`non-native JSON module <flow_want_json_modules>` or :ref:`Old-style module <flow_old_style_modules>` instead."
msgid "These modules typically parse the contents of ``json_arguments`` using a JSON library and then use them as native variables throughout the code."
msgid "If a module has the string ``WANT_JSON`` in it anywhere, Ansible treats it as a non-native module that accepts a filename as its only command line parameter. The filename is for a temporary file containing a :term:`JSON` string containing the module's parameters. The module needs to open the file, read and parse the parameters, operate on the data, and print its return data as a JSON encoded dictionary to stdout before exiting."
msgid "Examples of Non-native modules written in ruby are in the `Ansible for Rubyists <https://github.com/ansible/ansible-for-rubyists>`_ repository."
msgstr "Ruby で書かれた非ネイティブモジュールの例は、`Ansible for Rubyists <https://github.com/ansible/ansible-for-rubyists>`_ リポジトリーにあります。"
msgid "From Ansible 2.2 onwards, modules may also be small binary programs. Ansible doesn't perform any magic to make these portable to different systems so they may be specific to the system on which they were compiled or require other binary runtime dependencies. Despite these drawbacks, you may have to compile a custom module against a specific binary library if that's the only way to get access to certain resources."
msgid "One example of a `binary module <https://github.com/ansible/ansible/blob/devel/test/integration/targets/binary_modules/library/helloworld.go>`_ written in go."
msgid "Old-style modules are similar to :ref:`want JSON modules <flow_want_json_modules>`, except that the file that they take contains ``key=value`` pairs for their parameters instead of :term:`JSON`. Ansible decides that a module is old-style when it doesn't have any of the markers that would show that it is one of the other types."
msgid "When a user uses :program:`ansible` or :program:`ansible-playbook`, they specify a task to execute. The task is usually the name of a module along with several parameters to be passed to the module. Ansible takes these values and processes them in various ways before they are finally executed on the remote machine."
msgid "The TaskExecutor receives the module name and parameters that were parsed from the :term:`playbook <playbooks>` (or from the command line in the case of :command:`/usr/bin/ansible`). It uses the name to decide whether it's looking at a module or an :ref:`Action Plugin <flow_action_plugins>`. If it's a module, it loads the :ref:`Normal Action Plugin <flow_normal_action_plugin>` and passes the name, variables, and other information about the task and play to that Action Plugin for further processing."
msgid "The ``normal`` action plugin executes the module on the remote host. It is the primary coordinator of much of the work to actually execute the module on the managed machine."
msgid "It works with other plugins (connection, shell, become, other action plugins) to create any temporary files on the remote machine and cleans up afterwards."
msgid "It pushes the module and module parameters to the remote host, although the :ref:`module_common <flow_executor_module_common>` code described in the next section decides which format those will take."
msgid "It handles any special cases regarding modules (for instance, async execution, or complications around Windows modules that must have the same names as Python modules, so that internal calling of modules from other Action Plugins work.)"
msgstr "モジュールに関する特殊なケースを処理します (たとえば、非同期実行や、Python モジュールと同じ名前を持たなければならない Windows モジュールの複雑さなど。これにより、他のアクションプラグインからのモジュールの内部呼び出しが機能します)。"
msgid "Much of this functionality comes from the `BaseAction` class, which lives in :file:`plugins/action/__init__.py`. It uses the ``Connection`` and ``Shell`` objects to do its work."
msgid "When :term:`tasks <tasks>` are run with the ``async:`` parameter, Ansible uses the ``async`` Action Plugin instead of the ``normal`` Action Plugin to invoke it. That program flow is currently not documented. Read the source for information on how that works."
msgid "Code in :file:`executor/module_common.py` assembles the module to be shipped to the managed node. The module is first read in, then examined to determine its type:"
msgid ":ref:`PowerShell <flow_powershell_modules>` and :ref:`JSON-args modules <flow_jsonargs_modules>` are passed through :ref:`Module Replacer <module_replacer>`."
msgid ":ref:`Non-native-want-JSON <flow_want_json_modules>`, :ref:`Binary modules <flow_binary_modules>`, and :ref:`Old-Style modules <flow_old_style_modules>` aren't touched by either of these and pass through unchanged."
msgid "After the assembling step, one final modification is made to all modules that have a shebang line. Ansible checks whether the interpreter in the shebang line has a specific path configured via an ``ansible_$X_interpreter`` inventory variable. If it does, Ansible substitutes that path for the interpreter path given in the module. After this, Ansible returns the complete module data and the module type to the :ref:`Normal Action <flow_normal_action_plugin>` which continues execution of the module."
msgid "The Module Replacer framework is the original framework implementing new-style modules, and is still used for PowerShell modules. It is essentially a preprocessor (like the C Preprocessor for those familiar with that programming language). It does straight substitutions of specific substring patterns in the module file. There are two types of substitutions:"
msgstr "モジュール置換フレームワークは、新しいスタイルモジュールを実装し、引き続き PowerShell モジュール向けに使用されています。基本的には、(そのプログラミング言語に精通している C プロセッサーなど) です。モジュールファイル内の特定のサブストリングパターンを直接置換します。置換には 2 つのタイプがあります。"
msgid "Replacements that only happen in the module file. These are public replacement strings that modules can utilize to get helpful boilerplate or access to arguments."
msgid ":code:`from ansible.module_utils.MOD_LIB_NAME import *` is replaced with the contents of the :file:`ansible/module_utils/MOD_LIB_NAME.py` These should only be used with :ref:`new-style Python modules <flow_python_modules>`."
msgid ":code:`#<<INCLUDE_ANSIBLE_MODULE_COMMON>>` is equivalent to :code:`from ansible.module_utils.basic import *` and should also only apply to new-style Python modules."
msgid ":code:`# POWERSHELL_COMMON` substitutes the contents of :file:`ansible/module_utils/powershell.ps1`. It should only be used with :ref:`new-style Powershell modules <flow_powershell_modules>`."
msgid "Replacements that are used by ``ansible.module_utils`` code. These are internal replacement patterns. They may be used internally, in the above public replacements, but shouldn't be used directly by modules."
msgid ":code:`\"<<ANSIBLE_VERSION>>\"` is substituted with the Ansible version. In :ref:`new-style Python modules <flow_python_modules>` under the :ref:`Ansiballz` framework the proper way is to instead instantiate an `AnsibleModule` and then access the version from :attr:``AnsibleModule.ansible_version``."
msgid ":code:`\"<<INCLUDE_ANSIBLE_MODULE_COMPLEX_ARGS>>\"` is substituted with a string which is the Python ``repr`` of the :term:`JSON` encoded module parameters. Using ``repr`` on the JSON string makes it safe to embed in a Python file. In new-style Python modules under the Ansiballz framework this is better accessed by instantiating an `AnsibleModule` and then using :attr:`AnsibleModule.params`."
msgid ":code:`<<SELINUX_SPECIAL_FILESYSTEMS>>` substitutes a string which is a comma separated list of file systems which have a file system dependent security context in SELinux. In new-style Python modules, if you really need this you should instantiate an `AnsibleModule` and then use :attr:`AnsibleModule._selinux_special_fs`. The variable has also changed from a comma separated string of file system names to an actual python list of filesystem names."
msgid ":code:`<<INCLUDE_ANSIBLE_MODULE_JSON_ARGS>>` substitutes the module parameters as a JSON string. Care must be taken to properly quote the string as JSON data may contain quotes. This pattern is not substituted in new-style Python modules as they can get the module parameters another way."
msgid "The string :code:`syslog.LOG_USER` is replaced wherever it occurs with the ``syslog_facility`` which was named in :file:`ansible.cfg` or any ``ansible_syslog_facility`` inventory variable that applies to this host. In new-style Python modules this has changed slightly. If you really need to access it, you should instantiate an `AnsibleModule` and then use :attr:`AnsibleModule._syslog_facility` to access it. It is no longer the actual syslog facility and is now the name of the syslog facility. See the :ref:`documentation on internal arguments <flow_internal_arguments>` for details."
msgid "The Ansiballz framework was adopted in Ansible 2.1 and is used for all new-style Python modules. Unlike the Module Replacer, Ansiballz uses real Python imports of things in :file:`ansible/module_utils` instead of merely preprocessing the module. It does this by constructing a zipfile -- which includes the module file, files in :file:`ansible/module_utils` that are imported by the module, and some boilerplate to pass in the module's parameters. The zipfile is then Base64 encoded and wrapped in a small Python script which decodes the Base64 encoding and places the zipfile into a temp directory on the managed node. It then extracts just the Ansible module script from the zip file and places that in the temporary directory as well. Then it sets the PYTHONPATH to find Python modules inside of the zip file and imports the Ansible module as the special name, ``__main__``. Importing it as ``__main__`` causes Python to think that it is executing a script rather than simply importing a module. This lets Ansible run both the wrapper script and the module code in a single copy of Python on the remote machine."
msgid "so that pipelining will function properly. Pipelining needs to pipe the Python module into the Python interpreter on the remote node. Python understands scripts on stdin but does not understand zip files."
msgid "Prior to Ansible 2.7, the module was executed via a second Python interpreter instead of being executed inside of the same process. This change was made once Python-2.4 support was dropped to speed up module execution."
msgid "In Ansiballz, any imports of Python modules from the :py:mod:`ansible.module_utils` package trigger inclusion of that Python file into the zipfile. Instances of :code:`#<<INCLUDE_ANSIBLE_MODULE_COMMON>>` in the module are turned into :code:`from ansible.module_utils.basic import *` and :file:`ansible/module-utils/basic.py` is then included in the zipfile. Files that are included from :file:`module_utils` are themselves scanned for imports of other Python modules from :file:`module_utils` to be included in the zipfile as well."
msgstr "Ansiballzでは、：:py:mod:`ansible.module_utils` パッケージからの Python モジュールのインポートにより、その Python ファイルを zip ファイルに含めることを誘発します。モジュール内の :code:`#<<INCLUDE_ANSIBLE_MODULE_COMMON>>` のインスタンスは :code:`from ansible.module_utils.basic import *` に変換され、その後 :file:`ansible/module-utils/basic.py` が zip ファイルに含まれます。:file:`module_utils` から同梱されるファイルは、それ自体が :file:`module_utils` からの他の Python モジュールのインポートをスキャンし、同じように zip ファイルに同梱されます。"
msgid "At present, the Ansiballz Framework cannot determine whether an import should be included if it is a relative import. Always use an absolute import that has :py:mod:`ansible.module_utils` in it to allow Ansiballz to determine that the file should be included."
msgid "In :ref:`Ansiballz`, the JSON-ified string is part of the script which wraps the zipfile. Just before the wrapper script imports the Ansible module as ``__main__``, it monkey-patches the private, ``_ANSIBLE_ARGS`` variable in ``basic.py`` with the variable values. When a :class:`ansible.module_utils.basic.AnsibleModule` is instantiated, it parses this string and places the args into :attr:`AnsibleModule.params` where it can be accessed by the module's other code."
msgid "If you are writing modules, remember that the way we pass arguments is an internal implementation detail: it has changed in the past and will change again as soon as changes to the common module_utils code allow Ansible modules to forgo using :class:`ansible.module_utils.basic.AnsibleModule`. Do not rely on the internal global ``_ANSIBLE_ARGS`` variable."
msgid "Very dynamic custom modules which need to parse arguments before they instantiate an ``AnsibleModule`` may use ``_load_params`` to retrieve those parameters. Although ``_load_params`` may change in breaking ways if necessary to support changes in the code, it is likely to be more stable than either the way we pass parameters or the internal global variable."
msgid "Prior to Ansible 2.7, the Ansible module was invoked in a second Python interpreter and the arguments were then passed to the script over the script's stdin."
msgid "Both :ref:`module_replacer` and :ref:`Ansiballz` send additional arguments to the module beyond those which the user specified in the playbook. These additional arguments are internal parameters that help implement global Ansible features. Modules often do not need to know about these explicitly as the features are implemented in :py:mod:`ansible.module_utils.basic` but certain features need support from the module so it's good to know about them."
msgid "The internal arguments listed here are global. If you need to add a local internal argument to a custom module, create an action plugin for that specific module - see ``_original_basename`` in the `copy action plugin <https://github.com/ansible/ansible/blob/devel/lib/ansible/plugins/action/copy.py#L329>`_ for an example."
msgid "Boolean. Set to True whenever a parameter in a task or play specifies ``no_log``. Any module that calls :py:meth:`AnsibleModule.log` handles this automatically. If a module implements its own logging then it needs to check this value. To access in a module, instantiate an ``AnsibleModule`` and then check the value of :attr:`AnsibleModule.no_log`."
msgid "Boolean. Turns more verbose logging on or off and turns on logging of external commands that the module executes. If a module uses :py:meth:`AnsibleModule.debug` rather than :py:meth:`AnsibleModule.log` then the messages are only logged if ``_ansible_debug`` is set to ``True``. To set, add ``debug: True`` to :file:`ansible.cfg` or set the environment variable :envvar:`ANSIBLE_DEBUG`. To access in a module, instantiate an ``AnsibleModule`` and access :attr:`AnsibleModule._debug`."
msgid "Boolean. If a module supports it, tells the module to show a unified diff of changes to be made to templated files. To set, pass the ``--diff`` command line option. To access in a module, instantiate an `AnsibleModule` and access :attr:`AnsibleModule._diff`."
msgid "List. Names of filesystems which should have a special SELinux context. They are used by the `AnsibleModule` methods which operate on files (changing attributes, moving, and copying). To set, add a comma separated string of filesystem names in :file:`ansible.cfg`::"
msgid "Most modules can use the built-in ``AnsibleModule`` methods to manipulate files. To access in a module that needs to know about these special context filesystems, instantiate an ``AnsibleModule`` and examine the list in :attr:`AnsibleModule._selinux_special_fs`."
msgid "This replaces :attr:`ansible.module_utils.basic.SELINUX_SPECIAL_FS` from :ref:`module_replacer`. In module replacer it was a comma separated string of filesystem names. Under Ansiballz it's an actual list."
msgid "This parameter controls which syslog facility Ansible module logs to. To set, change the ``syslog_facility`` value in :file:`ansible.cfg`. Most modules should just use :meth:`AnsibleModule.log` which will then make use of this. If a module has to use this on its own, it should instantiate an `AnsibleModule` and then retrieve the name of the syslog facility from :attr:`AnsibleModule._syslog_facility`. The Ansiballz code is less hacky than the old :ref:`module_replacer` code:"
msgid "This parameter passes the version of Ansible that runs the module. To access it, a module should instantiate an `AnsibleModule` and then retrieve it from :attr:`AnsibleModule.ansible_version`. This replaces :attr:`ansible.module_utils.basic.ANSIBLE_VERSION` from :ref:`module_replacer`."
msgid "At the end of a module's execution, it formats the data that it wants to return as a JSON string and prints the string to its stdout. The normal action plugin receives the JSON string, parses it into a Python dictionary, and returns it to the executor."
msgid "If Ansible templated every string return value, it would be vulnerable to an attack from users with access to managed nodes. If an unscrupulous user disguised malicious code as Ansible return value strings, and if those strings were then templated on the controller, Ansible could execute arbitrary code. To prevent this scenario, Ansible marks all strings inside returned data as ``Unsafe``, emitting any Jinja2 templates in the strings verbatim, not expanded by Jinja2."
msgid "Strings returned by invoking a module through ``ActionPlugin._execute_module()`` are automatically marked as ``Unsafe`` by the normal action plugin. If another action plugin retrieves information from a module through some other means, it must mark its return data as ``Unsafe`` on its own."
msgid "In case a poorly-coded action plugin fails to mark its results as \"Unsafe,\" Ansible audits the results again when they are returned to the executor, marking all strings as ``Unsafe``. The normal action plugin protects itself and any other code that it calls with the result data as a parameter. The check inside the executor protects the output of all other action plugins, ensuring that subsequent tasks run by Ansible will not template anything from those results either."
msgid "it can write out the module to a temporary file on the remote host and then use a second connection to the remote host to execute it with the interpreter that the module needs"
msgid "Pipelining only works with modules written in Python at this time because Ansible only knows that Python supports this mode of operation. Supporting pipelining means that whatever format the module payload takes before being sent over the wire must be executable by Python via stdin."
msgid "When combined with :ref:`ANSIBLE_PIPELINING`, this keeps the module's arguments from temporarily being saved onto disk on the remote machine. This makes it harder (but not impossible) for a malicious user on the remote machine to steal any sensitive information that may be present in the arguments."
msgid "Environment variables are usually more secure than the commandline but some systems limit the total size of the environment. This could lead to truncation of the parameters if we hit that limit."
msgid "``elements`` works in combination with ``type`` when ``type='list'``. ``elements`` can then be defined as ``elements='int'`` or any other type, indicating that each element of the specified list should be of that type."
msgid "The ``default`` option allows sets a default value for the argument for the scenario when the argument is not provided to the module. When not specified, the default value is ``None``."
msgid "``fallback`` accepts a ``tuple`` where the first argument is a callable (function) that will be used to perform the lookup, based on the second argument. The second argument is a list of values to be accepted by the callable."
msgid "The most common callable used is ``env_fallback`` which will allow an argument to optionally use an environment variable when the argument is not supplied."
msgid "``required`` accepts a boolean, either ``True`` or ``False`` that indicates that the argument is required. When not specified, ``required`` defaults to ``False``. This should not be used in combination with ``default``."
msgid "``no_log`` accepts a boolean, either ``True`` or ``False``, that indicates explicitly whether or not the argument value should be masked in logs and output."
msgid "In the absence of ``no_log``, if the parameter name appears to indicate that the argument value is a password or passphrase (such as \"admin_password\"), a warning will be shown and the value will be masked in logs but **not** output. To disable the warning and masking for parameters that do not contain sensitive information, set ``no_log`` to ``False``."
msgid "``aliases`` accepts a list of alternative argument names for the argument, such as the case where the argument is ``name`` but the module accepts ``aliases=['pkg']`` to allow ``pkg`` to be interchangeably with ``name``"
msgid "``options`` implements the ability to create a sub-argument_spec, where the sub options of the top level argument are also validated using the attributes discussed in this section. The example at the top of this section demonstrates use of ``options``. ``type`` or ``elements`` should be ``dict`` is this case."
msgid "``apply_defaults`` works alongside ``options`` and allows the ``default`` of the sub-options to be applied even when the top-level argument is not supplied."
msgid "In the example of the ``argument_spec`` at the top of this section, it would allow ``module.params['top_level']['second_level']`` to be defined, even if the user does not provide ``top_level`` when calling the module."
msgid "``removed_in_version`` indicates which version of ansible-base or a collection a deprecated argument will be removed in. Mutually exclusive with ``removed_at_date``, and must be used with ``removed_from_collection``."
msgid "``removed_at_date`` indicates that a deprecated argument will be removed in a minor ansible-base release or major collection release after this date. Mutually exclusive with ``removed_in_version``, and must be used with ``removed_from_collection``."
msgid "Specifies which collection (or ansible-base) deprecates this deprecated argument. Specify ``ansible.builtin`` for ansible-base, or the collection's name (format ``foo.bar``). Must be used with ``removed_in_version`` or ``removed_at_date``."
msgid "The a date after which a minor release of ansible-base or a major collection release will no longer contain this alias.. Either ``version`` or ``date`` must be specified."
msgid "Specifies which collection (or ansible-base) deprecates this deprecated alias. Specify ``ansible.builtin`` for ansible-base, or the collection's name (format ``foo.bar``). Must be used with ``version`` or ``date``."
msgid "If ``options`` is specified, ``mutually_exclusive`` refers to the sub-options described in ``options`` and behaves as in :ref:`argument_spec_dependencies`."
msgid "If ``options`` is specified, ``required_together`` refers to the sub-options described in ``options`` and behaves as in :ref:`argument_spec_dependencies`."
msgid "If ``options`` is specified, ``required_one_of`` refers to the sub-options described in ``options`` and behaves as in :ref:`argument_spec_dependencies`."
msgid "If ``options`` is specified, ``required_if`` refers to the sub-options described in ``options`` and behaves as in :ref:`argument_spec_dependencies`."
msgid "If ``options`` is specified, ``required_by`` refers to the sub-options described in ``options`` and behaves as in :ref:`argument_spec_dependencies`."
msgid "Must be a sequence (list or tuple) of sequences of strings. Every sequence of strings is a list of option names which are mutually exclusive. If more than one options of a list are specified together, Ansible will fail the module with an error."
msgid "In this example, the options ``path`` and ``content`` must not specified at the same time. Also the options ``repository_url`` and ``repository_filename`` must not be specified at the same time. But specifying ``path`` and ``repository_url`` is accepted."
msgid "Must be a sequence (list or tuple) of sequences of strings. Every sequence of strings is a list of option names which are must be specified together. If at least one of these options are specified, the other ones from the same sequence must all be present."
msgid "In this example, if one of the options ``file_path`` or ``file_hash`` is specified, Ansible will fail the module with an error if the other one is not specified."
msgid "Must be a sequence (list or tuple) of sequences of strings. Every sequence of strings is a list of option names from which at least one must be specified. If none one of these options are specified, Ansible will fail module execution."
msgid "In this example, at least one of ``path`` and ``content`` must be specified. If none are specified, execution will fail. Specifying both is explicitly allowed; to prevent this, combine ``required_one_of`` with ``mutually_exclusive``."
msgid "Must be a sequence of sequences. Every inner sequence describes one conditional dependency. Every sequence must have three or four values. The first two values are the option's name and the option's value which describes the condition. The further elements of the sequence are only needed if the option of that name has precisely this value."
msgid "In this example, if the user specifies ``state=present``, at least one of the options ``path`` and ``content`` must be supplied (or both). To make sure that precisely one can be specified, combine ``required_if`` with ``mutually_exclusive``."
msgid "On the other hand, if ``force`` (a boolean parameter) is set to ``true``, ``yes`` etc., both ``force_reason`` and ``force_code`` must be specified."
msgid "Must be a dictionary mapping option names to sequences of option names. If the option name in a dictionary key is specified, the option names it maps to must all also be specified. Note that instead of a sequence of option names, you can also specify one single option name."
msgid "In the example, if ``force`` is specified, ``force_reason`` must also be specified. Also, if ``path`` is specified, then three three options ``mode``, ``owner`` and ``group`` also must be specified."
msgid "The module can determine whether it is called in check mode by checking the boolean value ``module.check_mode``. If it evaluates to ``True``, the module must take care not to do any modification."
msgid "If ``supports_check_mode=False`` is specified, which is the default value, the module will exit in check mode with ``skipped=True`` and message ``remote module (<insert module name here>) does not support check mode``."
msgstr "``supports_check_mode=False`` が指定されている場合 (デフォルト値)、モジュールはチェックモードで ``skipped=True`` および ``remote module (<insert module name here>) does not support check mode`` メッセージで終了します。"
msgid "You can find `a list of all file options here <https://github.com/ansible/ansible/blob/devel/lib/ansible/plugins/doc_fragments/files.py>`_. It is recommended that you make your ``DOCUMENTATION`` extend the doc fragment ``ansible.builtin.files`` (see :ref:`module_docs_fragments`) in this case, to make sure that all these fields are correctly documented."
msgstr "`a list of all file options here <https://github.com/ansible/ansible/blob/devel/lib/ansible/plugins/doc_fragments/files.py>`_ を確認できます。今回は、``DOCUMENTATION`` がドキュメントフラグメント ``ansible.builtin.files`` (:ref:`module_docs_fragments`を参照) を拡張し、これらのフィールドがすべて正しく文書化されていることを確認することが推奨されます。"
msgid "The helper functions ``module.load_file_common_arguments()`` and ``module.set_fs_attributes_if_different()`` can be used to handle these arguments for you:"
msgid "The ``ansible-base`` code runs on both Python 2 and Python 3 because we want Ansible to be able to manage a wide variety of machines. Contributors to ansible-base and to Ansible Collections should be aware of the tips in this document so that they can write code that will run on the same versions of Python as the rest of Ansible."
msgid "To ensure that your code runs on Python 3 as well as on Python 2, learn the tips and tricks and idioms described here. Most of these considerations apply to all three types of Ansible code:"
msgid "However, the three types of code do not use the same string strategy. If you're developing a module or some ``module_utils`` code, be sure to read the section on string strategy carefully."
msgid "Minimum version of Python 3.x and Python 2.x"
msgstr "Python 3.x および Python 2.x の最小バージョン"
#: ../../rst/dev_guide/developing_python_3.rst:25
msgid "On the controller we support Python 3.5 or greater and Python 2.7 or greater. Module-side, we support Python 3.5 or greater and Python 2.6 or greater."
msgid "Python 3.5 was chosen as a minimum because it is the earliest Python 3 version adopted as the default Python by a Long Term Support (LTS) Linux distribution (in this case, Ubuntu-16.04). Previous LTS Linux distributions shipped with a Python 2 version which users can rely upon instead of the Python 3 version."
msgstr "Python 3.5 は、長期サポート (LTS: Long Term Support) の Linux ディストリビューション (この場合は Ubuntu-16.04) でデフォルトの Python として採用されている最も古い Python 3 のバージョンであるため、最小バージョンとして採用されました。以前の LTS Linux ディストリビューションでは、Python 3 バージョンの代わりに、ユーザーが代わりに使用できる Python 2 バージョンが同梱されていました。"
#: ../../rst/dev_guide/developing_python_3.rst:33
msgid "For Python 2, the default is for modules to run on at least Python 2.6. This allows users with older distributions that are stuck on Python 2.6 to manage their machines. Modules are allowed to drop support for Python 2.6 when one of their dependent libraries requires a higher version of Python. This is not an invitation to add unnecessary dependent libraries in order to force your module to be usable only with a newer version of Python; instead it is an acknowledgment that some libraries (for instance, boto3 and docker-py) will only function with a newer version of Python."
msgid "Support for Python 2.4 and Python 2.5 was dropped in Ansible-2.4. RHEL-5 (and its rebuilds like CentOS-5) were supported until April of 2017. Ansible-2.3 was released in April of 2017 and was the last Ansible release to support Python 2.4 on the module-side."
msgid "The best place to start learning about writing code that supports both Python 2 and Python 3 is `Lennart Regebro's book: Porting to Python 3 <http://python3porting.com/>`_. The book describes several strategies for porting to Python 3. The one we're using is `to support Python 2 and Python 3 from a single code base <http://python3porting.com/strategies.html#python-2-and-python-3-without-conversion>`_"
msgid "Understanding strings in Python 2 and Python 3"
msgstr "Python 2 および Python 3 の文字列を理解"
#: ../../rst/dev_guide/developing_python_3.rst:61
msgid "Python 2 and Python 3 handle strings differently, so when you write code that supports Python 3 you must decide what string model to use. Strings can be an array of bytes (like in C) or they can be an array of text. Text is what we think of as letters, digits, numbers, other printable symbols, and a small number of unprintable \"symbols\" (control codes)."
msgid "In Python 2, the two types for these (:class:`str <python:str>` for bytes and :func:`unicode <python:unicode>` for text) are often used interchangeably. When dealing only with ASCII characters, the strings can be combined, compared, and converted from one type to another automatically. When non-ASCII characters are introduced, Python 2 starts throwing exceptions due to not knowing what encoding the non-ASCII characters should be in."
msgid "Python 3 changes this behavior by making the separation between bytes (:class:`bytes <python3:bytes>`) and text (:class:`str <python3:str>`) more strict. Python 3 will throw an exception when trying to combine and compare the two types. The programmer has to explicitly convert from one type to the other to mix values from each."
msgid "In Python 3 it's immediately apparent to the programmer when code is mixing the byte and text types inappropriately, whereas in Python 2, code that mixes those types may work until a user causes an exception by entering non-ASCII input. Python 3 forces programmers to proactively define a strategy for working with strings in their program so that they don't mix text and byte strings unintentionally."
msgid "Ansible uses different strategies for working with strings in controller-side code, in :ref: `modules <module_string_strategy>`, and in :ref:`module_utils <module_utils_string_strategy>` code."
msgid "Controller string strategy: the Unicode Sandwich"
msgstr "コントローラー文字列戦略: Unicode Sandwich"
#: ../../rst/dev_guide/developing_python_3.rst:93
msgid "In controller-side code we use a strategy known as the Unicode Sandwich (named after Python 2's :func:`unicode <python:unicode>` text type). For Unicode Sandwich we know that at the border of our code and the outside world (for example, file and network IO, environment variables, and some library calls) we are going to receive bytes. We need to transform these bytes into text and use that throughout the internal portions of our code. When we have to send those strings back out to the outside world we first convert the text back into bytes. To visualize this, imagine a 'sandwich' consisting of a top and bottom layer of bytes, a layer of conversion between, and all text type in the center."
msgid "This is a partial list of places where we have to convert to and from bytes when using the Unicode Sandwich string strategy. It's not exhaustive but it gives you an idea of where to watch for problems."
msgid "In Python 2, reading from files yields bytes. In Python 3, it can yield text. To make code that's portable to both we don't make use of Python 3's ability to yield text but instead do the conversion explicitly ourselves. For example:"
msgid "Much of Ansible assumes that all encoded text is UTF-8. At some point, if there is demand for other encodings we may change that, but for now it is safe to assume that bytes are UTF-8."
msgid "Note that we don't have to catch :exc:`UnicodeError` here because we're transforming to UTF-8 and all text strings in Python can be transformed back to UTF-8."
msgid "Dealing with filenames often involves dropping back to bytes because on UNIX-like systems filenames are bytes. On Python 2, if we pass a text string to these functions, the text string will be converted to a byte string inside of the function and a traceback will occur if non-ASCII characters are present. In Python 3, a traceback will only occur if the text string can't be decoded in the current locale, but it's still good to be explicit and have code which works on both versions:"
msgid "When you are only manipulating a filename as a string without talking to the filesystem (or a C library which talks to the filesystem) you can often get away without converting to bytes:"
msgstr "ファイルシステム (またはファイルシステムと通信する C ライブラリー) と通信せずにファイル名を文字列として操作するだけの場合は、バイトに変換せずに逃げることができることがよくあります。"
msgid "On the other hand, if the code needs to manipulate the filename and also talk to the filesystem, it can be more convenient to transform to bytes right away and manipulate in bytes."
msgid "Make sure all variables passed to a function are the same type. If you're working with something like :func:`python3:os.path.join` which takes multiple strings and uses them in combination, you need to make sure that all the types are the same (either all bytes or all text). Mixing bytes and text will cause tracebacks."
msgid "Interacting with other programs goes through the operating system and C libraries and operates on things that the UNIX kernel defines. These interfaces are all byte-oriented so the Python interface is byte oriented as well. On both Python 2 and Python 3, byte strings should be given to Python's subprocess library and byte strings should be expected back from it."
msgid "One of the main places in Ansible's controller code that we interact with other programs is the connection plugins' ``exec_command`` methods. These methods transform any text strings they receive in the command (and arguments to the command) to execute into bytes and return stdout and stderr as byte strings Higher level functions (like action plugins' ``_low_level_execute_command``) transform the output into text strings."
msgid "In modules we use a strategy known as Native Strings. This makes things easier on the community members who maintain so many of Ansible's modules, by not breaking backwards compatibility by mandating that all strings inside of modules are text and converting between text and bytes at the borders."
msgid "In Python 2, these are byte strings. In Python 3 these are text strings. Modules should be coded to expect bytes on Python 2 and text on Python 3."
msgid "In ``module_utils`` code we use a hybrid string strategy. Although Ansible's ``module_utils`` code is largely like module code, some pieces of it are used by the controller as well. So it needs to be compatible with modules and with the controller's assumptions, particularly the string strategy. The module_utils code attempts to accept native strings as input to its functions and emit native strings as their output."
msgid "Module-utils functions are therefore often very defensive in nature. They convert their string parameters into text (using ``ansible.module_utils._text.to_text``) at the beginning of the function, do their work, and then convert the return values into the native string type (using ``ansible.module_utils._text.to_native``) or back to the string type that their parameters received."
msgid "``__metaclass__ = type`` makes all classes defined in the file into new-style classes without explicitly inheriting from :class:`object <python3:object>`."
msgid "Makes imports look in :data:`sys.path <python3:sys.path>` for the modules being imported, skipping the directory in which the module doing the importing lives. If the code wants to use the directory in which the module doing the importing, there's a new dot notation to do so."
msgid "Since mixing text and bytes types leads to tracebacks we want to be clear about what variables hold text and what variables hold bytes. We do this by prefixing any variable holding bytes with ``b_``. For instance:"
msgid "We do not prefix the text strings instead because we only operate on byte strings at the borders, so there are fewer variables that need bytes than text."
msgid "The third-party Python `six <https://pypi.org/project/six/>`_ library exists to help projects create code that runs on both Python 2 and Python 3. Ansible includes a version of the library in module_utils so that other modules can use it without requiring that it is installed on the remote system. To make use of it, import it like this:"
msgid "Starting in Python 2.6, strings gained a method called ``format()`` to put strings together. However, one commonly used feature of ``format()`` wasn't added until Python 2.7, so you need to remember not to use it in Ansible code:"
msgid "Both of the format strings above map positional arguments of the ``format()`` method into the string. However, the first version doesn't work in Python 2.6. Always remember to put numbers into the placeholders so the code is compatible with Python 2.6."
msgid "Percent formatting of byte strings was added back into Python 3 in 3.5. This isn't a problem for us because Python 3.5 is our minimum version. However, if you happen to be testing Ansible code with Python 3.4 or earlier, you will find that the byte string formatting here won't work. Upgrade to Python 3.5 to test."
msgid "Ansible modules are slightly harder to code to support Python 3 than normal code from other projects. A lot of mocking has to go into unit testing an Ansible module, so it's harder to test that your changes have fixed everything or to to make sure that later commits haven't regressed the Python 3 support. Review our :ref:`testing <developing_testing>` pages for more information."
msgid "Before you can rebase your PR, you need to make sure you have the proper remotes configured. These instructions apply to any repository on GitHub, including collections repositories. On other platforms (bitbucket, gitlab), the same principles and commands apply but the syntax may be different. We use the ansible/ansible repository here as an example. In other repositories, the branch names may be different. Assuming you cloned your fork in the usual fashion, the ``origin`` remote will point to your fork::"
msgid "This will replay the changes in your branch on top of the changes made in the upstream ``devel`` branch. If there are merge conflicts, you will be prompted to resolve those before you can continue."
msgid "After you rebase, the status of your branch changes::"
msgstr "リベース後に、ブランチのステータスが変更になります。"
#: ../../rst/dev_guide/developing_rebasing.rst:61
msgid "Don't worry, this is normal after a rebase. You should ignore the ``git status`` instructions to use ``git pull``. We'll cover what to do next in the following section."
msgid "Since rebasing re-writes git history, you will need to use a force push::"
msgstr "git 履歴を再書き込みするため、強制的にプッシュする必要があります。"
#: ../../rst/dev_guide/developing_rebasing.rst:72
msgid "Your PR on GitHub has now been updated. This will automatically trigger testing of your changes. You should check in on the status of your PR after tests have completed to see if further changes are required."
msgid "For help with rebasing your PR, or other development related questions, join us on our #ansible-devel IRC chat channel on `freenode.net <https://freenode.net>`_."
msgid "Information on roadmaps, opening PRs, Ansibullbot, and more"
msgstr "ロードマップ、オープン PRS、Ansibullbot などに関する情報"
#: ../../rst/dev_guide/index.rst:5
msgid "Developer Guide"
msgstr "開発者ガイド"
#: ../../rst/dev_guide/index.rst:9
msgid "**Making Open Source More Inclusive**"
msgstr "**多様性を受け入れるオープンソースの強化**"
#: ../../rst/dev_guide/index.rst:11
msgid "Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. We ask that you open an issue or pull request if you come upon a term that we have missed. For more details, see `our CTO Chris Wright's message <https://www.redhat.com/en/blog/making-open-source-more-inclusive-eradicating-problematic-language>`_."
msgid "If you want to extend Ansible by using a custom module or plugin locally, creating a module or plugin, adding functionality to an existing module, or expanding test coverage, this guide is for you. We've included detailed information for developers on how to test and document modules, as well as the prerequisites for getting your module or plugin accepted into the main Ansible repository."
msgid "I want to :ref:`write a series of related modules <developing_modules_in_groups>` that integrate Ansible with a new product (for example, a database, cloud provider, network platform, and so on)."
msgid "If you prefer to read the entire guide, here's a list of the pages in order."
msgstr "本ガイドをすべて読む場合は、以下に示す順番でページを表示してください。"
#: ../../rst/dev_guide/migrating_roles.rst:6
msgid "Migrating Roles to Roles in Collections on Galaxy"
msgstr "Galaxy のコレクション内のロールへの移行"
#: ../../rst/dev_guide/migrating_roles.rst:8
msgid "You can migrate any existing standalone role into a collection and host the collection on Galaxy. With Ansible collections, you can distribute many roles in a single cohesive unit of re-usable automation. Inside a collection, you can share custom plugins across all roles in the collection instead of duplicating them in each role's :file:`library/`` directory."
msgid "If you want to import your collection to Galaxy, you need a `Galaxy namespace <https://galaxy.ansible.com/docs/contributing/namespaces.html>`_."
msgid "The highlighted directories above will change when you migrate to a collection-based role. The collection directory structure includes a :file:`roles/` directory:"
msgid "You will need to use the Fully Qualified Collection Name (FQCN) to use the roles and plugins when you migrate your role into a collection. The FQCN is the combination of the collection ``namespace``, collection ``name``, and the content item you are referring to."
msgid "A collection can contain one or more roles in the :file:`roles/` directory and these are almost identical to standalone roles, except you need to move plugins out of the individual roles, and use the :abbr:`FQCN (Fully Qualified Collection Name)` in some places, as detailed in the next section."
msgid "Create a collection. If you want to import this collection to Ansible Galaxy, you need a `Galaxy namespace <https://galaxy.ansible.com/docs/contributing/namespaces.html>`_."
msgid "This creates the collection directory structure."
msgstr "これにより、コレクションディレクトリー構造が作成されます。"
#: ../../rst/dev_guide/migrating_roles.rst:102
#: ../../rst/dev_guide/migrating_roles.rst:131
msgid "Copy the standalone role directory into the :file:`roles/` subdirectory of the collection. Roles in collections cannot have hyphens in the role name. Rename any such roles to use underscores instead."
msgid "Move any other plugins to the appropriate :file:`plugins/PLUGINTYPE/` directory. See :ref:`migrating_plugins_collection` for additional steps that may be required."
msgid "Migrating other role plugins to a collection"
msgstr "他のロールプラグインからコレクションへの移行"
#: ../../rst/dev_guide/migrating_roles.rst:184
msgid "To migrate other role plugins to a collection:"
msgstr "その他のロールプラグインをコレクションに移行するには、以下を実行します。"
#: ../../rst/dev_guide/migrating_roles.rst:187
msgid "Move each nonmodule plugins to the appropriate :file:`plugins/PLUGINTYPE/` directory. The :file:`mynamespace/mycollection/plugins/README.md` file explains the types of plugins that the collection can contain within optionally created subdirectories."
msgid "Update documentation to use the FQCN. Plugins that use ``doc_fragments`` need to use FQCN (for example, ``mydocfrag`` becomes ``mynamespace.mycollection.mydocfrag``)."
msgid "Update relative imports work in collections to start with a period. For example, :file:`./filename` and :file:`../asdfu/filestuff` works but :file:`filename` in same directory must be updated to :file:`./filename`."
msgid "Change the Python namespace for custom ``module_utils`` to use the :abbr:`FQCN (Fully Qualified Collection Name)` along with the ``ansible_collections`` convention. See :ref:`update_module_utils_role`."
msgid "If any of your custom modules use a custom module utility, once you migrate to a collection you cannot address the module utility in the top level ``ansible.module_utils`` Python namespace. Ansible does not merge content from collections into the Ansible internal Python namespace. Update any Python import statements that refer to custom module utilities when you migrate your custom content to collections. See :ref:`module_utils in collections <collection_module_utils>` for more details."
msgid "When coding with ``module_utils`` in a collection, the Python import statement needs to take into account the :abbr:`FQCN (Fully Qualified Collection Name)` along with the ``ansible_collections`` convention. The resulting Python import looks similar to the following example:"
msgid "The following example code snippets show a Python and a PowerShell module using both default Ansible ``module_utils`` and those provided by a collection. In this example the namespace is ``ansible_example`` and the collection is ``community``."
msgid "In the Python example the ``module_utils`` is ``helper`` and the :abbr:`FQCN (Fully Qualified Collection Name)` is ``ansible_example.community.plugins.module_utils.helper``:"
msgid "In the PowerShell example the ``module_utils`` is ``hyperv`` and the :abbr:`FQCN (Fully Qualified Collection Name)` is ``ansible_example.community.plugins.module_utils.hyperv``:"
msgid "Because of the way that the CPython interpreter does imports, combined with the way the Ansible plugin loader works, if your custom embedded module or plugin requires importing something from an :file:`__init__.py` file, that also becomes part of your collection. You can either originate the content inside a standalone role or use the file name in the Python import statement. The following example is an :file:`__init__.py` file that is part of a callback plugin found inside a collection named ``ansible_example.community``."
msgid "Example: Migrating a standalone role with plugins to a collection"
msgstr "例: プラグインを持つスタンドアロンロールをコレクションに移行"
#: ../../rst/dev_guide/migrating_roles.rst:284
msgid "In this example we have a standalone role called ``my-standalone-role.webapp`` to emulate a standalone role that contains dashes in the name (which is not valid in collections). This standalone role contains a custom module in the ``library/`` directory called ``manage_webserver``."
msgid "This example changed the original source file ``manage_webserver.py`` to the destination file ``manage.py``. This is optional but the :abbr:`FQCN (Fully Qualified Collection Name)` provides the ``webserver`` context as ``acme.webserver.manage``."
msgid "Change ``manage_webserver`` to ``acme.webserver.manage`` in :file:`tasks/` files in the role ( for example, ``my-standalone-role.webapp/tasks/main.yml``) and any use of the original module name."
msgid "This name change is only required if you changed the original module name, but illustrates content referenced by :abbr:`FQCN (Fully Qualified Collection Name)` can offer context and in turn can make module and plugin names shorter. If you anticipate using these modules independent of the role, keep the original naming conventions. Users can add the :ref:`collections keyword <collections_using_playbook>` in their playbooks. Typically roles are an abstraction layer and users won't use components of the role independently."
msgid "A standalone role can co-exist with its collection role counterpart (for example, as part of a support lifecycle of a product). This should only be done for a transition period, but these two can exist in downstream in packages such as RPMs. For example, the RHEL system roles could coexist with an `example of a RHEL system roles collection <https://github.com/maxamillion/collection-rhel-system-roles>`_ and provide existing backwards compatibility with the downstream RPM."
msgstr "スタンドアロンのロールは、対応するコレクションロールと共存することができます (例: 製品のサポートライフサイクルの一部として)。これは移行期間のみ行うべきですが、これら 2 つは RPM などのパッケージでダウンストリームに存在することができます。たとえば、RHEL のシステムロールは `example of a RHEL system roles collection <https://github.com/maxamillion/collection-rhel-system-roles>`_ と共存し、ダウンストリーム RPM との既存の後方互換性を提供することができます。"
#: ../../rst/dev_guide/migrating_roles.rst:341
msgid "This section walks through an example creating this coexistence in a downstream RPM and requires Ansible 2.9.0 or later."
msgid "Copy the contents of the role inside the collection into a directory named after the standalone role and place the standalone role in :file:`/usr/share/ansible/roles/`."
msgid "All previously bundled modules and plugins used in the standalone role are now referenced by :abbr:`FQCN (Fully Qualified Collection Name)` so even though they are no longer embedded, they can be found from the collection contents.This is an example of how the content inside the collection is a unique entity and does not have to be bound to a role or otherwise. You could alternately create two separate collections: one for the modules and plugins and another for the standalone role to migrate to. The role must use the modules and plugins as :abbr:`FQCN (Fully Qualified Collection Name)`."
msgid "Modules in the main Ansible repo have a defined life cycle, from first introduction to final removal. The module life cycle is tied to the `Ansible release cycle <release_cycle>`. A module may move through these four states:"
msgid "If a module matures, we will remove the 'preview' mark in the documentation. We support (though we cannot guarantee) backwards compatibility for these modules, which means their parameters should be maintained with stable meanings."
msgid "If a module's target API changes radically, or if someone creates a better implementation of its functionality, we may mark it deprecated. Modules that are deprecated are still available but they are reaching the end of their life cycle. We retain deprecated modules for 4 release cycles with deprecation warnings to help users update playbooks and roles that use them."
msgstr "モジュールのターゲット API が大幅に変更された場合、または誰かがその機能に対してより良い実装を作成した場合は、非推奨と表示することがあります。非推奨のモジュールは引き続き利用できますが、ライフサイクルの終わりに近づいています。非推奨のモジュールは 4 つのリリースサイクルの間保持され、ユーザーはそれを使用する Playbook とロールを更新できるように非推奨の警告が表示されます。"
#: ../../rst/dev_guide/module_lifecycle.rst:16
msgid "When a module has been deprecated for four release cycles, we remove the code and mark the stub file removed. Modules that are removed are no longer shipped with Ansible. The stub file helps users find alternative modules."
msgid "Rename the file so it starts with an ``_``, for example, rename ``old_cloud.py`` to ``_old_cloud.py``. This keeps the module available and marks it as deprecated on the module index pages."
msgid "A ``string``, such as ``\"2.10\"``; the version of Ansible where the module will be replaced with a docs-only module stub. Usually current release +4. Mutually exclusive with :removed_by_date:."
msgid "(Added in Ansible 2.10). An ISO 8601 formatted date when the module will be removed. Usually 2 years from the date the module is deprecated. Mutually exclusive with :removed_in:."
msgstr "(Ansible 2.10 に追加されます)。モジュールの削除時に ISO 8601 形式の日付。通常は、モジュールが非推奨になってから 2 年間となります。このモジュールでは、:removed_in: と相互排他的になります。"
#: ../../rst/dev_guide/module_lifecycle.rst
msgid "why"
msgstr "理由"
#: ../../rst/dev_guide/module_lifecycle.rst:32
msgid "Optional string that used to detail why this has been removed."
msgstr "これが削除された理由の詳細に使用される任意の文字列です。"
#: ../../rst/dev_guide/module_lifecycle.rst
msgid "alternative"
msgstr "代替方法"
#: ../../rst/dev_guide/module_lifecycle.rst:33
msgid "Inform users they should do instead, for example, ``Use M(whatmoduletouseinstead) instead.``."
msgid "For an example of documenting deprecation, see this `PR that deprecates multiple modules <https://github.com/ansible/ansible/pull/43781/files>`_. Some of the elements in the PR might now be out of date."
msgid "You can also rename a module and keep an alias to the old name by using a symlink that starts with _. This example allows the ``stat`` module to be called with ``fileinfo``, making the following examples equivalent::"
msgid "Ansible is a radically simple IT automation engine that automates cloud provisioning, configuration management, application deployment, intra-service orchestration, and many other IT needs."
msgstr "Ansible は、クラウドプロビジョニング、設定管理、アプリケーションのデプロイメント、サービス内オーケストレーション、およびその他の IT のニーズを自動化する非常にシンプルな IT 自動化エンジンです。"
msgid "Being designed for multi-tier deployments since day one, Ansible models your IT infrastructure by describing how all of your systems inter-relate, rather than just managing one system at a time."
msgid "It uses no agents and no additional custom security infrastructure, so it's easy to deploy - and most importantly, it uses a very simple language (YAML, in the form of Ansible Playbooks) that allow you to describe your automation jobs in a way that approaches plain English."
msgid "Ansible works by connecting to your nodes and pushing out scripts called \"Ansible modules\" to them. Most modules accept parameters that describe the desired state of the system. Ansible then executes these modules (over SSH by default), and removes them when finished. Your library of modules can reside on any machine, and there are no servers, daemons, or databases required."
msgid "You can :ref:`write your own modules <developing_modules_general>`, though you should first consider :ref:`whether you should <developing_modules>`. Typically you'll work with your favorite terminal program, a text editor, and probably a version control system to keep track of changes to your content. You may write specialized modules in any language that can return JSON (Ruby, Python, bash, and so on)."
msgid "When multiple modules use the same code, Ansible stores those functions as module utilities to minimize duplication and maintenance. For example, the code that parses URLs is ``lib/ansible/module_utils/url.py``. You can :ref:`write your own module utilities <developing_module_utilities>` as well. Module utilities may only be written in Python or in PowerShell."
msgid ":ref:`Plugins <plugins_lookup>` augment Ansible's core functionality. While modules execute on the target system in separate processes (usually that means on a remote system), plugins execute on the control node within the ``/usr/bin/ansible`` process. Plugins offer options and extensions for the core features of Ansible - transforming data, logging output, connecting to inventory, and more. Ansible ships with a number of handy plugins, and you can easily :ref:`write your own <developing_plugins>`. For example, you can write an :ref:`inventory plugin <developing_inventory>` to connect to any datasource that returns JSON. Plugins must be written in Python."
msgid "By default, Ansible represents the machines it manages in a file (INI, YAML, and so on) that puts all of your managed machines in groups of your own choosing."
msgid "To add new machines, there is no additional SSL signing server involved, so there's never any hassle deciding why a particular machine didn't get linked up due to obscure NTP or DNS issues."
msgstr "新規マシンを追加するための、追加の SSL 署名サーバーはありません。したがって、NTP または DNS の問題が原因で特定のマシンがリンクされない理由を判断する手間がかかります。"
msgid "If there's another source of truth in your infrastructure, Ansible can also connect to that. Ansible can draw inventory, group, and variable information from sources like EC2, Rackspace, OpenStack, and more."
msgid "Once inventory hosts are listed, variables can be assigned to them in simple text files (in a subdirectory called 'group_vars/' or 'host_vars/' or directly in the inventory file."
msgid "Playbooks can finely orchestrate multiple slices of your infrastructure topology, with very detailed control over how many machines to tackle at a time. This is where Ansible starts to get most interesting."
msgid "Ansible's approach to orchestration is one of finely-tuned simplicity, as we believe your automation code should make perfect sense to you years down the road and there should be very little to remember about special syntax or features."
msgid "Modules, module utilities, plugins, playbooks, and roles can live in multiple locations. If you write your own code to extend Ansible's core features, you may have multiple files with similar or the same names in different locations on your Ansible control node. The search path determines which of these files Ansible will discover and use on any given playbook run."
msgid "Ansible's search path grows incrementally over a run. As Ansible finds each playbook and role included in a given run, it appends any directories related to that playbook or role to the search path. Those directories remain in scope for the duration of the run, even after the playbook or role has finished executing. Ansible loads modules, module utilities, and plugins in this order:"
msgid "Directories adjacent to a playbook specified on the command line. If you run Ansible with ``ansible-playbook /path/to/play.yml``, Ansible appends these directories if they exist:"
msgid "Directories adjacent to a playbook that is statically imported by a playbook specified on the command line. If ``play.yml`` includes ``- import_playbook: /path/to/subdir/play1.yml``, Ansible appends these directories if they exist:"
msgid "Directories specified as default paths in ``ansible.cfg`` or by the related environment variables, including the paths for the various plugin types. See :ref:`ansible_configuration_settings` for more information. Sample ``ansible.cfg`` fields:"
msgid "Modules, module utilities, and plugins in user-specified directories will override the standard versions. This includes some files with generic names. For example, if you have a file named ``basic.py`` in a user-specified directory, it will override the standard ``ansible.module_utils.basic``."
msgid "If you have more than one module, module utility, or plugin with the same name in different user-specified directories, the order of commands at the command line and the order of includes and roles in each play will affect which one is found and used on that particular play."
msgid "The Ansible AWS collection (on `Galaxy <https://galaxy.ansible.com/community/aws>`_, source code `repository <https://github.com/ansible-collections/community.aws>`_) is maintained by the Ansible AWS Working Group. For further information see the `AWS working group community page <https://github.com/ansible/community/wiki/aws>`_. If you are planning to contribute AWS modules to Ansible then getting in touch with the working group is a good way to start, especially because a similar module may already be under development."
msgid "Try to keep backward compatibility with relatively recent versions of boto3. That means that if you want to implement some functionality that uses a new feature of boto3, it should only fail if that feature actually needs to be run, with a message stating the missing feature and minimum required version of boto3."
msgid "Use feature testing (for example, ``hasattr('boto3.module', 'shiny_new_method')``) to check whether boto3 supports a feature rather than version checking. For example, from the ``ec2`` module:"
msgid "Prior to Ansible 2.0, modules were written in either boto3 or boto. We are still porting some modules to boto3. Modules that still require boto should be ported to use boto3 rather than using both libraries (boto and boto3). We would like to remove the boto dependency from all modules."
msgstr "Ansible 2.0 より前、モジュールは boto3 または boto のいずれかで記述されていました。まだ、いくつかのモジュールを boto3 に移植しています。それでもbotoが必要なモジュールは、両方のライブラリー (boto と boto3) を使用するのではなく、boto3 を使用するように移植する必要があります。すべてのモジュールから boto 依存関係を削除したいと考えています。"
msgid "Some old AWS modules use the generic ``AnsibleModule`` as a base rather than the more efficient ``AnsibleAWSModule``. To port an old module to ``AnsibleAWSModule``, change:"
msgid "Few other changes are required. AnsibleAWSModule does not inherit methods from AnsibleModule by default, but most useful methods are included. If you do find an issue, please raise a bug report."
msgid "When porting, keep in mind that AnsibleAWSModule also will add the default ec2 argument spec by default. In pre-port modules, you should see common arguments specified with:"
msgid "``AnsibleAWSModule`` greatly simplifies exception handling and library management, reducing the amount of boilerplate code. If you cannot use ``AnsibleAWSModule`` as a base, you must document the reason and request an exception to this rule."
msgid "Base the name of the module on the part of AWS that you actually use. (A good rule of thumb is to take whatever module you use with boto as a starting point). Don't further abbreviate names - if something is a well known abbreviation of a major component of AWS (for example, VPC or ELB), that's fine, but don't create new ones independently."
msgid "The ``ansible.module_utils.ec2`` module and ``ansible.module_utils.core.aws`` modules both automatically import boto3 and botocore. If boto3 is missing from the system then the variable ``HAS_BOTO3`` will be set to false. Normally, this means that modules don't need to import boto3 directly. There is no need to check ``HAS_BOTO3`` when using AnsibleAWSModule as the module does that check:"
msgid "The existing AWS modules support using :ref:`module_defaults <module_defaults>` for common authentication parameters. To do the same for your new module, add an entry for it in ``lib/ansible/config/module_defaults.yml``. These entries take the form of:"
msgid "AnsibleAWSModule provides the ``resource`` and ``client`` helper methods for obtaining boto3 connections. These handle some of the more esoteric connection options, such as security tokens and boto profiles."
msgstr "AnsibleAWSModule は、boto3 接続を取得するためのヘルパーメソッド ``resource`` および ``client`` を提供します。これらは、セキュリティートークンや boto プロファイルなど、より難解な接続オプションのいくつかを処理します。"
msgid "If using the basic AnsibleModule then you should use ``get_aws_connection_info`` and then ``boto3_conn`` to connect to AWS as these handle the same range of connection options."
msgid "An example of connecting to ec2 is shown below. Note that unlike boto there is no ``NoAuthHandlerFound`` exception handling like in boto. Instead, an ``AuthFailure`` exception will be thrown when you use the connection. To ensure that authorization, parameter validation and permissions errors are all caught, you should catch ``ClientError`` and ``BotoCoreError`` exceptions with every boto3 connection call. See exception handling:"
msgid "These fragments should be used rather than re-documenting these properties to ensure consistency and that the more esoteric connection options are documented. For example:"
msgid "You should wrap any boto3 or botocore call in a try block. If an exception is thrown, then there are a number of possibilities for handling it."
msgid "For more information on botocore exception handling see the `botocore error documentation <https://botocore.readthedocs.io/en/latest/client_upgrades.html#error-handling>`_."
msgid "To use ``ansible.module_utils.aws.core.is_boto3_error_code`` to catch a single AWS error code, call it in place of ``ClientError`` in your except clauses. In this case, *only* the ``InvalidGroup.NotFound`` error code will be caught here, and any other error will be raised for handling elsewhere in the program."
msgid "In the AnsibleAWSModule there is a special method, ``module.fail_json_aws()`` for nice reporting of exceptions. Call this on your exception and it will report the error together with a traceback for use in Ansible verbose mode."
msgid "You should use the AnsibleAWSModule for all new modules, unless not possible. If adding significant amounts of exception handling to existing modules, we recommend migrating the module to use AnsibleAWSModule (there are very few changes required to do this)"
msgid "Note that it should normally be acceptable to catch all normal exceptions here, however if you expect anything other than botocore exceptions you should test everything works as expected."
msgid "For methods that return a lot of results, boto3 often provides `paginators <https://boto3.readthedocs.io/en/latest/guide/paginators.html>`_. If the method you're calling has ``NextToken`` or ``Marker`` parameters, you should probably check whether a paginator exists (the top of each boto3 service reference page has a link to Paginators, if the service has any). To use paginators, obtain a paginator object, call ``paginator.paginate`` with the appropriate arguments and then call ``build_full_result``."
msgid "Any time that you are calling the AWS API a lot, you may experience API throttling, and there is an ``AWSRetry`` decorator that can be used to ensure backoff. Because exception handling could interfere with the retry working properly (as AWSRetry needs to catch throttling exceptions to work correctly), you'd need to provide a backoff function and then put exception handling around the backoff function."
msgstr "AWS API を大量に呼び出しているのはいつでも、API スロットリングが発生する可能性があり、バックオフ機能を提供するために使用できる ``AWSRetry`` デコレーターがあります。例外処理は再試行が正しく機能するのを妨げる可能性があるため (AWSRetry が正しく機能するためにスロットリング例外を取得する必要があるため)、バックオフ関数を提供してから、バックオフ関数の周りに例外処理を配置する必要があります。"
msgid "You can use ``exponential_backoff`` or ``jittered_backoff`` strategies - see the cloud ``module_utils`` ()/lib/ansible/module_utils/cloud.py) and `AWS Architecture blog <https://www.awsarchitectureblog.com/2015/03/backoff.html>`_ for more details."
msgid "If the underlying ``describe_some_resources`` API call throws a ``ResourceNotFound`` exception, ``AWSRetry`` takes this as a cue to retry until it's not thrown (this is so that when creating a resource, we can just retry until it exists)."
msgstr "基礎となる ``describe_some_resources`` API 呼び出しで ``ResourceNotFound`` 例外を出力すると、``AWSRetry`` はこれが出力されなくなるまで再試行する合図としてこれを受け取ります (これは、リソースを作成するときに、リソースが存在するまで再試行できるようにするためです)。"
msgid "To handle authorization failures or parameter validation errors in ``describe_some_resource_with_backoff``, where we just want to return ``None`` if the resource doesn't exist and not retry, we need:"
msgid "To make use of AWSRetry easier, it can now be wrapped around a client returned by ``AnsibleAWSModule``. any call from a client. To add retries to a client, create a client:"
msgid "Any calls from that client can be made to use the decorator passed at call-time using the `aws_retry` argument. By default, no retries are used."
msgid "You can also use customization for ``retries``, ``delay`` and ``max_delay`` parameters used by ``AWSRetry.jittered_backoff`` API using module params. You can take a look at the `cloudformation <cloudformation_module>` module for example."
msgid "When you make a call using boto3, you will probably get back some useful information that you should return in the module. As well as information related to the call itself, you will also have some response metadata. It is OK to return this to the user as well as they may find it useful."
msgid "Boto3 returns all values CamelCased. Ansible follows Python standards for variable names and uses snake_case. There is a helper function in module_utils/ec2.py called `camel_dict_to_snake_dict` that allows you to easily convert the boto3 response to snake_case."
msgid "You should use this helper function and avoid changing the names of values returned by Boto3. E.g. if boto3 returns a value called 'SecretAccessKey' do not change it to 'AccessKey'."
msgid "Note that AWS is unlikely to return the policy in the same order that is was submitted. Therefore, use the `compare_policies` helper function which handles this variance."
msgid "AWS has a concept of resource tags. Usually the boto3 API has separate calls for tagging and untagging a resource. For example, the ec2 API has a create_tags and delete_tags call."
msgstr "AWS にはリソースタグの概念があります。通常、boto3 API には、リソースのタグ付けとタグ付け解除のための呼び出しがあります。たとえば、ec2 API には create_tags および delete_tags の呼び出しがあります。"
msgid "There is a helper function `compare_aws_tags` to ease dealing with tags. It can compare two dicts and return the tags to set and the tags to delete. See the Helper function section below for more detail."
msgid "boto3 returns results in a dict. The keys of the dict are in CamelCase format. In keeping with Ansible format, this function will convert the keys to snake_case."
msgid "``camel_dict_to_snake_dict`` takes an optional parameter called ``ignore_list`` which is a list of keys not to convert (this is usually useful for the ``tags`` dict, whose child keys should remain with case preserved)"
msgid "Another optional parameter is ``reversible``. By default, ``HTTPEndpoint`` is converted to ``http_endpoint``, which would then be converted by ``snake_dict_to_camel_dict`` to ``HttpEndpoint``. Passing ``reversible=True`` converts HTTPEndpoint to ``h_t_t_p_endpoint`` which converts back to ``HTTPEndpoint``."
msgid "`snake_dict_to_camel_dict` converts snake cased keys to camel case. By default, because it was first introduced for ECS purposes, this converts to dromedaryCase. An optional parameter called `capitalize_first`, which defaults to `False`, can be used to convert to CamelCase."
msgid "Converts a boto3 tag list to an Ansible dict. Boto3 returns tags as a list of dicts containing keys called 'Key' and 'Value' by default. This key names can be overridden when calling the function. For example, if you have already camel_cased your list of tags you may want to pass lowercase key names instead, in other words, 'key' and 'value'."
msgid "Opposite of above. Converts an Ansible dict to a boto3 tag list of dicts. You can again override the key names used if 'Key' and 'Value' is not suitable."
msgid "Pass this function a list of security group names or combination of security group names and IDs and this function will return a list of IDs. You should also pass the VPC ID if known because security group names are not necessarily unique across VPCs."
msgstr "この関数にセキュリティーグループ名のリスト、またはセキュリティーグループ名とIDの組み合わせを渡すと、この関数は ID のリストを返します。セキュリティーグループ名は VPC 間で必ずしも一意であるとは限らないため、既知の場合は VPCID も渡す必要があります。"
msgid "Pass two dicts of policies to check if there are any meaningful differences and returns true if there are. This recursively sorts the dicts and makes them hashable before comparison."
msgid "Pass two dicts of tags and an optional purge parameter and this function will return a dict containing key pairs you need to modify and a list of tag key names that you need to remove. Purge is True by default. If purge is False then any existing tags will not be modified."
msgid "This function is useful when using boto3 'add_tags' and 'remove_tags' functions. Be sure to use the other helper function `boto3_tag_list_to_ansible_dict` to get an appropriate tag dict before calling this function. Since the AWS APIs are not uniform (for example, EC2 is different from Lambda) this will work without modification for some (Lambda) and others may need modification before using these values (such as EC2, with requires the tags to unset to be in the form `[{'Key': key1}, {'Key': key2}]`)."
msgid "All new AWS modules should include integration tests to ensure that any changes in AWS APIs that affect the module are detected. At a minimum this should cover the key API calls and check the documented return values are present in the module result."
msgstr "すべての新規 AWS モジュールには、モジュールに影響する AWS API の変更が検出されるように、統合テストを含める必要があります。最小値はキー API 呼び出しに対応し、文書化された戻り値がモジュールの結果に存在するようにする必要があります。"
msgid "For general information on running the integration tests see the :ref:`Integration Tests page of the Module Development Guide <testing_integration>`, especially the section on configuration for cloud tests."
msgid "You must also have a aliases file in `test/integration/targets/MODULE_NAME/aliases`. This file serves two purposes. First indicates it's in an AWS test causing the test framework to make AWS credentials available during the test run. Second putting the test in a test group causing it to be run in the continuous integration build."
msgid "Tests for new modules should be added to the same group as existing AWS tests. In general just copy an existing aliases file such as the `aws_s3 tests aliases file <https://github.com/ansible-collections/amazon.aws/blob/master/tests/integration/targets/aws_s3/aliases>`_."
msgid "The testing framework handles running the test with appropriate AWS credentials, these are made available to your test in the following variables:"
msgid "So all invocations of AWS modules in the test should set these parameters. To avoid duplicating these for every call, it's preferable to use :ref:`module_defaults <module_defaults>`. For example:"
msgid "As explained in the :ref:`Integration Test guide <testing_integration>` there are defined IAM policies in `mattclay/aws-terminator <https://github.com/mattclay/aws-terminator>`_ that contain the necessary permissions to run the AWS integration test."
msgstr ":ref:`Integration Test guide <testing_integration>` で説明されているように、AWS 統合テストを実行するために必要な権限が含まれる `mattclay/aws-terminator <https://github.com/mattclay/aws-terminator>`_ で定義された IAM ポリシーがあります。"
msgid "If your module interacts with a new service or otherwise requires new permissions, tests will fail when you submit a pull request and the `Ansibullbot <https://github.com/ansible/ansibullbot/blob/master/ISSUE_HELP.md>`_ will tag your PR as needing revision. We do not automatically grant additional permissions to the roles used by the continuous integration builds. You will need to raise a Pull Request against `mattclay/aws-terminator <https://github.com/mattclay/aws-terminator>`_ to add them."
msgid "If your PR has test failures, check carefully to be certain the failure is only due to the missing permissions. If you've ruled out other sources of failure, add a comment with the `ready_for_review` tag and explain that it's due to missing permissions."
msgid "Your pull request cannot be merged until the tests are passing. If your pull request is failing due to missing permissions, you must collect the minimum IAM permissions required to run the tests."
msgstr "テストに合格するまでプル要求がマージできません。パーミッションがないためにプル要求が失敗すると、テストの実行に必要な最低限の IAM パーミッションを収集する必要があります。"
msgid "Start with the most permissive IAM policy, run the tests to collect information about which resources your tests actually use, then construct a policy based on that output. This approach only works on modules that use `AnsibleAWSModule`."
msgstr "最も許容度の高い IAM ポリシーから始めて、テストを実行し、テストが実際に使用するリソースに関する情報を収集し、その出力に基づいてポリシーを構築します。このアプローチは、`AnsibleAWSModule` を使用するモジュールでのみ機能します。"
msgid "Start with the least permissive IAM policy, run the tests to discover a failure, add permissions for the resource that addresses that failure, then repeat. If your module uses `AnsibleModule` instead of `AnsibleAWSModule`, you must use this approach."
msgstr "最も許容度の低い IAM ポリシーから開始し、テストを実行して障害を検出し、その障害に対処するリソースのパーミッションを追加してから、繰り返します。モジュールが使用する場合は、`AnsibleAWSModule` の代わりに `AnsibleModule` を使用する場合は、このアプローチを使用する必要があります。"
msgid "`Create an IAM policy <https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-start>`_ that allows all actions (set ``Action`` and ``Resource`` to ``*```)."
msgid "Run your tests locally with this policy. On AnsibleAWSModule-based modules, the ``debug_botocore_endpoint_logs`` option is automatically set to ``yes``, so you should see a list of AWS ACTIONS after the PLAY RECAP showing all the permissions used. If your tests use a boto/AnsibleModule module, you must start with the least permissive policy (see below)."
msgid "Modify your policy to allow only the actions your tests use. Restrict account, region, and prefix where possible. Wait a few minutes for your policy to update."
msgid "If the tests fail, troubleshoot (see tips below), modify the policy, run the tests again, and repeat the process until the tests pass with a restrictive policy."
msgid "Open a pull request proposing the minimum required policy to the `CI policies <https://github.com/mattclay/aws-terminator/tree/master/aws/policy>`_."
msgid "Usually the action is a CamelCase version of the method name - for example, for an ec2 client the method `describe_security_groups` correlates to the action `ec2:DescribeSecurityGroups`."
msgid "Add the action or resource that caused the failure to `an IAM policy <https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-start>`_. Wait a few minutes for your policy to update."
msgid "If the tests still fail at the same place with the same error you will need to troubleshoot (see tips below). If the first test passes, repeat steps 2 and 3 for the next error. Repeat the process until the tests pass with a restrictive policy."
msgid "Use the `policy simulator <https://policysim.aws.amazon.com/>`_ to verify that each action (limited by resource when applicable) in your policy is allowed."
msgid "If you're restricting actions to certain resources, replace resources temporarily with `*`. If the tests pass with wildcard resources, there is a problem with the resource definition in your policy."
msgid "Re-read the AWS documentation, especially the list of `Actions, Resources and Condition Keys <https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_actions-resources-contextkeys.html>`_ for the various AWS services."
msgid "There are a limited number of reasons why it may not be practical to run integration tests for a module within CI. Where these apply you should add the keyword `unsupported` to the aliases file in `test/integration/targets/MODULE_NAME/aliases`."
msgid "Some cases where tests should be marked as unsupported: 1) The tests take longer than 10 or 15 minutes to complete 2) The tests create expensive resources 3) The tests create inline policies 4) The tests require the existence of external resources 5) The tests manage Account level security policies such as the password policy or AWS Organizations."
msgid "Where one of these reasons apply you should open a pull request proposing the minimum required policy to the `unsupported test policies <https://github.com/mattclay/aws-terminator/tree/master/hacking/aws_config/test_policies>`_."
msgid "Unsupported integration tests will not be automatically run by CI. However, the necessary policies should be available so that the tests can be manually run by someone performing a PR review or writing a patch."
msgstr "サポート対象外の統合テストは CI によって自動的に実行されませんが、必要なポリシーを利用すると、PR レビューまたはパッチの作成を実行してテストを手動で実行できるようにする必要があります。"
msgid "Please see the `OpenStack guidelines <https://opendev.org/openstack/ansible-collections-openstack/src/branch/master/docs/openstack_guidelines.rst>`_, for further information."
msgid "The set of modules for interacting with oVirt/RHV are currently part of the community.general collection (on `Galaxy <https://galaxy.ansible.com/community/general>`_, source code `repository <https://github.com/ansible-collections/community.general/tree/main/plugins/modules/cloud/ovirt>`_). This document serves as developer coding guidelines for creating oVirt/RHV modules."
msgid "All modules should use ``ovirt_full_argument_spec`` or ``ovirt_info_full_argument_spec`` to pick up the standard input (such as auth and ``fetch_nested``)."
msgid "In order to achieve idempotency of oVirt entity attributes, a helper class was created. The first thing you need to do is to extend this class and override a few methods:"
msgid "The code above handle the check if the entity should be updated, so we don't update the entity if not needed and also it construct the needed entity of the SDK."
msgid "If your module must support action handling (for example, virtual machine start) you must ensure that you handle the states of the virtual machine correctly, and document the behavior of the module:"
msgid "As you can see from the preceding example, the ``action`` method accepts the ``action_condition`` and ``wait_condition``, which are methods which accept the virtual machine object as a parameter, so you can check whether the virtual machine is in a proper state before the action. The rest of the parameters are for the ``start`` action. You may also handle pre- or post- action tasks by defining ``pre_action`` and ``post_action`` parameters."
msgid "Integration testing is currently done in oVirt's CI system `on Jenkins <https://jenkins.ovirt.org/view/All/job/ovirt-system-tests_ansible-suite-master/>`__ and `on GitHub <https://github.com/oVirt/ovirt-system-tests/tree/master/ansible-suite-master/>`__."
msgstr "統合テストは、現在、__ と `GitHub <https://github.com/oVirt/ovirt-system-tests/tree/master/ansible-suite-master/>`__ の oVirt's CI システム で行われています。"
msgid "The Ansible VMware collection (on `Galaxy <https://galaxy.ansible.com/community/vmware>`_, source code `repository <https://github.com/ansible-collections/community.vmware>`_) is maintained by the VMware Working Group. For more information see the `team community page <https://github.com/ansible/community/wiki/VMware>`_."
msgid "Most of the existing modules are covered by functional tests. The tests are located `here <https://github.com/ansible-collections/community.vmware/tree/main/tests/integration/targets>`_."
msgid "By default, the tests run against a vCenter API simulator called `govcsim <https://github.com/vmware/govmomi/tree/master/vcsim>`_. ``ansible-test`` will automatically pull a `govcsim container <https://quay.io/repository/ansible/vcenter-test-container>`_ and use it to set-up the test environment."
msgid "``govcsim`` is handy because it is much faster than a regular test environment. However, ``govcsim`` does not support all the ESXi or vCenter features."
msgid "Do not confuse ``govcsim`` with ``vcsim``. ``vcsim`` is an older and outdated version of vCenter simulator, whereas ``govcsim`` is new and written in Go language."
msgid "If you want to deploy your test environment in a hypervisor, both `VMware or Libvirt <https://github.com/goneri/vmware-on-libvirt>`_ works well."
msgid "With this configuration all the new files will be owned by the user with the UID and GID 1000/1000. Adjust the configuration to match your user's UID/GID."
msgid "Prepare a configuration file that describes your set-up. The file should be called :file:`test/integration/cloud-config-vcenter.ini` and based on :file:`test/lib/ansible_test/config/cloud-config-vcenter.ini.template`. For instance, if you have deployed your lab with `vmware-on-libvirt <https://github.com/goneri/vmware-on-libvirt>`_:"
msgid "In addition, you may need to adjust the variables of the following `var files <https://github.com/ansible-collections/community.vmware/tree/main/tests/integration/targets/prepare_vmware_tests/vars>`_ to match the configuration of your lab. If you use vmware-on-libvirt to prepare your lab, you do not have anything to change."
msgid "``vmware_guest`` is much larger than any other test role and is rather slow. You can enable or disable some of its test playbooks in `main.yml <https://github.com/ansible-collections/community.vmware/tree/main/tests/integration/targets/vmware_guest/defaults/main.yml>`_."
msgid "The ``datacenter`` parameter should not use ``ha-datacenter`` by default. This is because the user may not realize that Ansible silently targets the wrong data center."
msgid "Depending upon the functionality provided by ESXi or vCenter, some modules can seamlessly work with both. In this case, ``esxi_hostname`` parameter should be optional."
msgid "Use FQCN for examples within module documentation. For instance, you should use ``community.vmware.vmware_guest`` instead of just ``vmware_guest``."
msgid "If you are writing a new collection of integration tests, there are a few VMware-specific things to note beyond the standard Ansible :ref:`integration testing<testing_integration>` process."
msgid "The test-suite uses a set of common, pre-defined vars located `in prepare_vmware_tests <https://github.com/ansible-collections/community.vmware/tree/main/tests/integration/targets/test/integration/targets/prepare_vmware_tests/>`_ role. The resources defined there are automatically created by importing that role at the start of your test:"
msgid "Most of the time, it's not necessary to use ``with_items`` to create multiple resources. By avoiding it, you speed up the test execution and you simplify the clean up afterwards."
msgid "If you need to create a new VM during your test, you can use ``test_vm1``, ``test_vm2`` or ``test_vm3``. This way it will be automatically clean up for you."
msgid "From Ansible 2.10, the test suite uses `modules_defaults`. This module allow us to preinitialize the following default keys of the VMware modules:"
msgid "The Ansible VMware REST collection (on `Galaxy <https://galaxy.ansible.com/vmware/vmware_rest>`_, source code `repository <https://github.com/ansible-collections/vmware.vmware_rest>`_) is maintained by Red Hat and the community."
msgid "The modules of the vmware_rest collection are autogenerated by another tool called `vmware_rest_code_generator <https://github.com/ansible-collections/vmware_rest_code_generator>`."
msgid "Ansible uses Standard American English. Watch for common words that are spelled differently in American English (color vs colour, organize vs organise, and so on)."
msgid "Everything you say should be understandable by people of different backgrounds and cultures. Avoid idioms and regionalism and maintain a neutral tone that cannot be misinterpreted. Avoid attempts at humor."
msgid "The unwise walking about upon the area near the cliff edge may result in a dangerous fall and therefore it is recommended that one remains a safe distance to maintain personal safety."
msgstr "The unwise walking about upon the area near the cliff edge may result in a dangerous fall and therefore it is recommended that one remains a safe distance to maintain personal safety. (崖の端近くを歩き回ると、下に落ちる危険があります。安全を維持するために安全な距離を保つことをお勧めします。)"
msgid "Write \"Ansible.\" Not \"Ansible, Inc.\" or \"AnsibleWorks The only exceptions to this rule are when we're writing legal or financial statements."
msgid "If it's not a real product, service, or department at Ansible, don't capitalize it. Not even if it seems important. Capitalize only the first letter of the first word in headlines."
msgid "But not if the list is a complement or object of an element in the sentence: - Before going on vacation, be sure to (1) set the alarm, (2) cancel the newspaper, and (3) ask a neighbor to collect your mail."
msgstr "ただし、リストが、文内の要素の補語または目的語の場合は、以下のようにします。Before going on vacation, be sure to (1) set the alarm, (2) cancel the newspaper, and (3) ask a neighbor to collect your mail."
msgid "Use a colon after \"as follows\" and \"the following\" if the related list comes immediately after: wedge The steps for changing directories are as follows:"
msgstr "直後に関連するリストを追加する場合は、「as follows」および「the following」(次のとおり) の後にコロンを使用します。The steps for changing directories are as follows:"
msgid "It's easier to read that way and helps avoid confusion. The primary exception to this you will see is in PR, where it is traditional not to use serial commas because it is often the style of journalists."
msgid "When possible, use em-dashes with no space on either side. When full em-dashes aren't available, use double-dashes with no spaces on either side--like this."
msgid "A pair of em dashes can replace a pair of parentheses. Dashes are considered less formal than parentheses; they are also more intrusive. If you want to draw attention to the parenthetical content, use dashes. If you want to include the parenthetical content more subtly, use parentheses."
msgid "Do not use gender-specific pronouns in documentation. It is far less awkward to read a sentence that uses \"they\" and \"their\" rather than \"he/she\" and \"his/hers.\""
msgid "The hyphen's primary function is the formation of certain compound terms. Do not use a hyphen unless it serves a purpose. If a compound adjective cannot be misread or, as with many psychological terms, its meaning is established, a hyphen is not necessary."
msgid "In professionally printed material (particularly books, magazines, and newspapers), the hyphen is used to divide words between the end of one line and the beginning of the next. This allows for an evenly aligned right margin without highly variable (and distracting) word spacing."
msgid "Keep the structure of bulleted lists equivalent and consistent. If one bullet is a verb phrase, they should all be verb phrases. If one is a complete sentence, they should all be complete sentences, and so on."
msgid "Capitalize the first word of each bullet. Unless it is obvious that it is just a list of items, such as a list of items like: * computer * monitor * keyboard * mouse"
msgid "When the bulleted list appears within the context of other copy, (unless it's a straight list like the previous example) add periods, even if the bullets are sentence fragments. Part of the reason behind this is that each bullet is said to complete the original sentence."
msgid "Abbreviate months and states according to AP. Months are only abbreviated if they are used in conjunction with a day. Example: \"The President visited in January 1999.\" or \"The President visited Jan. 12.\""
msgstr "AP に従って、月と州の名前を省略します。月は、日付と組み合わせて使用される場合に限り省略されます。たとえば、「The President visited in January 1999.」または「The President visited Jan. 12.」です。"
msgid "Numbers between one and nine are written out. 10 and above are numerals. The exception to this is writing \"4 million\" or \"4 GB.\" It's also acceptable to use numerals in tables and charts."
msgid "Except in rare instances, use only \"said\" or \"says\" because anything else just gets in the way of the quote itself, and also tends to editorialize."
msgid "Everyday I have coffee, toast, and fruit for breakfast; a salad for lunch; and a peanut butter sandwich, cookies, ice cream, and chocolate cake for dinner."
msgstr "Everyday I have coffee, toast, and fruit for breakfast; a salad for lunch; and a peanut butter sandwich, cookies, ice cream, and chocolate cake for dinner."
msgid "Latin words and phrases like ``e.g.`` or ``etc.`` are easily understood by English speakers. They may be harder to understand for others and are also tricky for automated translation."
msgid "The Ansible documentation is written in reStructuredText and processed by Sphinx. We follow these technical or mechanical guidelines on all rST pages:"
msgid "`Section headers in reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections>`_ can use a variety of notations. Sphinx will 'learn on the fly' when creating a hierarchy of headers. To make our documents easy to read and to edit, we follow a standard set of header notations. We use:"
msgstr "`Section headers in reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections>`_ は、さまざまな表記を使用できます。Sphinx は、ヘッダーの階層を作成するときに「オンザフライで学習」します。ドキュメントを読みやすく、編集できるようにするために、標準のヘッダー表記法に従います。以下を使用します。"
#: ../../rst/dev_guide/style_guide/index.rst:91
msgid "``###`` with overline, for parts:"
msgstr "``###`` 上線付き (各部分の場合):"
#: ../../rst/dev_guide/style_guide/index.rst:99
msgid "``***`` with overline, for chapters:"
msgstr "``***`` 上線付き (章の場合):"
#: ../../rst/dev_guide/style_guide/index.rst:107
msgid "``===`` for sections:"
msgstr "``===`` セクションの場合:"
#: ../../rst/dev_guide/style_guide/index.rst:114
msgid "``---`` for subsections:"
msgstr "``---`` サブセクションの場合:"
#: ../../rst/dev_guide/style_guide/index.rst:121
msgid "``^^^`` for sub-subsections:"
msgstr "``^^^`` サブサブセクションの場合:"
#: ../../rst/dev_guide/style_guide/index.rst:128
msgid "``\"\"\"`` for paragraphs:"
msgstr "``\"\"\"`` パラグラフの場合:"
#: ../../rst/dev_guide/style_guide/index.rst:137
msgid "Syntax highlighting - Pygments"
msgstr "構文の強調表示 - Pygment"
#: ../../rst/dev_guide/style_guide/index.rst:139
msgid "The Ansible documentation supports a range of `Pygments lexers <https://pygments.org/>`_ for `syntax highlighting <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#code-examples>`_ to make our code examples look good. Each code-block must be correctly indented and surrounded by blank lines."
msgid "The Ansible documentation allows the following values:"
msgstr "Ansible ドキュメントでは、以下の値を使用できます。"
#: ../../rst/dev_guide/style_guide/index.rst:144
msgid "none (no highlighting)"
msgstr "なし (強調表示なし)"
#: ../../rst/dev_guide/style_guide/index.rst:145
msgid "ansible-output (a custom lexer for Ansible output)"
msgstr "ansible-output (Ansible 出力用のカスタム lexer)"
#: ../../rst/dev_guide/style_guide/index.rst:146
msgid "bash"
msgstr "bash"
#: ../../rst/dev_guide/style_guide/index.rst:147
msgid "console"
msgstr "console"
#: ../../rst/dev_guide/style_guide/index.rst:148
msgid "csharp"
msgstr "csharp"
#: ../../rst/dev_guide/style_guide/index.rst:149
msgid "ini"
msgstr "ini"
#: ../../rst/dev_guide/style_guide/index.rst:151
msgid "powershell"
msgstr "powershell"
#: ../../rst/dev_guide/style_guide/index.rst:152
msgid "python"
msgstr "python"
#: ../../rst/dev_guide/style_guide/index.rst:153
msgid "rst"
msgstr "rst"
#: ../../rst/dev_guide/style_guide/index.rst:154
msgid "sh"
msgstr "sh"
#: ../../rst/dev_guide/style_guide/index.rst:155
msgid "shell"
msgstr "shell"
#: ../../rst/dev_guide/style_guide/index.rst:156
msgid "shell-session"
msgstr "shell-session"
#: ../../rst/dev_guide/style_guide/index.rst:157
msgid "text"
msgstr "text"
#: ../../rst/dev_guide/style_guide/index.rst:158
msgid "yaml"
msgstr "yaml"
#: ../../rst/dev_guide/style_guide/index.rst:159
msgid "yaml+jinja"
msgstr "yaml+jinja"
#: ../../rst/dev_guide/style_guide/index.rst:161
msgid "For example, you can highlight Python code using following syntax:"
msgstr "たとえば、以下の構文を使用して Python コードを強調表示できます。"
#: ../../rst/dev_guide/style_guide/index.rst:171
msgid "Internal navigation"
msgstr "内部ナビゲーション"
#: ../../rst/dev_guide/style_guide/index.rst:173
msgid "`Anchors (also called labels) and links <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#ref-role>`_ work together to help users find related content. Local tables of contents also help users navigate quickly to the information they need. All internal links should use the ``:ref:`` syntax. Every page should have at least one anchor to support internal ``:ref:`` links. Long pages, or pages with multiple levels of headers, can also include a local TOC."
msgstr "`Anchors (also called labels) and links <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#ref-role>`関連コンテンツを見つけやすくするために、あるローカルテーブルも必要な情報に移動するのに役立ちます。すべての内部リンクで ``:ref:`` 構文を使用する必要があります。また、内部ページには内部 ``:ref:`` リンクに対応するアンカーは 1 つ以上ある必要があります。長いページまたは複数のヘッダーレベルを持つページでも、ローカルの TOC を含めることもできます。"
#: ../../rst/dev_guide/style_guide/index.rst:183
msgid "Adding anchors"
msgstr "アンカーの追加"
#: ../../rst/dev_guide/style_guide/index.rst:185
msgid "Include at least one anchor on every page"
msgstr "すべてのページに少なくとも 1 つのアンカーを含める。"
#: ../../rst/dev_guide/style_guide/index.rst:186
msgid "Place the main anchor above the main header"
msgstr "メインヘッダーの上にメインアンカーを配置する。"
#: ../../rst/dev_guide/style_guide/index.rst:187
msgid "If the file has a unique title, use that for the main page anchor::"
msgstr "このファイルに一意のタイトルがある場合は、メインページのアンカーに使用する。"
#: ../../rst/dev_guide/style_guide/index.rst:191
msgid "You may also add anchors elsewhere on the page"
msgstr "ページにアンカーを追加することもできます。"
#: ../../rst/dev_guide/style_guide/index.rst:194
msgid "Adding internal links"
msgstr "内部リンクの追加"
#: ../../rst/dev_guide/style_guide/index.rst:196
msgid "All internal links must use ``:ref:`` syntax. These links both point to the anchor defined above:"
msgid "``ansible.builtin`` is the FQCN for modules included in ``ansible.base``. Documentation links are the only place you prepend ``ansible_collections`` to the FQCN. This is used by the documentation build scripts to correctly fetch documentation from collections on Ansible Galaxy."
msgid "The page you're reading includes a `local TOC <https://docutils.sourceforge.io/docs/ref/rst/directives.html#table-of-contents>`_. If you include a local TOC:"
msgid "One of the keys to writing good documentation is to make it findable. Readers use a combination of internal site search and external search engines such as Google or duckduckgo."
msgid "What we are really trying to describe is - how do I write documentation so search engines can find my content? That simple phrase is what drove the title of this section. When you are creating your headings for documentation, spend some time to think about what you would type in a search box to find it, or more importantly, how someone less familiar with Ansible would try to find that information. Your heading should be the answer to that question."
msgid "One word of caution - you do want to limit the size of your headings. A full heading such as `How do I write documentation so search engines can find my content?` is too long. Search engines would truncate anything over 50 - 60 characters. Long headings would also wrap on smaller devices such as a smart phone."
msgstr "注意の 1 つの単語 - 見出しのサイズを制限する場合は、`How do I write documentation so search engines can find my content?` などの見出しにすると長すぎます。検索エンジンは 50 ~ 60 文字を超えるものを省略します。長い見出しも、スマートフォンなどの小規模なデバイスで折り返されます。"
msgid "Google can optimize the search results by adding a `feature snippet <https://support.google.com/websearch/answer/9351707>`_ at the top of the search results. This snippet provides a small window into the documentation on that first search result that adds more detail than the rest of the search results, and can occasionally answer the reader's questions right there, or at least verify that the linked page is what the reader is looking for."
msgid "Google returns the feature snippet in the form of numbered steps. Where possible, you should add a numbered list near the top of your documentation page, where appropriate. The steps can be the exact procedure a reader would follow, or could be a high level introduction to the documentation topic, such as the numbered list at the top of this page."
msgid "Search engines do not typically return github blobs in search results, at least not in higher ranked positions. While it is possible and sometimes necessary to link to github blobs from documentation, the better approach would be to copy that information into an .rst page in Ansible documentation."
msgid "While it may not be possible to adapt your documentation to all search optimizations, keep the following in mind as you write your documentation:"
msgid "**Search engines don't parse beyond the `#` in an html page.** So for example, all the subheadings on this page are appended to the main page URL. As such, when I search for 'Using number lists for zero position snippets', the search result would be a link to the top of this page, not a link directly to the subheading I searched for. Using :ref:`local TOCs <local_toc>` helps alleviate this problem as the reader can scan for the header at top of the page and click to the section they are looking for. For critical documentation, consider creating a new page that can be a direct search result page."
msgstr "**検索エンジンは、html ページ内の `#` 以降は解析しません。** そのため、たとえば、このページのすべての小見出しは、メインページの URL に付加されています。そのため、「Using number lists for zero position snippets」と検索すると、検索結果はこのページの冒頭へのリンクになり、検索した小見出しへの直接のリンクにはなりません。:ref:`ローカル TOC <local_toc>` を使用すると、読者がページ上部のヘッダーをスキャンして、探しているセクションにクリックできるため、この問題を軽減することができます。重要な文書については、検索結果のページに直接アクセスできる新しいページを作成することを検討してください。"
msgid "**Make your first few sentences clearly describe your page topic.** Search engines return not just the URL, but a short description of the information at the URL. For Ansible documentation, we do not have description metadata embedded on each page. Instead, the search engines return the first couple of sentences (140 characters) on the page. That makes your first sentence or two very important to the reader who is searching for something in Ansible."
msgid "Always uppercase. An acronym is a word formed from the initial letters of a name, such as ROM for Read-only memory, SaaS for Software as a Service, or by combining initial letters or part of a series of words, such as LILO for LInux LOader."
msgstr "常に大文字です。頭字語とは、ROM (Read-Only Memory) や SaaS (Software as a Service) のように名前の頭文字から形成された単語や、LILO (LInux LOader) のように一連の単語の頭文字や一部を組み合わせて形成された単語のことです。"
msgid "When used as a proper name, use the capitalization of the product, such as GNUPro, Source-Navigator, and Ansible Tower. When used as a command, use lowercase as appropriate, such as \"To start GCC, type ``gcc``.\""
msgid "This is often used to mean \"because\", but has other connotations, for example, parallel or simultaneous actions. If you mean \"because\", say \"because\"."
msgid "Use \"can\" to describe actions or conditions that are possible. Use \"may\" only to describe situations where permission is being given. If either \"can,\" \"could,\" or \"may\" apply, use \"can\" because it's less tentative."
msgid "When referring to a compact disk, use CD, such as \"Insert the CD into the CD-ROM drive.\" When referring to the change directory command, use cd."
msgstr "コンパクトディスクを参照する場合は、CD を使用します。たとえば、「Insert the CD into the CD-ROM drive.」(CD を CD-ROM ドライブに挿入します。) とします。ディレクトリーを変更する change directory コマンドを示す場合は、cd を使用します。"
msgid "Correct. Do not use \"cdrom,\" \"CD-Rom,\" \"CDROM,\" \"cd-rom\" or any other variation. When referring to the drive, use CD-ROM drive, such as \"Insert the CD into the CD-ROM drive.\" The plural is \"CD-ROMs.\""
msgstr "「cdrom」、「CD-Rom」、「CDROM」、「cd-rom」、またはその他のバリテーションは使用しないでください。ドライブを参照する場合は、「Insert the CD into the CD-ROM drive (CD-ROM ドライブなど)」のように「CD-ROM drive」を使用します。複数形は「CD-ROMs」となります。"
msgid "Correct. Do not use \"command-line\" or \"commandline\" as a noun. If used as an adjective, \"command-line\" is appropriate, for example \"command-line arguments\"."
msgid "Use \"command line\" to describes where to place options for a command, but not where to type the command. Use \"shell prompt\" instead to describe where to type commands. The line on the display screen where a command is expected. Generally, the command line is the line that contains the most recently displayed command prompt."
msgid "Correct. Do not use daylight savings time. Daylight Saving Time (DST) is often misspelled \"Daylight Savings\", with an \"s\" at the end. Other common variations are \"Summer Time\"and \"Daylight-Saving Time\". (https://www.timeanddate.com/time/dst/daylight-savings-time.html)"
msgstr "適切です。「daylight savings time」は使用しないでください。「Daylight Saving Time (DST)」は、「Daylight Savings」のように、最後に s が付いている場合がありますが、これは間違いです。その他の一般的な表記法には、「Summer Time」および「Daylight-Saving Time」があります (https://www.timeanddate.com/time/dst/daylight-savings-time.html))。"
msgid "When used as a noun, a failover is a backup operation that automatically switches to a standby database, server or network if the primary system fails or is temporarily shut down for servicing. Failover is an important fault tolerance function of mission-critical systems that rely on constant accessibility. Failover automatically and transparently to the user redirects requests from the failed or down system to the backup system that mimics the operations of the primary system."
msgid "Fewer is used with plural nouns. Think things you could count. Time, money, distance, and weight are often listed as exceptions to the traditional \"can you count it\" rule, often thought of a singular amounts (the work will take less than 5 hours, for example)."
msgstr "fewer は、複数形の名詞で使用します。数を数えることができるものに使用します。時間、お金、距離、および重量は、従来の「数えることができるか」ルールの例外として挙げられることが多く、通常は 1 つの量と見なされます。たとえば、「the work will take less than 5 hours」(作業にかかる時間は 5 時間未満です)。"
msgid "Correct. Do not use \"filesystem.\" The system that an operating system or program uses to organize and keep track of files. For example, a hierarchical file system is one that uses directories to organize files into a tree structure. Although the operating system provides its own file management system, you can buy separate file management systems. These systems interact smoothly with the operating system but provide more features, such as improved backup procedures and stricter file protection."
msgid "\"It's\" is a contraction for \"it is;\" use \"it is\" instead of \"it's.\" Use \"its\" as a possessive pronoun (for example, \"the store is known for its low prices\")."
msgstr "「It's」は「it is」の短縮形です。「it's」ではなく「it is」を使用します。所有代名詞は「its」と使用します。たとえば「the store is known for its low prices」(この店は低価格で知られています) となります。"
msgid "Less is used with singular nouns. For example \"View less details\" wouldn't be correct but \"View less detail\" works. Use fewer when you have plural nouns (things you can count)."
msgstr "Less は単数名詞で使用されます。たとえば、「View less details」は間違っていますが、「View less detail」は適切です。複数名詞 (数えられる物) には、「fewer」を使用します。"
msgid "Correct. Do not use \"LINUX\" or \"linux\" unless referring to a command, such as \"To start Linux, type linux.\" Linux is a registered trademark of Linus Torvalds."
msgstr "適切です。コマンドを参照している場合 (たとえば「To start Linux, type linux」(Linux を起動する場合は、linux と入力します)) を除き、「LINUX」または「linux」を使用しないでください。Linux is a registered trademark of Linus Torvalds."
msgid "A verb used to refer to the act of logging in. Do not use \"login,\" \"loggin,\" \"logon,\" and other variants. For example, \"When starting your computer, you are requested to log in...\""
msgstr "ログインの動作を参照するために使用される動詞です。「login」、「loggin」、「loggin」などの形は使用しないでください。たとえば、「When starting your computer, you are requested to log in...」(コンピューターを起動すると、ログインを要求されます...) と表示されます。"
msgid "To make a computer system or network recognize you so that you can begin a computer session. Most personal computers have no log-on procedure -- you just turn the machine on and begin working. For larger systems and networks, however, you usually need to enter a username and password before the computer system will allow you to execute programs."
msgid "This means \"be careful to remember, attend to, or find out something.\" For example, \"...make sure that the rhedk group is listed in the output.\" Try to use verify or ensure instead."
msgstr "これは、「何かを覚えたり、注意したり、見つけたりするように注意する」という意味です。たとえば、「...make sure that the rhedk group is listed in the output.」(rhedk グループが出力の一覧に含まれていることを確認してください。) となります。代わりに verify や ensure を使用してください。"
msgid "Depends. If used as a noun, it is the actual time during which something takes place. For example, \"The computer may partly analyze the data in real time (as it comes in) -- R. H. March.\" If used as an adjective, \"real-time\" is appropriate. For example, \"XEmacs is a self-documenting, customizable, extensible, real-time display editor.\""
msgstr "状況によって異なります。名詞として使用する場合は、それは何かが行われる実際の時間になります。たとえば、「The computer may partly analyze the data in real time (as it comes in) -- R. H. March」(コンピュータはデータをリアルタイムで部分的に分析する場合があります。(R. H.マーチ)) となります。形容詞として使用する場合は、「real-time」が適切です。たとえば、「XEmacs is a self-documenting, customizable, extensible, real-time display editor.」(XEmacs は、自己文書化を行う、カスタマイズ可能で、拡張可能な、リアルタイムディスプレイエディターです。) となります。"
msgid "\"That\" introduces a restrictive clause-a clause that must be there for the sentence to make sense. A restrictive clause often defines the noun or phrase preceding it. \"Which\" introduces a non-restrictive, parenthetical clause-a clause that could be omitted without affecting the meaning of the sentence. For example: The car was travelling at a speed that would endanger lives. The car, which was traveling at a speed that would endanger lives, swerved onto the sidewalk. Use \"who\" or \"whom,\" rather than \"that\" or \"which,\" when referring to a person."
msgstr "「That」は、制限的関係詞節を導入します。これは、文が意味をなすために必要な節です。制限的関係詞節は、多くの場合、その前にある名詞または句を定義します。「Which」は、非制限の、括弧で囲まれた節を導入します。つまり、文の意味に影響を与えずに省略することができる節です。たとえば、「The car was travelling at a speed that would endanger lives.」(人命を危険にさらす速度で車が走行していました。) と、「The car, which was traveling at a speed that would endanger lives, swerved onto the sidewalk.」(人命を危険にさらす速度で走行していた車が歩道にのり上げました。) です。人を指す場合は、「that」または「which」ではなく「who」または「whom」を使用します。"
msgid "Correct. Do not use \"trouble shoot\" or \"trouble-shoot.\" To isolate the source of a problem and fix it. In the case of computer systems, the term troubleshoot is usually used when the problem is suspected to be hardware -related. If the problem is known to be in software, the term debug is more commonly used."
msgid "When referring to the reader, use \"you\" instead of \"user.\" For example, \"The user must...\" is incorrect. Use \"You must...\" instead. If referring to more than one user, calling the collection \"users\" is acceptable, such as \"Other users may wish to access your database.\""
msgstr "読み手を示す場合は、「user」ではなく「you」を使用します。たとえば、「The user must...」は正しくありません。代わりに「You must...」を使用してください。複数のユーザーを示す場合は、「users」を使用できます。たとえば、「Other users may to access your database.」(その他のユーザーがデータベースにアクセスすることを望む可能性があります。) です。"
msgid "Use the pronoun \"who\" as a subject. Use the pronoun \"whom\" as a direct object, an indirect object, or the object of a preposition. For example: Who owns this? To whom does this belong?"
msgstr "主語には、代名詞「who」を使用します。直接目的語、間接目的語、または前置詞の目的語には、代名詞の目的格「whom」を使用します。たとえば、「Who owns this?」(これは誰が所有していますか?) や、「To whom does this belong?」(これは誰のものですか?) となります。"
msgid "Do not use future tense unless it is absolutely necessary. For instance, do not use the sentence, \"The next section will describe the process in more detail.\" Instead, use the sentence, \"The next section describes the process in more detail.\""
msgstr "絶対に必要な場合を除いて、未来時制は使用しないでください。たとえば、「The next section will describe the process in more detail.」(次のセクションでプロセスを詳しく説明します。) ではなく、「The next section describes the process in more detail.」とします。"
msgid "Use \"need\" instead of \"desire\" and \"wish.\" Use \"want\" when the reader's actions are optional (that is, they may not \"need\" something but may still \"want\" something)."
msgid "Before a trademark is registered with the United States Patent and Trademark Office it is appropriate to use the TM or SM symbol depending whether the product is for goods or services. It is important to use the TM or SM as it is notification to the public that Ansible claims rights to the mark even though it has not yet been registered."
msgstr "商標が米国特許商標局に登録される前に、TM または SM のどちらの記号を使用するのが適切かは、製品が商品用かサービス用かによって異なります。TM または SM は、登録される前から、Ansible がそのマークに対する権利を主張していることを公に通知するため、TM または SM を使用することが重要です。"
msgid "Once the trademark is registered, it is appropriate to use the symbol in place of the TM or SM. The symbol designation must be used in conjunction with the trademark if Ansible is to fully protect its rights. If we don't protect these marks, we run the risk of losing them in the way of Aspirin or Trampoline or Escalator."
msgstr "商標が登録されたら、TM または SM の代わりにシンボルを使用することが適切です。Ansible がその権利を完全に保護する場合は、シンボルと商標を組み合わせて使用する必要があります。これらのマークを保護しないと、アスピリン、トランポリン、エスカレーターなどのように、権利を失う場合があります。"
msgid "Also add the trademark disclaimer. * When using Ansible trademarks in the body of written text, you should use the following credit line in a prominent place, usually a footnote."
msgid "For registered and unregistered trademarks: - [Name of Trademark] is a registered trademark and [Name of Trademark] is a trademark of Red Hat, Inc. in the United States and other countries."
msgstr "登録商標および未登録商標の場合: [Name of Trademark] is a registered trademark and [Name of Trademark] is a trademark of Red Hat, Inc. in the United States and other countries."
msgid "The Ansible trademark and the \"A\" logo in a shaded circle are our most valuable assets. The value of these trademarks encompass the Ansible Brand. Effective trademark use is more than just a name, it defines the level of quality the customer will receive and it ties a product or service to a corporate image. A trademark may serve as the basis for many of our everyday decisions and choices. The Ansible Brand is about how we treat customers and each other. In order to continue to build a stronger more valuable Brand we must use it in a clear and consistent manner."
msgid "Microsoft, Windows, Vista, XP, and NT are registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/en-us.aspx"
msgstr "- Microsoft, Windows, Vista, XP, and NT are registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/en-us.aspx"
msgid "Apple, Mac, Mac OS, Macintosh, Pages and TrueType are either registered trademarks or trademarks of Apple Computer, Inc. in the United States and/or other countries. https://www.apple.com/legal/intellectual-property/trademark/appletmlist.html"
msgstr "Apple, Mac, Mac OS, Macintosh, Pages and TrueType are either registered trademarks or trademarks of Apple Computer, Inc. in the United States and/or other countries. https://www.apple.com/legal/intellectual-property/trademark/appletmlist.html"
msgid "Adobe, Acrobat, GoLive, InDesign, Illustrator, PostScript , PhotoShop and the OpenType logo are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries. https://www.adobe.com/legal/permissions/trademarks.html"
msgstr "Adobe, Acrobat, GoLive, InDesign, Illustrator, PostScript , PhotoShop and the OpenType logo are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries. https://www.adobe.com/legal/permissions/trademarks.html"
msgid "Celeron, Celeron Inside, Centrino, Centrino logo, Core Inside, Intel Core, Intel Inside, Intel Inside logo, Itanium, Itanium Inside, Pentium, Pentium Inside,VTune, Xeon, and Xeon Inside are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries. https://www.intel.com/content/www/us/en/legal/trademarks.html"
msgstr "Celeron, Celeron Inside, Centrino, Centrino logo, Core Inside, Intel Core, Intel Inside, Intel Inside logo, Itanium, Itanium Inside, Pentium, Pentium Inside,VTune, Xeon, and Xeon Inside are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries. https://www.intel.com/content/www/us/en/legal/trademarks.html"
msgid "The essence of the Ansible writing style is short sentences that flow naturally together. Mix up sentence structures. Vary sentence subjects. Address the reader directly. Ask a question. And when the reader adjusts to the pace of shorter sentences, write a longer one."
msgid "When possible, start task-oriented sentences (those that direct a user to do something) with action words. For example: Find software... Contact support... Install the media.... and so forth."
msgstr "可能な場合は、タスク指向の文章 (ユーザーによる作業を指示する項目) は、動作を示す用語で開始します。たとえば、「Find software...」、「Contact support...」、「Install the media...」などです。"
msgid "Use the active voice (\"Start Linuxconf by typing...\") rather than passive (\"Linuxconf can be started by typing...\") whenever possible. Active voice makes for more lively, interesting reading. Also avoid future tense (or using the term \"will\") whenever possible For example, future tense (\"The screen will display...\") does not read as well as an active voice (\"The screen displays\"). Remember, the users you are writing for most often refer to the documentation while they are using the system, not after or in advance of using the system."
msgstr "可能な限り、受動態 (「Linuxconf can be started by typing...」) ではなく、能動態 (「Start Linuxconf by typing...」) を使用してください。能動態の方がより生き生きとした、注意を引き付ける文章になります。また、未来形 (または「will」の使用) は可能な限り使用しないでください。たとえば、未来形 (「The screen will display...」) と能動態 (「The screen displays」) では、ニュアンスが異なります。読者は、システムの使用前または使用後ではなく、システムの使用中にドキュメントを参照することがほとんどであることに注意してください。"
#: ../../rst/dev_guide/style_guide/why_use.rst:4
msgid "Why Use a Style Guide?"
msgstr "スタイルガイドを使用する理由"
#: ../../rst/dev_guide/style_guide/why_use.rst:6
msgid "Style guides are important because they ensure consistency in the content, look, and feel of a book or a website."
msgstr "スタイルガイドは、ドキュメントまたは Web サイトのコンテンツおよびルックアンドフィールの一貫性を確保するために重要です。"
#: ../../rst/dev_guide/style_guide/why_use.rst:8
msgid "Remember, a style guide is only useful if it is used, updated, and enforced. Style Guides are useful for engineering-related documentation, sales and marketing materials, support docs, community contributions, and more."
msgid "As changes are made to the overall Ansible site design, be sure to update this style guide with those changes. Or, should other resources listed below have major revisions, consider including company information here for ease of reference."
msgid "If you're a developer, one of the most valuable things you can do is to look at GitHub issues and help fix bugs, since bug-fixing is almost always prioritized over feature development. Even for non-developers, helping to test pull requests for bug fixes and features is still immensely valuable."
msgid "Ansible users who understand how to write playbooks and roles should be able to test their work. GitHub pull requests will automatically run a variety of tests (for example, Shippable) that show bugs in action. However, contributors must also test their work outside of the automated GitHub checks and show evidence of these tests in the PR to ensure that their work will be more likely to be reviewed and merged."
msgid "Tests directly against individual parts of the code base."
msgstr "コードベースの個々の部分に対して直接テストを行います。"
#: ../../rst/dev_guide/testing.rst:44
msgid "If you're a developer, one of the most valuable things you can do is look at the GitHub issues list and help fix bugs. We almost always prioritize bug fixing over feature development."
msgid "Even for non developers, helping to test pull requests for bug fixes and features is still immensely valuable. Ansible users who understand writing playbooks and roles should be able to add integration tests and so GitHub pull requests with integration tests that show bugs in action will also be a great way to help."
msgid "When Pull Requests (PRs) are created they are tested using Shippable, a Continuous Integration (CI) tool. Results are shown at the end of every PR."
msgid "When Shippable detects an error and it can be linked back to a file that has been modified in the PR then the relevant lines will be added as a GitHub comment. For example::"
msgid "From the above example we can see that ``--test pep8`` and ``--test validate-modules`` have identified an issue. The commands given allow you to run the same tests locally to ensure you've fixed all issues without having to push your changes to GitHub and wait for Shippable, for example:"
msgid "Then run the tests detailed in the GitHub comment::"
msgstr "次に、GitHub コメントで説明するテストを実行します。"
#: ../../rst/dev_guide/testing.rst:83
msgid "If there isn't a GitHub comment stating what's failed you can inspect the results by clicking on the \"Details\" button under the \"checks have failed\" message at the end of the PR."
msgstr "GitHub のコメントに何が失敗したかが書かれていない場合は、PR の末尾にある「checks have failed」というメッセージの下にある「Details」ボタンをクリックして結果を確認することができます。"
#: ../../rst/dev_guide/testing.rst:86
msgid "Rerunning a failing CI job"
msgstr "失敗した CI ジョブの再実行"
#: ../../rst/dev_guide/testing.rst:88
msgid "Occasionally you may find your PR fails due to a reason unrelated to your change. This could happen for several reasons, including:"
msgid "Ideally, code should add tests that prove that the code works. That's not always possible and tests are not always comprehensive, especially when a user doesn't have access to a wide variety of platforms, or is using an API or web service. In these cases, live testing against real equipment can be more valuable than automation that runs against simulated interfaces. In any case, things should always be tested manually the first time as well."
msgstr "理想的には、コードが機能することを証明するテストを追加することが推奨されます。特に、ユーザーが様々なプラットフォームにアクセスできない場合、または API や Web サービスを使用している場合は、これが必ずしも可能ではなく、テストも必ずしも包括的ではありません。このような場合は、シミュレーションされたインターフェースに対して実行される自動化よりも、実際の機器を使用したライブテストの方が有益でしょう。いずれにせよ、最初の段階でも常に手動でテストする必要があります。"
#: ../../rst/dev_guide/testing.rst:107
msgid "Thankfully, helping to test Ansible is pretty straightforward, assuming you are familiar with how Ansible works."
msgid "fetching the proposed changes into a test branch"
msgstr "テストブランチへの提案された変更の取得"
#: ../../rst/dev_guide/testing.rst:116
msgid "testing"
msgstr "テスト"
#: ../../rst/dev_guide/testing.rst:117
msgid "commenting on that particular issue on GitHub"
msgstr "GitHub に特定の問題についてのコメント"
#: ../../rst/dev_guide/testing.rst:119
msgid "Here's how:"
msgstr "以下に、実行する方法を説明します。"
#: ../../rst/dev_guide/testing.rst:122
msgid "Testing source code from GitHub pull requests sent to us does have some inherent risk, as the source code sent may have mistakes or malicious code that could have a negative impact on your system. We recommend doing all testing on a virtual machine, whether a cloud instance, or locally. Some users like Vagrant or Docker for this, but they are optional. It is also useful to have virtual machines of different Linux or other flavors, since some features (for example, package managers such as apt or yum) are specific to those OS versions."
msgstr "GitHub のプル要求から送られてきたソースコードをテストすることにはリスクが伴います。送られてきたソースコードには、間違いや悪意のあるコードが含まれていて、システムに影響を及ぼす可能性があるからです。すべてのテストは、仮想マシン上で行うことが推奨されます。クラウドインスタンスでもローカルでもかまいません。このために Vagrant や Docker を好むユーザーもいますが、これらは任意です。また、いくつかの機能 (たとえば、apt や yum などのパッケージマネージャー) は、それらの OS バージョンに固有のものであるため、異なる Linux やその他のフレーバーの仮想マシンを用意しておくと便利です。"
#: ../../rst/dev_guide/testing.rst:129
msgid "Create a fresh area to work::"
msgstr "作業用に新しい領域を作成します::"
#: ../../rst/dev_guide/testing.rst:135
msgid "Next, find the pull request you'd like to test and make note of its number. It will look something like this::"
msgstr "次に、テストするプル要求を見つけて、その番号を書き留めます。次のようになります。"
#: ../../rst/dev_guide/testing.rst:139
msgid "Only test ``ansible:devel``"
msgstr "``ansible:devel`` のみをテストします。"
#: ../../rst/dev_guide/testing.rst:141
msgid "It is important that the PR request target be ``ansible:devel``, as we do not accept pull requests into any other branch. Dot releases are cherry-picked manually by Ansible staff."
msgid "The first command fetches the proposed changes from the pull request and creates a new branch named ``testing_PRXXXX``, where the XXXX is the actual number associated with the pull request (for example, 65381). The second command checks out the newly created branch."
msgid "If the GitHub user interface shows that the pull request will not merge cleanly, we do not recommend proceeding if you are not somewhat familiar with git and coding, as you will have to resolve a merge conflict. This is the responsibility of the original pull request contributor."
msgid "Some users do not create feature branches, which can cause problems when they have multiple, unrelated commits in their version of ``devel``. If the source looks like ``someuser:devel``, make sure there is only one commit listed on the pull request."
msgid "The Ansible source includes a script that allows you to use Ansible directly from source without requiring a full installation that is frequently used by developers on Ansible."
msgid "This script modifies the ``PYTHONPATH`` environment variables (along with a few other things), which will be temporarily set as long as your shell session is open."
msgid "Any potential issues should be added as comments on the pull request (and it's acceptable to comment if the feature works as well), remembering to include the output of ``ansible --version``"
msgid "When I ran this Ubuntu 16.04 it failed with the following:"
msgstr "When I ran this Ubuntu 16.04 it failed with the following:"
#: ../../rst/dev_guide/testing.rst
msgid "\\```"
msgstr "\\```"
#: ../../rst/dev_guide/testing.rst
msgid "some output"
msgstr "some output"
#: ../../rst/dev_guide/testing.rst
msgid "StackTrace"
msgstr "StackTrace"
#: ../../rst/dev_guide/testing.rst
msgid "some other output"
msgstr "some other output"
#: ../../rst/dev_guide/testing.rst:223
msgid "Code Coverage Online"
msgstr "オンラインのコードカバレージ"
#: ../../rst/dev_guide/testing.rst:225
msgid "`The online code coverage reports <https://codecov.io/gh/ansible/ansible>`_ are a good way to identify areas for testing improvement in Ansible. By following red colors you can drill down through the reports to find files which have no tests at all. Adding both integration and unit tests which show clearly how code should work, verify important Ansible functions and increase testing coverage in areas where there is none is a valuable way to help improve Ansible."
msgid "The code coverage reports only cover the ``devel`` branch of Ansible where new feature development takes place. Pull requests and new code will be missing from the codecov.io coverage reports so local reporting is needed. Most ``ansible-test`` commands allow you to collect code coverage, this is particularly useful to indicate where to extend testing. See :ref:`testing_running_locally` for more information."
msgid "If you'd like to know more about the plans for improving testing Ansible then why not join the `Testing Working Group <https://github.com/ansible/community/blob/master/meetings/README.md>`_."
msgid "``test/lib/ansible_test/_data/requirements/sanity.import-plugins.txt`` must be an identical copy of ``requirements.txt`` found in the project's root."
msgid "The ``bin/`` directory in Ansible must contain only symbolic links to executable files. These files must reside in the ``lib/ansible/`` or ``test/lib/ansible_test/`` directories."
msgid "Symlinks for each entry point in ``bin/`` must also be present in ``test/lib/ansible_test/_data/injector/``. Each symlink should point to the ``python.py`` script in the same directory. This facilitates running with the correct Python interpreter and enabling code coverage."
msgid "The file ``examples/scripts/ConfigureRemotingForAnsible.ps1`` is required and must be a regular file. It is used by external automated processes and cannot be moved, renamed or replaced with a symbolic link."
msgid "The ``__init__.py`` files under the following directories must be empty. For some of these (modules and tests), ``__init__.py`` files with code won't be used. For others (module_utils), we want the possibility of using Python namespaces which an empty ``__init__.py`` will allow for."
msgid "This uses Python 3 semantics for absolute vs relative imports, division, and print. By doing this, we can write code which is portable between Python 2 and Python 3 by following the Python 3 semantics."
msgid "When Python 2 encounters an import of a name in a file like ``import copy`` it attempts to load ``copy.py`` from the same directory as the file is in. This can cause problems if there is a python file of that name in the directory and also a python module in ``sys.path`` with that same name. In that case, Python 2 would load the one in the same directory and there would be no way to load the one on ``sys.path``. Python 3 fixes this by making imports absolute by default. ``import copy`` will find ``copy.py`` from ``sys.path``. If you want to import ``copy.py`` from the same directory, the code needs to be changed to perform a relative import: ``from . import copy``."
msgid "In Python 2, the division operator (``/``) returns integer values when used with integers. If there was a remainder, this part would be left off (aka, `floor division`). In Python 3, the division operator (``/``) always returns a floating point number. Code that needs to calculate the integer portion of the quotient needs to switch to using the floor division operator (`//`) instead."
msgid "In Python 2, :func:`python:print` is a keyword. In Python 3, :func:`python3:print` is a function with different parameters. Using this ``__future__`` allows using the Python 3 print semantics everywhere."
msgid "Sanity tests are designed to improve code quality and identify common issues with content. When issues are identified during development, those issues should be corrected."
msgid "As development of Ansible continues, sanity tests are expanded to detect issues that previous releases could not. To allow time for existing content to be updated to pass newer tests, ignore entries can be added. New content should not use ignores for existing sanity tests."
msgid "When code is fixed to resolve sanity test errors, any relevant ignores must also be removed. If the ignores are not removed, this will be reported as an unnecessary ignore error. This is intended to prevent future regressions due to the same error recurring after being fixed."
msgid "If a sanity test results in a traceback when processing content, that error cannot be ignored. If this occurs, open a new `bug report <https://github.com/ansible/ansible/issues/new?template=bug_report.md>`_ for the issue so it can be fixed. If the traceback occurs due to an issue with the content, that issue should be fixed. If the content is correct, the test will need to be skipped until the bug in the sanity test is fixed."
msgid "Caution should be used when skipping sanity tests instead of ignoring them. Since the test is skipped entirely, resolution of the issue will not be automatically detected. This will prevent prevent regression detection from working once the issue has been resolved. For this reason it is a good idea to periodically review skipped entries manually to verify they are required."
msgid "The ignore file contains one entry per line. Each line consists of two columns, separated by a single space. Comments may be added at the end of an entry, started with a hash (``#``) character, which can be proceeded by zero or more spaces. Blank and comment only lines are not allowed."
msgid "The first column specifies the file path that the entry applies to. File paths must be relative to the root of the content being tested. This is either the Ansible source or an Ansible collection. File paths cannot contain a space or the hash (``#``) character."
msgid "The second column specifies the sanity test that the entry applies to. This will be the name of the sanity test. If the sanity test is specific to a version of Python, the name will include a dash (``-``) and the relevant Python version. If the named test uses error codes then the error code to ignore must be appended to the name of the test, separated by a colon (``:``)."
msgid "It is also possible to skip a sanity test for a specific file. This is done by adding ``!skip`` after the sanity test name in the second column. When this is done, no error code is included, even if the sanity test uses error codes."
msgid "Ansible allows unchecked imports of some libraries from specific directories, listed at the bottom of this section. Import all other Python libraries in a try/except ImportError block to support sanity tests such as ``validate-modules`` and to allow Ansible to give better error messages to the user. To import a library in a try/except ImportError block:"
msgid "For ``lib/ansible/plugins/``, unchecked imports are only allowed from the Python standard library, from dependencies of ansible-core, and from ansible-core itself;"
msgid "For other directories in ``plugins/`` (see `the community collection requirements <https://github.com/ansible-collections/overview/blob/main/collection_requirements.rst#modules-plugins>`_ for a list), unchecked imports are only allowed from the Python standard library, from dependencies of ansible-core, and from ansible-core itself."
msgid "The following sanity tests are available as ``--test`` options for ``ansible-test sanity``. This list is also available using ``ansible-test sanity --list-tests --allow-disabled``."
msgid "Integration tests are executed by ``ansible-test`` and reside in directories under ``test/integration/targets/``. Each test MUST have an ``aliases`` file to control test execution."
msgid "Groups are used to balance tests across multiple CI jobs to minimize test run time. They also improve efficiency by keeping tests with similar requirements running together."
msgstr "グループは、複数の CI ジョブ間でテストのバランスを取り、テストのランタイムを最小限にするために使用します。同様の要件が一緒に実行されるテストを維持することで、効率性も向上します。"
msgid "When selecting a group for a new test, use the same group as existing tests similar to the one being added. If more than one group is available, select one randomly."
msgid "Tests which fail sometimes should be marked with the ``unstable`` alias until the instability has been fixed. These tests will continue to run for pull requests which modify the test or the module under test."
msgid "Tests which cannot be run in CI should be marked with the ``unsupported`` alias. Most tests can be supported through the use of simulators and/or cloud plugins."
msgid "Tests that are marked as unstable_ or disabled_ will have an issue created to track the status of the test. Each issue will be assigned to one of the following projects:"
msgid "Most Python files should include the following boilerplate at the top of the file, right after the comment header and ``from __future__ import``:"
msgid "Python 2 has \"new-style classes\" and \"old-style classes\" whereas Python 3 only has new-style classes. Adding the ``__metaclass__ = type`` boilerplate makes every class defined in that file into a new-style class as well."
msgid "Do not use ``assert`` in production Ansible python code. When running Python with optimizations, Python will remove ``assert`` statements, potentially allowing for unexpected behavior throughout the Ansible code base."
msgid "Instead of using ``assert`` you should utilize simple ``if`` statements, that result in raising an exception. There is a new exception called ``AnsibleAssertionError`` that inherits from ``AnsibleError`` and ``AssertionError``. When possible, utilize a more specific exception than ``AnsibleAssertionError``."
msgid "Modules will not have access to ``AnsibleAssertionError`` and should instead raise ``AssertionError``, a more specific exception, or just use ``module.fail_json`` at the failure point."
msgid "Do not use ``isinstance(s, basestring)`` as basestring has been removed in Python3. You can import ``string_types``, ``binary_type``, or ``text_type`` from ``ansible.module_utils.six`` and then use ``isinstance(s, string_types)`` or ``isinstance(s, (binary_type, text_type))`` instead."
msgid "If this is part of code to convert a string to a particular type, ``ansible.module_utils._text`` contains several functions that may be even better for you: ``to_text``, ``to_bytes``, and ``to_native``."
msgid "We created a function, ``ansible.module_utils.pycompat24.get_exception`` to help retrieve exceptions in a manner compatible with Python 2.4 through Python 3.6. We no longer support Python 2.4 and Python 2.5 so this is extraneous and we want to deprecate the function. Porting code should look something like this:"
msgid "Prior to Ansible 2.5, Jinja2 tests included within Ansible were most often used as filters. The large difference in use is that filters are referenced as ``variable | filter_name`` while Jinja2 tests are referenced as ``variable is test_name``."
msgid "Jinja2 tests are used for comparisons, whereas filters are used for data manipulation, and have different applications in Jinja2. This change is to help differentiate the concepts for a better understanding of Jinja2, and where each can be appropriately used."
msgid "In the future, Ansible may use the identifier ``_`` to internationalize its message strings. To be ready for that, we need to make sure that there are no conflicting identifiers defined in the code base."
msgid "In common practice, ``_`` is frequently used as a dummy variable (a variable to receive a value from a function where the value is useless and never used). In Ansible, we're using the identifier ``dummy`` for this purpose instead."
msgid "It makes it so one can't jump into the middle of a file and know whether a bare literal string is a byte string or text string. The programmer has to first check the top of the file to see if the import is there."
msgid "It removes the ability to define native strings (a string which should be a byte string on python2 and a text string on python3) via a string literal."
msgid "It makes for more context switching. A programmer could be reading one file which has `unicode_literals` and know that bare string literals are text strings but then switch to another file (perhaps tracing program execution into a third party library) and have to switch their understanding of what bare string literals are."
msgid "Using :code:`import *` is a bad habit which pollutes your namespace, hinders debugging, and interferes with static analysis of code. For those reasons, we do want to limit the use of :code:`import *` in the ansible code. Change our code to import the specific names that you need instead."
msgid "Directories in the Ansible source tree are sometimes made obsolete. Files should not exist in these directories. The new location (if any) is dependent on which directory has been made obsolete."
msgid "This error occurs most frequently for open pull requests which add or modify files in directories which are now obsolete. Make sure the branch you are working from is current so that changes can be made in the correct location."
msgid "Verifies that the combination of ``MANIFEST.in`` and ``package_data`` from ``setup.py`` properly installs data files from within ``lib/ansible``"
msgid "The bundled code is out of date with regard to the latest release on pypi. Update the code to the new version and update the version in _BUNDLED_METADATA to solve this."
msgid "The code is lacking a _BUNDLED_METADATA variable. This typically happens when a bundled version is updated and we forget to add a _BUNDLED_METADATA variable to the updated file. Once that is added, this error should go away."
msgid "A file has a _BUNDLED_METADATA variable but the file isn't specified in :file:`test/sanity/code-smell/update-bundled.py`. This typically happens when a new bundled library is added. Add the file to the `get_bundled_libs()` function in the `update-bundled.py` test script to solve this error."
msgid "Optional PEP440 specifier for the version range that we are bundling. Currently, the only valid use of this is to follow a version that is compatible with the Python stdlib when newer versions of the pypi package implement a new API."
msgstr "バンドルするバージョン範囲の任意の PEP440 指定子。現在、これの唯一の有効な使用法は、新しいバージョンの pypi パッケージが新しい API を実装するときに、Python stdlib と互換性のあるバージョンに従うことです。"
msgid "The AnsibleModule argument_spec knows of several types beyond the standard python types. One of these is ``path``. When used, type ``path`` ensures that an argument is a string and expands any shell variables and tilde characters."
msgid "This test looks for use of :func:`os.path.expanduser <python:os.path.expanduser>` in modules. When found, it tells the user to replace it with ``type='path'`` in the module's argument_spec or list it as a false positive in the test."
msgid "NOTE: In Ansible 2.4 and earlier the compile test was provided by a dedicated sub-command ``ansible-test compile`` instead of a sanity test using ``ansible-test sanity --test compile``."
msgid "The full list of requirements can be found at `test/lib/ansible_test/_data/requirements <https://github.com/ansible/ansible/tree/devel/test/lib/ansible_test/_data/requirements>`_. Requirements files are named after their respective commands. See also the `constraints <https://github.com/ansible/ansible/blob/devel/test/lib/ansible_test/_data/requirements/constraints.txt>`_ applicable to all commands."
msgid "If you believe changes are needed to the compile tests please add a comment on the `Testing Working Group Agenda <https://github.com/ansible/community/blob/master/meetings/README.md>`_ so it can be discussed."
msgid "Before you submit a module for inclusion in the main Ansible repo, you must test your module documentation for correct HTML rendering and to ensure that the argspec matches the documentation in your Python file. The community pages offer more information on :ref:`testing reStructuredText documentation <testing_documentation_locally>`."
msgid "``httptester`` is a docker container used to host certain resources required by :ref:`testing_integration`. This is to avoid CI tests requiring external resources (such as git or package repos) which, if temporarily unavailable, would cause tests to fail."
msgstr "``httptester`` は、:ref:`testing_integration` で必要な特定のリソースをホストするために使用される docker コンテナーです。これにより、(git やパッケージリポジトリーなどの) 外部リソースを必要とする CI テストが回避され、一時的に利用できなくなるとテストが失敗します。"
#: ../../rst/dev_guide/testing_httptester.rst:14
msgid "HTTP Testing endpoint which provides the following capabilities:"
msgstr "以下の機能を提供する HTTP テストエンドポイントです。"
#: ../../rst/dev_guide/testing_httptester.rst:16
msgid "httpbin"
msgstr "httpbin"
#: ../../rst/dev_guide/testing_httptester.rst:17
msgid "nginx"
msgstr "nginx"
#: ../../rst/dev_guide/testing_httptester.rst:18
msgid "SSL"
msgstr "SSL"
#: ../../rst/dev_guide/testing_httptester.rst:19
msgid "SNI"
msgstr "SNI"
#: ../../rst/dev_guide/testing_httptester.rst:20
msgid "Negotiate Authentication"
msgstr "認証のネゴシエート"
#: ../../rst/dev_guide/testing_httptester.rst:23
msgid "Source files can be found in the `http-test-container <https://github.com/ansible/http-test-container>`_ repository."
msgid "If you have sometime to improve ``httptester`` please add a comment on the `Testing Working Group Agenda <https://github.com/ansible/community/blob/master/meetings/README.md>`_ to avoid duplicated effort."
msgid "It is highly recommended that you install and activate the ``argcomplete`` python package. It provides tab completion in ``bash`` for the ``ansible-test`` test runner."
msgid "The example below assumes ``bin/`` is in your ``$PATH``. An easy way to achieve that is to initialize your environment with the ``env-setup`` command::"
msgid "You can also call ``ansible-test`` with the full path::"
msgstr "完全パスで ``ansible-test`` を呼び出すこともできます。"
#: ../../rst/dev_guide/testing_integration.rst:46
msgid "integration_config.yml"
msgstr "integration_config.yml"
#: ../../rst/dev_guide/testing_integration.rst:48
msgid "Making your own version of ``integration_config.yml`` can allow for setting some tunable parameters to help run the tests better in your environment. Some tests (for example, cloud tests) will only run when access credentials are provided. For more information about supported credentials, refer to the various ``cloud-config-*.template`` files in the ``test/integration/`` directory."
msgid "Some tests assume things like hg, svn, and git are installed, and in path. Some tests (such as those for Amazon Web Services) need separate definitions, which will be covered later in this document."
msgstr "一部のテストでは、hg、svn、git などがインストールされ、パスにあることを前提としています。一部のテスト (Amazon Web Services のテストなど) には個別の定義が必要です。これについては、このドキュメントの後半で説明します。"
#: ../../rst/dev_guide/testing_integration.rst:61
msgid "(Complete list pending)"
msgstr "(完全はリストは後に追加されます)"
#: ../../rst/dev_guide/testing_integration.rst:64
msgid "Non-destructive Tests"
msgstr "非破壊テスト"
#: ../../rst/dev_guide/testing_integration.rst:66
msgid "These tests will modify files in subdirectories, but will not do things that install or remove packages or things outside of those test subdirectories. They will also not reconfigure or bounce system services."
msgid "To protect your system from any potential changes caused by integration tests, and to ensure a sensible set of dependencies are available we recommend that you always run integration tests with the ``--docker`` option, for example ``--docker centos8``. See the `list of supported docker images <https://github.com/ansible/ansible/blob/devel/test/lib/ansible_test/_data/completion/docker.txt>`_ for options (the ``default`` image is used for sanity and unit tests, as well as for platform independent integration tests such as those for cloud modules)."
msgid "Use the ``--docker-no-pull`` option to avoid pulling the latest container image. This is required when using custom local images that are not available for download."
msgid "These tests are allowed to install and remove some trivial packages. You will likely want to devote these to a virtual environment, such as Docker. They won't reformat your filesystem::"
msgid "These tests exercise the ``winrm`` connection plugin and Windows modules. You'll need to define an inventory with a remote Windows 2008 or 2012 Server to use for testing, and enable PowerShell Remoting to continue."
msgstr "これらのテストは、``winrm`` 接続プラグインと Windows モジュールに従います。テストに使用するリモート Windows 2008 Server または 2012 Server を持つインベントリーを定義し、PowerShell Remoting を継続できるようにする必要があります。"
msgid "If you have a Linux system with Docker installed, running integration tests using the same Docker containers used by the Ansible continuous integration (CI) system is recommended."
msgstr "Docker がインストールされた Linux システムをお持ちの場合は、Ansible の継続的インテグレーション (CI) システムで使用されているものと同じ Docker コンテナーを使用して統合テストを実行することが推奨されます。"
msgid "Using Docker Engine to run Docker on a non-Linux host (such as macOS) is not recommended. Some tests may fail, depending on the image used for testing. Using the ``--docker-privileged`` option when running ``integration`` (not ``network-integration`` or ``windows-integration``) may resolve the issue."
msgid "You can also run specific tests or select a different Linux distribution. For example, to run tests for the ``ping`` module on a Ubuntu 18.04 container::"
msgstr "特定のテストを実行することも、別の Linux ディストリビューションを選択することもできます。たとえば、Ubuntu 18.04 コンテナーで ``ping`` モジュールのテストを実行するには、次を実行します。"
msgid "Some of the cloud tests run as normal integration tests, and others run as legacy tests; see the :ref:`testing_integration_legacy` page for more information."
msgid "In order to run some tests, you must provide access credentials in a file named ``cloud-config-aws.yml`` or ``cloud-config-cs.ini`` in the test/integration directory. Corresponding .template files are available for for syntax help. The newer AWS tests now use the file test/integration/cloud-config-aws.yml"
msgid "Ansible needs fairly wide ranging powers to run the tests in an AWS account. This rights can be provided to a dedicated user. These need to be configured before running the test."
msgid "The GitHub repository `mattclay/aws-terminator <https://github.com/mattclay/aws-terminator/>`_ contains two sets of policies used for all existing AWS module integratoin tests. The `hacking/aws_config/setup_iam.yml` playbook can be used to setup two groups:"
msgid "`ansible-integration-ci` will have the policies applied necessary to run any integration tests not marked as `unsupported` and are designed to mirror those used by Ansible's CI."
msgstr "`ansible-integration-ci` は、インテグレーションテストの実行に必要となるポリシーを適用すると共に、`unsupported` と識別されず、Ansible の CI で使用されるミラーリング用に設計されています。"
msgid "`ansible-integration-unsupported` will have the additional policies applied necessary to run the integration tests marked as `unsupported` including tests for managing IAM roles, users and groups."
msgid "Once the groups have been created, you'll need to create a user and make the user a member of these groups. The policies are designed to minimize the rights of that user. Please note that while this policy does limit the user to one region, this does not fully restrict the user (primarily due to the limitations of the Amazon ARN notation). The user will still have wide privileges for viewing account definitions, and will also able to manage some resources that are not related to testing (for example, AWS lambdas with different names). Tests should not be run in a primary production account in any case."
msgid "Apart from installing the policy and giving it to the user identity running the tests, a lambda role `ansible_integration_tests` has to be created which has lambda basic execution privileges."
msgstr "ポリシーをインストールしてテストを実行しているユーザ ID に付与することとは別に、ラムダロール `ansible_integration_tests` を作成する必要があります。これは、ラムダの基本的な実行権限を持ちます。"
msgid "If you'd like to know more about the plans for improving testing Ansible, join the `Testing Working Group <https://github.com/ansible/community/blob/master/meetings/README.md>`_."
msgid "Cloud tests exercise capabilities of cloud modules (for example, ec2_key). These are not 'tests run in the cloud' so much as tests that leverage the cloud modules and are organized by cloud provider."
msgid "Some AWS tests may use environment variables. It is recommended to either unset any AWS environment variables( such as ``AWS_DEFAULT_PROFILE``, ``AWS_SECRET_ACCESS_KEY``, and so on) or be sure that the environment variables match the credentials provided in ``credentials.yml`` to ensure the tests run with consistency to their full capability on the expected account. See `AWS CLI docs <https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html>`_ for information on creating a profile."
msgid "In order to run cloud tests, you must provide access credentials in a file named ``credentials.yml``. A sample credentials file named ``credentials.template`` is available for syntax help."
msgid "In order to run some tests, you must provide access credentials in a file named ``credentials.yml``. A sample credentials file named ``credentials.template`` is available for syntax help."
msgid "In order to run the tests in an AWS account ansible needs fairly wide ranging powers which can be provided to a dedicated user or temporary credentials using a specific policy configured in the AWS account."
msgid "The testing-iam-policy.json.j2 file contains a policy which can be given to the user running the tests to give close to minimum rights required to run the tests. Please note that this does not fully restrict the user; The user has wide privileges for viewing account definitions and is also able to manage some resources that are not related to testing (for example, AWS lambdas with different names) primarily due to the limitations of the Amazon ARN notation. At the very least the policy limits the user to one region, however tests should not be run in a primary production account in any case."
msgid "Running cloud integration tests will create and destroy cloud resources. Running these tests may result in additional fees associated with your cloud account. Care is taken to ensure that created resources are removed. However, it is advisable to inspect your AWS console to ensure no unexpected resources are running."
msgid "There are no special requirements for running ``ansible-test`` on Python 2.7 or later. The ``argparse`` package is required for Python 2.6. The requirements for each ``ansible-test`` command are covered later."
msgid "See the `list of supported platforms and versions <https://github.com/ansible/ansible/blob/devel/test/lib/ansible_test/_data/completion/remote.txt>`_ for additional details."
msgid "Example: ``ANSIBLE_KEEP_REMOTE_FILES=1`` can be set when running ``ansible-test integration --venv``. However, using the ``--docker`` option would require running ``ansible-test shell`` to gain access to the Docker environment. Once at the shell prompt, the environment variable could be set and the tests executed. This is useful for debugging tests inside a container by following the :ref:`Debugging AnsibleModule-based modules <debugging_modules>` instructions."
msgid "Code coverage reports make it easy to identify untested code for which more tests should be written. Online reports are available but only cover the ``devel`` branch (see :ref:`developing_testing`). For new code local reports are needed."
msgid "Add the ``--coverage`` option to any test command to collect code coverage data. If you aren't using the ``--venv`` or ``--docker`` options which create an isolated python environment then you may have to use the ``--requirements`` option to ensure that the correct version of the coverage module is installed::"
msgid "Sanity tests are made up of scripts and tools used to perform static code analysis. The primary purpose of these tests is to enforce Ansible coding standards and requirements."
msgid "Unit tests are small isolated tests that target a specific library or module. Unit tests in Ansible are currently the only way of driving tests from python within Ansible's continuous integration process. This means that in some circumstances the tests may be a bit wider than just units."
msgid "Unit tests can be found in `test/units <https://github.com/ansible/ansible/tree/devel/test/units>`_. Notice that the directory structure of the tests matches that of ``lib/ansible/``."
msgid "You can also run tests in Ansible's continuous integration system by opening a pull request. This will automatically determine which tests to run based on the changes made in your pull request."
msgid "Otherwise you can install dependencies using the ``--requirements`` option, which will install all the required dependencies needed for unit tests. For example:"
msgid "The list of unit test requirements can be found at `test/units/requirements.txt <https://github.com/ansible/ansible/tree/devel/test/units/requirements.txt>`_."
msgid "This does not include the list of unit test requirements for ``ansible-test`` itself, which can be found at `test/lib/ansible_test/_data/requirements/units.txt <https://github.com/ansible/ansible/tree/devel/test/lib/ansible_test/_data/requirements/units.txt>`_."
msgid "See also the `constraints <https://github.com/ansible/ansible/blob/devel/test/lib/ansible_test/_data/requirements/constraints.txt>`_ applicable to all test commands."
msgid "Ansible drives unit tests through `pytest <https://docs.pytest.org/en/latest/>`_. This means that tests can either be written a simple functions which are included in any file name like ``test_<something>.py`` or as classes."
msgid "Both methods work fine in most circumstances; the function-based interface is simpler and quicker and so that's probably where you should start when you are just trying to add a few basic tests for a module. The class-based test allows more tidy set up and tear down of pre-requisites, so if you have many test cases for your module you may want to refactor to use that."
msgid "Assertions using the simple ``assert`` function inside the tests will give full information on the cause of the failure with a trace-back of functions called during the assertion. This means that plain asserts are recommended over other external assertion libraries."
msgid "A number of the unit test suites include functions that are shared between several modules, especially in the networking arena. In these cases a file is created in the same directory, which is then included directly."
msgid "Keep common code as specific as possible within the `test/units/` directory structure. Don't import common unit test code from directories outside the current or parent directories."
msgid "To mock out fetching results from devices, or provide other complex data structures that come from external libraries, you can use ``fixtures`` to read in pre-generated data."
msgid "You can check how `fixtures <https://github.com/ansible/ansible/tree/devel/test/units/module_utils/facts/fixtures/cpuinfo>`_ are used in `cpuinfo fact tests <https://github.com/ansible/ansible/blob/9f72ff80e3fe173baac83d74748ad87cb6e20e64/test/units/module_utils/facts/hardware/linux_data.py#L384>`_"
msgid "Code Coverage For New or Updated Unit Tests"
msgstr "新規ユニットテストまたは更新されたユニットテスト用のコード対応"
#: ../../rst/dev_guide/testing_units.rst:178
msgid "New code will be missing from the codecov.io coverage reports (see :ref:`developing_testing`), so local reporting is needed. Most ``ansible-test`` commands allow you to collect code coverage; this is particularly useful when to indicate where to extend testing."
msgid "To clear data between test runs, use the ``ansible-test coverage erase`` command. See :ref:`testing_running_locally` for more information about generating coverage reports."
msgid "This document explains why, how and when you should use unit tests for Ansible modules. The document doesn't apply to other parts of Ansible for which the recommendations are normally closer to the Python standard. There is basic documentation for Ansible unit tests in the developer guide :ref:`testing_units`. This document should be readable for a new Ansible module author. If you find it incomplete or confusing, please open a bug or ask for help on Ansible IRC."
msgid "Ansible includes a set of unit tests in the :file:`test/units` directory. These tests primarily cover the internals but can also cover Ansible modules. The structure of the unit tests matches the structure of the code base, so the tests that reside in the :file:`test/units/modules/` directory are organized by module groups."
msgid "Integration tests can be used for most modules, but there are situations where cases cannot be verified using integration tests. This means that Ansible unit test cases may extend beyond testing only minimal units and in some cases will include some level of functional testing."
msgid "Most unit tests are much faster than most Ansible integration tests. The complete suite of unit tests can be run regularly by a developer on their local system."
msgid "Unit tests can be run by developers who don't have access to the system which the module is designed to work on, allowing a level of verification that changes to core functions haven't broken module expectations."
msgid "Unit tests can easily substitute system functions allowing testing of software that would be impractical. For example, the ``sleep()`` function can be replaced and we check that a ten minute sleep was called without actually waiting ten minutes."
msgid "There are also some potential disadvantages of unit tests. Unit tests don't normally directly test actual useful valuable features of software, instead just internal implementation"
msgid "Unit tests that test the internal, non-visible features of software may make refactoring difficult if those internal features have to change (see also naming in How below)"
msgid "Even if the internal feature is working correctly it is possible that there will be a problem between the internal code tested and the actual result delivered to the user"
msgid "Normally the Ansible integration tests (which are written in Ansible YAML) provide better testing for most module functionality. If those tests already test a feature and perform well there may be little point in providing a unit test covering the same area as well."
msgid "There are a number of situations where unit tests are a better choice than integration tests. For example, testing things which are impossible, slow or very difficult to test with integration tests, such as:"
msgid "A single step of the rds_instance test cases can take up to 20 minutes (the time to create an RDS instance in Amazon). The entire test run can last for well over an hour. All 16 of the unit tests complete execution in less than 2 seconds."
msgid "The time saving provided by being able to run the code in a unit test makes it worth creating a unit test when bug fixing a module, even if those tests do not often identify problems later. As a basic goal, every module should have at least one unit test which will give quick feedback in easy cases without having to wait for the integration tests to complete."
msgid "Unit tests can check the way in which external services are run to ensure that they match specifications or are as efficient as possible *even when the final output will not be changed*."
msgid "Package managers are often far more efficient when installing multiple packages at once rather than each package separately. The final result is the same: the packages are all installed, so the efficiency is difficult to verify through integration tests. By providing a mock package manager and verifying that it is called once, we can build a valuable test for module efficiency."
msgid "Another related use is in the situation where an API has versions which behave differently. A programmer working on a new version may change the module to work with the new API version and unintentionally break the old version. A test case which checks that the call happens properly for the old version can help avoid the problem. In this situation it is very important to include version numbering in the test case name (see `Naming unit tests`_ below)."
msgstr "別の関連する使用法は、API の動作が異なるバージョンがある状況です。新しいバージョンで作業しているプログラマーは、新しい API バージョンで動作するようにモジュールを変更し、意図せずに古いバージョンを壊してしまう可能性があります。古いバージョンで呼び出しが適切に行われることを確認するテストケースは、問題を回避するのに役立ちます。この状況では、テストケース名にバージョン番号を含めることが非常に重要です (以下 `Naming unit tests`_ を参照)。"
msgid "By building a requirement for a particular part of the code and then coding to that requirement, unit tests _can_ sometimes improve the code and help future developers understand that code."
msgid "Unit tests that test internal implementation details of code, on the other hand, almost always do more harm than good. Testing that your packages to install are stored in a list would slow down and confuse a future developer who might need to change that list into a dictionary for efficiency. This problem can be reduced somewhat with clear test naming so that the future developer immediately knows to delete the test case, but it is often better to simply leave out the test case altogether and test for a real valuable feature of the code, such as installing all of the packages supplied as arguments to the module."
msgid "There are a number of techniques for unit testing modules. Beware that most modules without unit tests are structured in a way that makes testing quite difficult and can lead to very complicated tests which need more work than the code. Effectively using unit tests may lead you to restructure your code. This is often a good thing and leads to better code overall. Good restructuring can make your code clearer and easier to understand."
msgid "Unit tests should have logical names. If a developer working on the module being tested breaks the test case, it should be easy to figure what the unit test covers from the name. If a unit test is designed to verify compatibility with a specific software or API version then include the version in the name of the unit test."
msgstr "ユニットテストは論理名を付ける必要があります。テスト対象のモジュールで作業している開発者がテストケースを壊してしまった場合に、ユニットテストが何を対象としているのかが名前から簡単に分かるようにする必要があります。ユニットテストが特定のソフトウェアや API のバージョンとの互換性を検証するように設計されている場合は、ユニットテストの名前にそのバージョンを追加してください。"
msgid "Mock objects (from https://docs.python.org/3/library/unittest.mock.html) can be very useful in building unit tests for special / difficult cases, but they can also lead to complex and confusing coding situations. One good use for mocks would be in simulating an API. As for 'six', the 'mock' python package is bundled with Ansible (use ``import units.compat.mock``)."
msgid "Functions like :meth:`module.fail_json` are normally expected to terminate execution. When you run with a mock module object this doesn't happen since the mock always returns another mock from a function call. You can set up the mock to raise an exception as shown above, or you can assert that these functions have not been called in each test. For example::"
msgid "The setup of an actual module is quite complex (see `Passing Arguments`_ below) and often isn't needed for most functions which use a module. Instead you can use a mock object as the module and create any module attributes needed by the function you are testing. If you do this, beware that the module exit functions need special handling as mentioned above, either by throwing an exception or ensuring that they haven't been called. For example::"
msgid "API interaction is usually best tested with the function tests defined in Ansible's integration testing section, which run against the actual API. There are several cases where the unit tests are likely to work better."
msgstr "API の対話は通常、実際の API に対して実行される Ansible の統合テストで定義された関数テストで最適です。ユニットテストが適切に機能する可能性があります。"
msgid "This case is especially important for modules interacting with web services, which provide an API that Ansible uses but which are beyond the control of the user."
msgstr "このケースは、Ansible が使用する API を提供しているが、ユーザーの制御が及ばない Web サービスと対話するモジュールにとって特に重要です。"
msgid "By writing a custom emulation of the calls that return data from the API, we can ensure that only the features which are clearly defined in the specification of the API are present in the message. This means that we can check that we use the correct parameters and nothing else."
msgid "These states are then used as returns from a mock object to ensure that the ``await`` function waits through all of the states that would mean the RDS instance has not yet completed configuration::"
msgid "By doing this we check that the ``await`` function will keep waiting through potentially unusual that it would be impossible to reliably trigger through the integration tests but which happen unpredictably in reality."
msgid "This case is especially important for modules interacting with many different versions of software; for example, package installation modules that might be expected to work with many different operating system versions."
msgid "By using previously stored data from various versions of an API we can ensure that the code is tested against the actual data which will be sent from that version of the system even when the version is very obscure and unlikely to be available during testing."
msgstr "様々なバージョンの API から、以前に保存されたデータを使用することで、バージョンが非常に曖昧でテスト中に利用できそうにない場合でも、そのバージョンのシステムから送信される実際のデータに対してコードがテストできるようになります。"
msgid "There are a number of special cases for unit testing the environment of an Ansible module. The most common are documented below, and suggestions for others can be found by looking at the source code of the existing unit tests or asking on the Ansible IRC channel or mailing lists."
msgid "Since the module is supposed to accept arguments on ``STDIN`` it is a bit difficult to set up the arguments correctly so that the module will get them as parameters."
msgid "All modules should finish by calling either the :meth:`module.fail_json` or :meth:`module.exit_json`, but these won't work correctly in a testing environment."
msgid "To pass arguments to a module correctly, use the ``set_module_args`` method which accepts a dictionary as its parameter. Module creation and argument processing is handled through the :class:`AnsibleModule` object in the basic section of the utilities. Normally this accepts input on ``STDIN``, which is not convenient for unit testing. When the special variable is set it will be treated as if the input came on ``STDIN`` to the module. Simply call that function before setting up your module::"
msgid "The :meth:`module.exit_json` function won't work properly in a testing environment since it writes error information to ``STDOUT`` upon exit, where it is difficult to examine. This can be mitigated by replacing it (and :meth:`module.fail_json`) with a function that raises an exception::"
msgid "The same technique can be used to replace :meth:`module.fail_json` (which is used for failure returns from modules) and for the ``aws_module.fail_json_aws()`` (used in modules for Amazon Web Services)."
msgstr "同じテクニックを使用して、:meth:`module.fail_json` (モジュールから返る障害に使用) および ``aws_module.fail_json_aws()`` (Amazon Web Services のモジュールに使用) に置き換えることができます。"
msgid "If you do want to run the actual main function of a module you must import the module, set the arguments as above, set up the appropriate exit exception and then run the module::"
msgid "Often modules have a ``main()`` function which sets up the module and then performs other actions. This can make it difficult to check argument processing. This can be made easier by moving module configuration and initialization into a separate function. For example::"
msgid "Note that the ``argument_spec`` dictionary is visible in a module variable. This has advantages, both in allowing explicit testing of the arguments and in allowing the easy creation of module objects for testing."
msgid "The same restructuring technique can be valuable for testing other functionality, such as the part of the module which queries the object that the module configures."
msgid "If you use the ``mock`` library from the Python 2.6 standard library, a number of the assert functions are missing but will return as if successful. This means that test cases should take great care *not* use functions marked as _new_ in the Python 3 documentation, since the tests will likely always succeed even if the code is broken when run on older versions of Python."
msgid "A helpful development approach to this should be to ensure that all of the tests have been run under Python 2.6 and that each assertion in the test cases has been checked to work by breaking the code in Ansible to trigger that failure."
msgid "Please remember that modules need to maintain compatibility with Python 2.6 so the unittests for modules should also be compatible with Python 2.6."
msgid "Unit testing is a part of the of various philosophies of software development, including Extreme Programming (XP), Clean Coding. Uncle Bob talks through how to benefit from this"
msgstr "ユニットテストは、Extreme Programming (XP)、クリーンコーディングを含むソフトウェア開発の様々な哲学の一部です。Uncle Bob は、どのようにしてこの恩恵を受けることができるのかを説明します。"
msgid "The ``validate-modules`` tool has a `schema.py <https://github.com/ansible/ansible/blob/devel/test/lib/ansible_test/_data/sanity/validate-modules/validate_modules/schema.py>`_ that is used to validate the YAML blocks, such as ``DOCUMENTATION`` and ``RETURNS``."
msgid "Module marked as deprecated or removed in at least one of the filename, its metadata, or in DOCUMENTATION (setting DOCUMENTATION.deprecated for deprecation or removing all Documentation for removed) but not in all three places."
msgid "The version at which a feature is supposed to be removed cannot be parsed (for collections, it must be a semantic version, see https://semver.org/)"
msgid "Argument ``state`` includes ``get``, ``list`` or ``info`` as a choice. Functionality should be in an ``_info`` or (if further conditions apply) ``_facts`` module."
msgid "According to the semantic versioning specification (https://semver.org/), the only versions in which features are allowed to be removed are major versions (x.0.0)"
msgid "According to the semantic versioning specification (https://semver.org/), the only versions in which features are allowed to be added are major and minor versions (x.y.0)"
#~ msgid "All Python imports in ``lib/ansible/modules/`` and ``lib/ansible/module_utils/`` which are not from the Python standard library must be imported in a try/except ImportError block."
