# Table of Contents - [Users | Ansible documentation | Ansible documentation](#users-ansible-documentation-ansible-documentation) - [Ansible Documentation — Ansible Community Documentation](#ansible-documentation-ansible-community-documentation) - [Ansible Compat Library](#ansible-compat-library) - [Installing - Ansible Pytest Documentation](#installing-ansible-pytest-documentation) - [Community - Ansible Pytest Documentation](#community-ansible-pytest-documentation) - [Galaxy NG](#galaxy-ng) - [Glossary — Ansible Builder Documentation](#glossary-ansible-builder-documentation) - [Installation — Ansible Builder Documentation](#installation-ansible-builder-documentation) - [New Ansible Releases - Ansible Package Release Management](#new-ansible-releases-ansible-package-release-management) - [Ansible AWX Operator Documentation](#ansible-awx-operator-documentation) - [Join the Community - antsibull-docs – Ansible Documentation Build Scripts](#join-the-community-antsibull-docs-ansible-documentation-build-scripts) - [Getting Started - Ansible Pytest Documentation](#getting-started-ansible-pytest-documentation) - [home - Ansible Creator Documentation](#home-ansible-creator-documentation) - [Collection-level dependencies — Ansible Builder Documentation](#collection-level-dependencies-ansible-builder-documentation) - [Home - Tox Ansible Documentation](#home-tox-ansible-documentation) - [Community - antsibull-changelog – Ansible Changelog Tool](#community-antsibull-changelog-ansible-changelog-tool) - [Installation - Tox Ansible Documentation](#installation-tox-ansible-documentation) - [Configuration - Tox Ansible Documentation](#configuration-tox-ansible-documentation) - [FAQ - Tox Ansible Documentation](#faq-tox-ansible-documentation) - [Automated Ansible Release Process - Ansible Package Release Management](#automated-ansible-release-process-ansible-package-release-management) - [Manual Ansible Release Process - Ansible Package Release Management](#manual-ansible-release-process-ansible-package-release-management) - [home - Ansible Pytest Documentation](#home-ansible-pytest-documentation) - [Official Ansible docsite - antsibull-docs – Ansible Documentation Build Scripts](#official-ansible-docsite-antsibull-docs-ansible-documentation-build-scripts) - [antsibull-docs – Ansible Documentation Build Scripts](#antsibull-docs-ansible-documentation-build-scripts) - [antsibull-changelog – Ansible Changelog Tool](#antsibull-changelog-ansible-changelog-tool) - [Maintainers | Ansible documentation | Ansible documentation](#maintainers-ansible-documentation-ansible-documentation) - [Installing Ansible Runner — Ansible Runner Documentation](#installing-ansible-runner-ansible-runner-documentation) - [Community — Ansible Runner Documentation](#community-ansible-runner-documentation) - [Ansible Navigator Documentation](#ansible-navigator-documentation) - [Introduction to Ansible Builder — Ansible Builder Documentation](#introduction-to-ansible-builder-ansible-builder-documentation) - [Community — Ansible Builder Documentation](#community-ansible-builder-documentation) - [Ansible AWX Documentation — Ansible AWX community documentation](#ansible-awx-documentation-ansible-awx-community-documentation) - [ansible-navigator subcommands - Ansible Navigator Documentation](#ansible-navigator-subcommands-ansible-navigator-documentation) - [Contributor Guide - Tox Ansible Documentation](#contributor-guide-tox-ansible-documentation) - [CLI Usage — Ansible Builder Documentation](#cli-usage-ansible-builder-documentation) - [Contributing - Ansible Creator Documentation](#contributing-ansible-creator-documentation) - [Ansible Development Environment Documentation](#ansible-development-environment-documentation) - [Using Runner with Execution Environments — Ansible Runner Documentation](#using-runner-with-execution-environments-ansible-runner-documentation) - [Introduction - antsibull-nox – Antsibull Nox Helper](#introduction-antsibull-nox-antsibull-nox-helper) - [Community - Ansible Navigator Documentation](#community-ansible-navigator-documentation) - [Security Policy - Ansible Navigator Documentation](#security-policy-ansible-navigator-documentation) - [Join the Ansible community | Ansible documentation](#join-the-ansible-community-ansible-documentation) - [Ansible Runner — Ansible Runner Documentation](#ansible-runner-ansible-runner-documentation) - [Using Runner as a standalone command line tool — Ansible Runner Documentation](#using-runner-as-a-standalone-command-line-tool-ansible-runner-documentation) - [Remote job execution — Ansible Runner Documentation](#remote-job-execution-ansible-runner-documentation) - [Ansible community documentation archive | Ansible documentation](#ansible-community-documentation-archive-ansible-documentation) - [Other projects - antsibull-changelog – Ansible Changelog Tool](#other-projects-antsibull-changelog-ansible-changelog-tool) - [User Guide - Tox Ansible Documentation](#user-guide-tox-ansible-documentation) - [home - Ansible Lint Documentation](#home-ansible-lint-documentation) - [Ansible Package Release Management](#ansible-package-release-management) - [Sending Runner Status and Events to External Systems — Ansible Runner Documentation](#sending-runner-status-and-events-to-external-systems-ansible-runner-documentation) - [Ansible Molecule](#ansible-molecule) - [Change detection - antsibull-nox – Antsibull Nox Helper](#change-detection-antsibull-nox-antsibull-nox-helper) - [Troubleshooting - antsibull-nox – Antsibull Nox Helper](#troubleshooting-antsibull-nox-antsibull-nox-helper) - [Community - antsibull-nox – Antsibull Nox Helper](#community-antsibull-nox-antsibull-nox-helper) - [Installation - Ansible Navigator Documentation](#installation-ansible-navigator-documentation) - [Ansible Development Tools Documentation](#ansible-development-tools-documentation) - [Philosophy - Ansible Lint Documentation](#philosophy-ansible-lint-documentation) - [DevSpaces - Ansible Development Tools Documentation](#devspaces-ansible-development-tools-documentation) - [Execution environment definition — Ansible Builder Documentation](#execution-environment-definition-ansible-builder-documentation) - [Changelogs - antsibull-changelog – Ansible Changelog Tool](#changelogs-antsibull-changelog-ansible-changelog-tool) - [Changelog configuration - antsibull-changelog – Ansible Changelog Tool](#changelog-configuration-antsibull-changelog-ansible-changelog-tool) - [Changelog.yaml format - antsibull-changelog – Ansible Changelog Tool](#changelog-yaml-format-antsibull-changelog-ansible-changelog-tool) - [Ansible Collection Policies - Ansible Package Release Management](#ansible-collection-policies-ansible-package-release-management) - [Contributing to Ansible Navigator - Ansible Navigator Documentation](#contributing-to-ansible-navigator-ansible-navigator-documentation) - [Contributing - Ansible Lint Documentation](#contributing-ansible-lint-documentation) - [Execution Environment - Ansible Development Tools Documentation](#execution-environment-ansible-development-tools-documentation) - [Running nox in CI - antsibull-nox – Antsibull Nox Helper](#running-nox-in-ci-antsibull-nox-antsibull-nox-helper) - [Getting started - antsibull-nox – Antsibull Nox Helper](#getting-started-antsibull-nox-antsibull-nox-helper) - [Contributing - Ansible Molecule](#contributing-ansible-molecule) - [Installation and Usage - Ansible Creator Documentation](#installation-and-usage-ansible-creator-documentation) - [Installation - Ansible Molecule](#installation-ansible-molecule) - [Contributor Guide - Ansible Development Tools Documentation](#contributor-guide-ansible-development-tools-documentation) - [Updating playbook output in RST files - antsibull-docs – Ansible Documentation Build Scripts](#updating-playbook-output-in-rst-files-antsibull-docs-ansible-documentation-build-scripts) - [Using Runner as a Python Module Interface to Ansible — Ansible Runner Documentation](#using-runner-as-a-python-module-interface-to-ansible-ansible-runner-documentation) - [Molecule Collection - Ansible Molecule](#molecule-collection-ansible-molecule) - [Creating a collection docsite - antsibull-docs – Ansible Documentation Build Scripts](#creating-a-collection-docsite-antsibull-docs-ansible-documentation-build-scripts) - [antsibull-changelog Release Notes - antsibull-changelog – Ansible Changelog Tool](#antsibull-changelog-release-notes-antsibull-changelog-ansible-changelog-tool) - [antsibull-nox – Antsibull Nox Helper](#antsibull-nox-antsibull-nox-helper) - [FAQ - Ansible Molecule](#faq-ansible-molecule) - [Configuration - Ansible Navigator Documentation](#configuration-ansible-navigator-documentation) - [Introduction to Ansible Runner — Ansible Runner Documentation](#introduction-to-ansible-runner-ansible-runner-documentation) - [User Guide - Ansible Development Tools Documentation](#user-guide-ansible-development-tools-documentation) - [noxfile reference - antsibull-nox – Antsibull Nox Helper](#noxfile-reference-antsibull-nox-antsibull-nox-helper) - [Using docker containers - Ansible Molecule](#using-docker-containers-ansible-molecule) - [Frequently asked questions - Ansible Navigator Documentation](#frequently-asked-questions-ansible-navigator-documentation) - [Release notes - antsibull-nox – Antsibull Nox Helper](#release-notes-antsibull-nox-antsibull-nox-helper) - [Installation - Ansible Development Tools Documentation](#installation-ansible-development-tools-documentation) - [Ansible SDK documentation — Ansible SDK Documentation](#ansible-sdk-documentation-ansible-sdk-documentation) - [ansible-sign — Ansible Sign Documentation](#ansible-sign-ansible-sign-documentation) - [Using - Ansible Lint Documentation](#using-ansible-lint-documentation) - [Developer Documentation — Ansible Runner Documentation](#developer-documentation-ansible-runner-documentation) - [Developers | Ansible documentation | Ansible documentation](#developers-ansible-documentation-ansible-documentation) - [Installing - Ansible Lint Documentation](#installing-ansible-lint-documentation) - [Welcome to Ansible Rulebook documentation — Ansible Rulebook Documentation](#welcome-to-ansible-rulebook-documentation-ansible-rulebook-documentation) - [Ansible ecosystem | Ansible documentation](#ansible-ecosystem-ansible-documentation) - [Custom image - Ansible Molecule](#custom-image-ansible-molecule) - [Python 3 Support — Ansible Core Documentation](#python-3-support-ansible-core-documentation) - [Playbook Testing - Ansible Molecule](#playbook-testing-ansible-molecule) - [Configuring Ansible — Ansible Core Documentation](#configuring-ansible-ansible-core-documentation) - [Installation Guide — Ansible Core Documentation](#installation-guide-ansible-core-documentation) - [Galaxy Developer Guide — Ansible Core Documentation](#galaxy-developer-guide-ansible-core-documentation) - [Special Variables — Ansible Core Documentation](#special-variables-ansible-core-documentation) - [Return Values — Ansible Core Documentation](#return-values-ansible-core-documentation) - [Interpreter Discovery — Ansible Core Documentation](#interpreter-discovery-ansible-core-documentation) - [Red Hat Ansible Automation Platform — Ansible Core Documentation](#red-hat-ansible-automation-platform-ansible-core-documentation) - [Ansible Automation Hub — Ansible Core Documentation](#ansible-automation-hub-ansible-core-documentation) - [Logging Ansible output — Ansible Core Documentation](#logging-ansible-output-ansible-core-documentation) - [Building Ansible inventories — Ansible Core Documentation](#building-ansible-inventories-ansible-core-documentation) - [ansible-core Contributors Guide — Ansible Core Documentation](#ansible-core-contributors-guide-ansible-core-documentation) - [Creating a playbook — Ansible Core Documentation](#creating-a-playbook-ansible-core-documentation) - [Ansible concepts — Ansible Core Documentation](#ansible-concepts-ansible-core-documentation) - [Getting started with Ansible — Ansible Core Documentation](#getting-started-with-ansible-ansible-core-documentation) - [Controlling how Ansible behaves: precedence rules — Ansible Core Documentation](#controlling-how-ansible-behaves-precedence-rules-ansible-core-documentation) - [YAML Syntax — Ansible Core Documentation](#yaml-syntax-ansible-core-documentation) - [antsibull-docs Release Notes - antsibull-docs – Ansible Documentation Build Scripts](#antsibull-docs-release-notes-antsibull-docs-ansible-documentation-build-scripts) - [Working with dynamic inventory — Ansible Core Documentation](#working-with-dynamic-inventory-ansible-core-documentation) - [Testing philosophy - Ansible Molecule](#testing-philosophy-ansible-molecule) - [Collection Index — Ansible Core Documentation](#collection-index-ansible-core-documentation) - [Network Getting Started — Ansible Community Documentation](#network-getting-started-ansible-community-documentation) - [Network Advanced Topics — Ansible Community Documentation](#network-advanced-topics-ansible-community-documentation) - [Python 3 Support — Ansible Community Documentation](#python-3-support-ansible-community-documentation) - [Ansible Automation Hub — Ansible Community Documentation](#ansible-automation-hub-ansible-community-documentation) - [Connection methods and details — Ansible Core Documentation](#connection-methods-and-details-ansible-core-documentation) - [Installing Ansible on specific operating systems — Ansible Core Documentation](#installing-ansible-on-specific-operating-systems-ansible-core-documentation) - [Testing Strategies — Ansible Core Documentation](#testing-strategies-ansible-core-documentation) - [Building an inventory — Ansible Core Documentation](#building-an-inventory-ansible-core-documentation) - [Playbook Keywords — Ansible Core Documentation](#playbook-keywords-ansible-core-documentation) - [Galaxy User Guide — Ansible Core Documentation](#galaxy-user-guide-ansible-core-documentation) - [Legacy Public Cloud Guides — Ansible Community Documentation](#legacy-public-cloud-guides-ansible-community-documentation) - [Network Developer Guide — Ansible Community Documentation](#network-developer-guide-ansible-community-documentation) - [Interpreter Discovery — Ansible Community Documentation](#interpreter-discovery-ansible-community-documentation) - [Red Hat Ansible Automation Platform — Ansible Community Documentation](#red-hat-ansible-automation-platform-ansible-community-documentation) - [Logging Ansible output — Ansible Community Documentation](#logging-ansible-output-ansible-community-documentation) - [Patterns: targeting hosts and groups — Ansible Core Documentation](#patterns-targeting-hosts-and-groups-ansible-core-documentation) - [Introduction to ad hoc commands — Ansible Core Documentation](#introduction-to-ad-hoc-commands-ansible-core-documentation) - [Ansible documentation style guide — Ansible Core Documentation](#ansible-documentation-style-guide-ansible-core-documentation) - [Configuring Ansible — Ansible Community Documentation](#configuring-ansible-ansible-community-documentation) - [Galaxy Developer Guide — Ansible Community Documentation](#galaxy-developer-guide-ansible-community-documentation) - [Special Variables — Ansible Community Documentation](#special-variables-ansible-community-documentation) - [Return Values — Ansible Community Documentation](#return-values-ansible-community-documentation) - [Installing Ansible — Ansible Core Documentation](#installing-ansible-ansible-core-documentation) - [Releases and maintenance — Ansible Core Documentation](#releases-and-maintenance-ansible-core-documentation) - [Advanced Contributor Guide — Ansible Core Documentation](#advanced-contributor-guide-ansible-core-documentation) - [Introduction to Ansible — Ansible Core Documentation](#introduction-to-ansible-ansible-core-documentation) - [Start automating with Ansible — Ansible Core Documentation](#start-automating-with-ansible-ansible-core-documentation) - [ansible-core Contributors Guide — Ansible Community Documentation](#ansible-core-contributors-guide-ansible-community-documentation) - [Ansible tips and tricks — Ansible Community Documentation](#ansible-tips-and-tricks-ansible-community-documentation) - [Ansible-core 2.18 Porting Guide — Ansible Core Documentation](#ansible-core-2-18-porting-guide-ansible-core-documentation) - [Ansible-core 2.17 Porting Guide — Ansible Core Documentation](#ansible-core-2-17-porting-guide-ansible-core-documentation) - [Ansible-core 2.16 Porting Guide — Ansible Core Documentation](#ansible-core-2-16-porting-guide-ansible-core-documentation) - [Ansible-core 2.13 Porting Guide — Ansible Core Documentation](#ansible-core-2-13-porting-guide-ansible-core-documentation) - [Building Ansible inventories — Ansible Community Documentation](#building-ansible-inventories-ansible-community-documentation) - [Creating a playbook — Ansible Community Documentation](#creating-a-playbook-ansible-community-documentation) - [Ansible concepts — Ansible Community Documentation](#ansible-concepts-ansible-community-documentation) - [Introduction to Execution Environments — Ansible Community Documentation](#introduction-to-execution-environments-ansible-community-documentation) - [Running Ansible with the community EE image — Ansible Community Documentation](#running-ansible-with-the-community-ee-image-ansible-community-documentation) - [Setting up your environment — Ansible Community Documentation](#setting-up-your-environment-ansible-community-documentation) - [Protecting sensitive data with Ansible vault — Ansible Core Documentation](#protecting-sensitive-data-with-ansible-vault-ansible-core-documentation) - [Ansible Community Guide — Ansible Core Documentation](#ansible-community-guide-ansible-core-documentation) - [Ansible Core Porting Guides — Ansible Core Documentation](#ansible-core-porting-guides-ansible-core-documentation) - [Using Ansible command line tools — Ansible Core Documentation](#using-ansible-command-line-tools-ansible-core-documentation) - [Advanced Contributor Guide — Ansible Community Documentation](#advanced-contributor-guide-ansible-community-documentation) - [Installing Ansible on specific operating systems — Ansible Community Documentation](#installing-ansible-on-specific-operating-systems-ansible-community-documentation) - [YAML Syntax — Ansible Community Documentation](#yaml-syntax-ansible-community-documentation) - [Controlling how Ansible behaves: precedence rules — Ansible Community Documentation](#controlling-how-ansible-behaves-precedence-rules-ansible-community-documentation) - [Glossary — Ansible Core Documentation](#glossary-ansible-core-documentation) - [Introduction to Ansible — Ansible Community Documentation](#introduction-to-ansible-ansible-community-documentation) - [Start automating with Ansible — Ansible Community Documentation](#start-automating-with-ansible-ansible-community-documentation) - [Ansible-core 2.15 Porting Guide — Ansible Core Documentation](#ansible-core-2-15-porting-guide-ansible-core-documentation) - [Ansible-core 2.14 Porting Guide — Ansible Core Documentation](#ansible-core-2-14-porting-guide-ansible-core-documentation) - [Ansible-core 2.12 Porting Guide — Ansible Core Documentation](#ansible-core-2-12-porting-guide-ansible-core-documentation) - [Ansible-base 2.10 Porting Guide — Ansible Core Documentation](#ansible-base-2-10-porting-guide-ansible-core-documentation) - [Testing Strategies — Ansible Community Documentation](#testing-strategies-ansible-community-documentation) - [Ansible Reference: Module Utilities — Ansible Core Documentation](#ansible-reference-module-utilities-ansible-core-documentation) - [Ansible Community Guide — Ansible Community Documentation](#ansible-community-guide-ansible-community-documentation) - [Building an inventory — Ansible Community Documentation](#building-an-inventory-ansible-community-documentation) - [Running your EE — Ansible Community Documentation](#running-your-ee-ansible-community-documentation) - [Building your first Execution Environment — Ansible Community Documentation](#building-your-first-execution-environment-ansible-community-documentation) - [Playbook Keywords — Ansible Community Documentation](#playbook-keywords-ansible-community-documentation) - [Ansible documentation style guide — Ansible Community Documentation](#ansible-documentation-style-guide-ansible-community-documentation) - [Releases and maintenance — Ansible Community Documentation](#releases-and-maintenance-ansible-community-documentation) - [Installation Guide — Ansible Community Documentation](#installation-guide-ansible-community-documentation) - [Galaxy User Guide — Ansible Community Documentation](#galaxy-user-guide-ansible-community-documentation) - [Installing Ansible — Ansible Community Documentation](#installing-ansible-ansible-community-documentation) - [How to build your inventory — Ansible Core Documentation](#how-to-build-your-inventory-ansible-core-documentation) - [Ansible Collections Contributor Guide — Ansible Community Documentation](#ansible-collections-contributor-guide-ansible-community-documentation) - [Introduction to modules — Ansible Community Documentation](#introduction-to-modules-ansible-community-documentation) - [Ansible architecture — Ansible Community Documentation](#ansible-architecture-ansible-community-documentation) - [Adding modules and plugins locally — Ansible Community Documentation](#adding-modules-and-plugins-locally-ansible-community-documentation) - [Config file reference - antsibull-nox – Antsibull Nox Helper](#config-file-reference-antsibull-nox-antsibull-nox-helper) - [Glossary — Ansible Community Documentation](#glossary-ansible-community-documentation) - [ansible-core Roadmaps — Ansible Community Documentation](#ansible-core-roadmaps-ansible-community-documentation) - [Ansible tips and tricks — Ansible Core Documentation](#ansible-tips-and-tricks-ansible-core-documentation) - [Getting started with Ansible — Ansible Community Documentation](#getting-started-with-ansible-ansible-community-documentation) - [Getting started with Execution Environments — Ansible Community Documentation](#getting-started-with-execution-environments-ansible-community-documentation) - [Ansible Roadmap — Ansible Community Documentation](#ansible-roadmap-ansible-community-documentation) - [Contributor path — Ansible Community Documentation](#contributor-path-ansible-community-documentation) - [Ansible Reference: Module Utilities — Ansible Community Documentation](#ansible-reference-module-utilities-ansible-community-documentation) - [Community Code of Conduct — Ansible Community Documentation](#community-code-of-conduct-ansible-community-documentation) - [Working with dynamic inventory — Ansible Community Documentation](#working-with-dynamic-inventory-ansible-community-documentation) - [Frequently Asked Questions — Ansible Core Documentation](#frequently-asked-questions-ansible-core-documentation) - [Protecting sensitive data with Ansible vault — Ansible Community Documentation](#protecting-sensitive-data-with-ansible-vault-ansible-community-documentation) - [Using Ansible command line tools — Ansible Community Documentation](#using-ansible-command-line-tools-ansible-community-documentation) - [Maintainer responsibilities — Ansible Community Documentation](#maintainer-responsibilities-ansible-community-documentation) - [Using Ansible collections — Ansible Community Documentation](#using-ansible-collections-ansible-community-documentation) - [Ansible-core 2.19 Porting Guide — Ansible Core Documentation](#ansible-core-2-19-porting-guide-ansible-core-documentation) - [ansible-core Roadmaps — Ansible Core Documentation](#ansible-core-roadmaps-ansible-core-documentation) - [Using Ansible collections — Ansible Core Documentation](#using-ansible-collections-ansible-core-documentation) - [Indexes of all modules and plugins — Ansible Core Documentation](#indexes-of-all-modules-and-plugins-ansible-core-documentation) - [Frequently Asked Questions — Ansible Community Documentation](#frequently-asked-questions-ansible-community-documentation) - [Using Ansible on Windows, BSD, and z/OS UNIX — Ansible Core Documentation](#using-ansible-on-windows-bsd-and-z-os-unix-ansible-core-documentation) - [Ansible-core 2.11 Porting Guide — Ansible Core Documentation](#ansible-core-2-11-porting-guide-ansible-core-documentation) - [Using Ansible on Windows, BSD, and z/OS UNIX — Ansible Community Documentation](#using-ansible-on-windows-bsd-and-z-os-unix-ansible-community-documentation) - [Using Ansible playbooks — Ansible Core Documentation](#using-ansible-playbooks-ansible-core-documentation) - [How to build your inventory — Ansible Community Documentation](#how-to-build-your-inventory-ansible-community-documentation) - [index - Ansible Lint Documentation](#index-ansible-lint-documentation) - [Working with command line tools — Ansible Core Documentation](#working-with-command-line-tools-ansible-core-documentation) - [Using Ansible playbooks — Ansible Community Documentation](#using-ansible-playbooks-ansible-community-documentation) - [Developer Guide — Ansible Core Documentation](#developer-guide-ansible-core-documentation) - [Indexes of all modules and plugins — Ansible Community Documentation](#indexes-of-all-modules-and-plugins-ansible-community-documentation) - [Using Ansible modules and plugins — Ansible Community Documentation](#using-ansible-modules-and-plugins-ansible-community-documentation) - [Using Ansible modules and plugins — Ansible Core Documentation](#using-ansible-modules-and-plugins-ansible-core-documentation) - [How to Develop a Custom Plugin — Ansible Rulebook Documentation](#how-to-develop-a-custom-plugin-ansible-rulebook-documentation) - [Developer Guide — Ansible Community Documentation](#developer-guide-ansible-community-documentation) - [Ansible Porting Guides — Ansible Community Documentation](#ansible-porting-guides-ansible-community-documentation) - [Conditionals — Ansible Community Documentation](#conditionals-ansible-community-documentation) - [Ansible 13 Porting Guide — Ansible Community Documentation](#ansible-13-porting-guide-ansible-community-documentation) - [Ansible 3 Porting Guide — Ansible Community Documentation](#ansible-3-porting-guide-ansible-community-documentation) - [Ansible 4 Porting Guide — Ansible Community Documentation](#ansible-4-porting-guide-ansible-community-documentation) - [Ansible 10 Porting Guide — Ansible Community Documentation](#ansible-10-porting-guide-ansible-community-documentation) - [Using variables — Ansible Community Documentation](#using-variables-ansible-community-documentation) - [Ansible 6 Porting Guide — Ansible Community Documentation](#ansible-6-porting-guide-ansible-community-documentation) - [Roles — Ansible Community Documentation](#roles-ansible-community-documentation) - [Collection Index — Ansible Community Documentation](#collection-index-ansible-community-documentation) --- # Users | Ansible documentation | Ansible documentation Join us at [Red Hat Summit in Atlanta](https://www.redhat.com/en/summit?sc_id=RHCTE0250000464461) to learn about Ansible Automation Platform | May 11-14, 2026 Users ----- Automate the management of remote systems and control their desired state. Top links for Ansible users --------------------------- [YAML syntax](https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html) [Playbook variables](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_variables.html) [Playbook conditionals](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_conditionals.html) * * * ### Create automation [Start writing Ansible playbooks](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_intro.html#playbook-syntax) [Learn about Ansible modules](https://docs.ansible.com/ansible/latest/module_plugin_guide/modules_intro.html) ### Build inventories [Build inventory files to manage multiple hosts](https://docs.ansible.com/ansible/latest/inventory_guide/intro_inventory.html) [Use dynamic inventories](https://docs.ansible.com/ansible/latest/inventory_guide/intro_dynamic_inventory.html) ### Organize automation projects [Use roles to structure the automation project](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_reuse_roles.html) ### Use Ansible execution environments [Get started with execution environments](https://docs.ansible.com/ansible/devel/getting_started_ee/index.html) [Build execution environments](https://docs.ansible.com/projects/builder/en/latest/) ### Use Ansible tooling [Create and test playbooks with Ansible Navigator](https://docs.ansible.com/projects/navigator/) [Use Ansible Lint to validate playbooks](https://docs.ansible.com/projects/lint/) [Install Molecule to develop and test Ansible roles](https://docs.ansible.com/projects/molecule/) [Use Ansible with OpenVSX compatible editors](https://marketplace.visualstudio.com/items?itemName=redhat.ansible) ### Find automation content [Start exploring Ansible Galaxy](https://docs.ansible.com/ansible/latest/galaxy/user_guide.html#finding-collections-on-galaxy) [Install and use roles](https://docs.ansible.com/ansible/latest/galaxy/user_guide.html#installing-roles-from-galaxy) [Install and use collections](https://docs.ansible.com/ansible/latest/galaxy/user_guide.html#installing-collections) ### Share automation content [Submit roles to an existing collection](https://docs.ansible.com/projects/galaxy-ng/en/latest/community/userguide/#importing-roles) [Create a new collection](https://docs.ansible.com/ansible/latest/dev_guide/developing_collections.html#developing-collections) [Upload a collection to Ansible Galaxy](https://docs.ansible.com/projects/galaxy-ng/en/latest/community/userguide/#uploading-collections) ### Schedule and run automation jobs [Execute automation jobs on demand](https://github.com/ansible/awx/blob/devel/docs/tasks.md#awx-jobs) [Schedule automation jobs](https://github.com/ansible/awx/blob/devel/docs/schedules.md#scheduled-jobs) [Use execution environments with AWX jobs](https://docs.ansible.com/projects/runner/en/latest/execution_environments/) * [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) * [Privacy policy](https://www.redhat.com/en/about/privacy-policy) * [Code of conduct](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html) Sponsored by [![Red Hat logo.](https://docs.ansible.com/assets/images/redhat_reversed.svg)](https://www.redhat.com/en/technologies/management/ansible?sc_id=RHCTE0250000464439) --- # Ansible Documentation — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html#) * Ansible Documentation * * * * Ansible Documentation[](https://docs.ansible.com/projects/ansible/latest/index.html#id1 "Link to this heading") ================================================================================================================= Welcome to Ansible community documentation! This documentation covers the version of Ansible noted in the upper left corner of this page. We maintain multiple versions of Ansible and of the documentation, so please be sure you are using the version of the documentation that covers the version of Ansible you’re using. For recent features, we note the version of Ansible where the feature was added. Ansible releases a new major release approximately twice a year. The core application evolves somewhat conservatively, valuing simplicity in language design and setup. Contributors develop and change modules and plugins, hosted in collections, much more quickly. Ansible getting started * [Getting started with Ansible](https://docs.ansible.com/projects/ansible/latest/getting_started/index.html) * [Introduction to Ansible](https://docs.ansible.com/projects/ansible/latest/getting_started/introduction.html) * [Start automating with Ansible](https://docs.ansible.com/projects/ansible/latest/getting_started/get_started_ansible.html) * [Building an inventory](https://docs.ansible.com/projects/ansible/latest/getting_started/get_started_inventory.html) * [Creating a playbook](https://docs.ansible.com/projects/ansible/latest/getting_started/get_started_playbook.html) * [Ansible concepts](https://docs.ansible.com/projects/ansible/latest/getting_started/basic_concepts.html) * [Getting started with Execution Environments](https://docs.ansible.com/projects/ansible/latest/getting_started_ee/index.html) * [Introduction to Execution Environments](https://docs.ansible.com/projects/ansible/latest/getting_started_ee/introduction.html) * [Setting up your environment](https://docs.ansible.com/projects/ansible/latest/getting_started_ee/setup_environment.html) * [Building your first Execution Environment](https://docs.ansible.com/projects/ansible/latest/getting_started_ee/build_execution_environment.html) * [Running your EE](https://docs.ansible.com/projects/ansible/latest/getting_started_ee/run_execution_environment.html) * [Running Ansible with the community EE image](https://docs.ansible.com/projects/ansible/latest/getting_started_ee/run_community_ee_image.html) Installation, Upgrade & Configuration * [Installation Guide](https://docs.ansible.com/projects/ansible/latest/installation_guide/index.html) * [Installing Ansible](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html) * [Installing Ansible on specific operating systems](https://docs.ansible.com/projects/ansible/latest/installation_guide/installation_distros.html) * [Configuring Ansible](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_configuration.html) * [Ansible Porting Guides](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guides.html) * [Ansible 13 Porting Guide](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html) * [Ansible 12 Porting Guide](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_12.html) * [Ansible 11 Porting Guide](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_11.html) * [Ansible 10 Porting Guide](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html) * [Ansible 9 Porting Guide](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_9.html) * [Ansible 8 Porting Guide](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_8.html) * [Ansible 7 Porting Guide](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_7.html) * [Ansible 6 Porting Guide](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html) * [Ansible 5 Porting Guide](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_5.html) * [Ansible 4 Porting Guide](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html) * [Ansible 3 Porting Guide](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html) * [Ansible 2.10 Porting Guide](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_2.10.html) * [Ansible 2.9 Porting Guide](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_2.9.html) * [Ansible 2.8 Porting Guide](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_2.8.html) * [Ansible 2.7 Porting Guide](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_2.7.html) * [Ansible 2.6 Porting Guide](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_2.6.html) * [Ansible 2.5 Porting Guide](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_2.5.html) * [Ansible 2.4 Porting Guide](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_2.4.html) * [Ansible 2.3 Porting Guide](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_2.3.html) * [Ansible 2.0 Porting Guide](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_2.0.html) Using Ansible * [Building Ansible inventories](https://docs.ansible.com/projects/ansible/latest/inventory_guide/index.html) * [How to build your inventory](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html) * [Working with dynamic inventory](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_dynamic_inventory.html) * [Patterns: targeting hosts and groups](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_patterns.html) * [Connection methods and details](https://docs.ansible.com/projects/ansible/latest/inventory_guide/connection_details.html) * [Using Ansible command line tools](https://docs.ansible.com/projects/ansible/latest/command_guide/index.html) * [Introduction to ad hoc commands](https://docs.ansible.com/projects/ansible/latest/command_guide/intro_adhoc.html) * [Working with command line tools](https://docs.ansible.com/projects/ansible/latest/command_guide/command_line_tools.html) * [Ansible CLI cheatsheet](https://docs.ansible.com/projects/ansible/latest/command_guide/cheatsheet.html) * [Using Ansible playbooks](https://docs.ansible.com/projects/ansible/latest/playbook_guide/index.html) * [Ansible playbooks](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_intro.html) * [Working with playbooks](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks.html) * [Executing playbooks](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_execution.html) * [Advanced playbook syntax](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_advanced_syntax.html) * [Manipulating data](https://docs.ansible.com/projects/ansible/latest/playbook_guide/complex_data_manipulation.html) * [Protecting sensitive data with Ansible vault](https://docs.ansible.com/projects/ansible/latest/vault_guide/index.html) * [Ansible Vault](https://docs.ansible.com/projects/ansible/latest/vault_guide/vault.html) * [Managing vault passwords](https://docs.ansible.com/projects/ansible/latest/vault_guide/vault_managing_passwords.html) * [Encrypting content with Ansible Vault](https://docs.ansible.com/projects/ansible/latest/vault_guide/vault_encrypting_content.html) * [Using encrypted variables and files](https://docs.ansible.com/projects/ansible/latest/vault_guide/vault_using_encrypted_content.html) * [Configuring defaults for using encrypted content](https://docs.ansible.com/projects/ansible/latest/vault_guide/vault_using_encrypted_content.html#configuring-defaults-for-using-encrypted-content) * [When are encrypted files made visible?](https://docs.ansible.com/projects/ansible/latest/vault_guide/vault_using_encrypted_content.html#when-are-encrypted-files-made-visible) * [Format of files encrypted with Ansible Vault](https://docs.ansible.com/projects/ansible/latest/vault_guide/vault_using_encrypted_content.html#format-of-files-encrypted-with-ansible-vault) * [Using Ansible modules and plugins](https://docs.ansible.com/projects/ansible/latest/module_plugin_guide/index.html) * [Introduction to modules](https://docs.ansible.com/projects/ansible/latest/module_plugin_guide/modules_intro.html) * [Boolean variables](https://docs.ansible.com/projects/ansible/latest/module_plugin_guide/modules_intro.html#boolean-variables) * [Module maintenance and support](https://docs.ansible.com/projects/ansible/latest/module_plugin_guide/modules_support.html) * [Rejecting modules](https://docs.ansible.com/projects/ansible/latest/module_plugin_guide/plugin_filtering_config.html) * [Working with plugins](https://docs.ansible.com/projects/ansible/latest/plugins/plugins.html) * [Modules and plugins index](https://docs.ansible.com/projects/ansible/latest/module_plugin_guide/modules_plugins_index.html) * [Using Ansible collections](https://docs.ansible.com/projects/ansible/latest/collections_guide/index.html) * [Installing collections](https://docs.ansible.com/projects/ansible/latest/collections_guide/collections_installing.html) * [Removing a collection](https://docs.ansible.com/projects/ansible/latest/collections_guide/collections_installing.html#removing-a-collection) * [Downloading collections](https://docs.ansible.com/projects/ansible/latest/collections_guide/collections_downloading.html) * [Listing collections](https://docs.ansible.com/projects/ansible/latest/collections_guide/collections_listing.html) * [Verifying collections](https://docs.ansible.com/projects/ansible/latest/collections_guide/collections_verifying.html) * [Using collections in a playbook](https://docs.ansible.com/projects/ansible/latest/collections_guide/collections_using_playbooks.html) * [Collections index](https://docs.ansible.com/projects/ansible/latest/collections_guide/collections_index.html) * [Using Ansible on Windows, BSD, and z/OS UNIX](https://docs.ansible.com/projects/ansible/latest/os_guide/index.html) * [Managing BSD hosts with Ansible](https://docs.ansible.com/projects/ansible/latest/os_guide/intro_bsd.html) * [Managing Windows hosts with Ansible](https://docs.ansible.com/projects/ansible/latest/os_guide/intro_windows.html) * [Managing z/OS UNIX hosts with Ansible](https://docs.ansible.com/projects/ansible/latest/os_guide/intro_zos.html) * [Ansible tips and tricks](https://docs.ansible.com/projects/ansible/latest/tips_tricks/index.html) * [General tips](https://docs.ansible.com/projects/ansible/latest/tips_tricks/ansible_tips_tricks.html) * [Playbook tips](https://docs.ansible.com/projects/ansible/latest/tips_tricks/ansible_tips_tricks.html#playbook-tips) * [Inventory tips](https://docs.ansible.com/projects/ansible/latest/tips_tricks/ansible_tips_tricks.html#inventory-tips) * [Execution tricks](https://docs.ansible.com/projects/ansible/latest/tips_tricks/ansible_tips_tricks.html#execution-tricks) * [Sample Ansible setup](https://docs.ansible.com/projects/ansible/latest/tips_tricks/sample_setup.html) Contributing to Ansible * [Ansible Community Guide](https://docs.ansible.com/projects/ansible/latest/community/index.html) * [Getting started](https://docs.ansible.com/projects/ansible/latest/community/getting_started.html) * [Contributor path](https://docs.ansible.com/projects/ansible/latest/community/contributor_path.html) * [Ansible Collections Contributor Guide](https://docs.ansible.com/projects/ansible/latest/community/contributions_collections.html) * [The Ansible Collections Development Cycle](https://docs.ansible.com/projects/ansible/latest/community/collection_development_process.html) * [Requesting changes to a collection](https://docs.ansible.com/projects/ansible/latest/community/reporting_collections.html) * [Creating your first collection pull request](https://docs.ansible.com/projects/ansible/latest/community/create_pr_quick_start.html) * [Testing Collection Contributions](https://docs.ansible.com/projects/ansible/latest/community/collection_contributors/test_index.html) * [Review checklist for collection PRs](https://docs.ansible.com/projects/ansible/latest/community/collection_contributors/collection_reviewing.html) * [Ansible community package collections requirements](https://docs.ansible.com/projects/ansible/latest/community/collection_contributors/collection_requirements.html) * [Guidelines for collection maintainers](https://docs.ansible.com/projects/ansible/latest/community/maintainers.html) * [Contributing to Ansible-maintained Collections](https://docs.ansible.com/projects/ansible/latest/community/contributing_maintained_collections.html) * [Ansible Community Steering Committee](https://docs.ansible.com/projects/ansible/latest/community/steering/steering_index.html) * [Contributing to the Ansible Documentation](https://docs.ansible.com/projects/ansible/latest/community/documentation_contributions.html) * [Other Tools and Programs](https://docs.ansible.com/projects/ansible/latest/community/other_tools_and_programs.html) * [Working with the Ansible collection repositories](https://docs.ansible.com/projects/ansible/latest/community/contributions_collections.html#working-with-the-ansible-collection-repositories) * [ansible-core Contributors Guide](https://docs.ansible.com/projects/ansible/latest/community/contributions.html) * [Reporting bugs and requesting features](https://docs.ansible.com/projects/ansible/latest/community/reporting_bugs_and_features.html) * [Contributing to the Ansible Documentation](https://docs.ansible.com/projects/ansible/latest/community/documentation_contributions.html) * [The Ansible Development Cycle](https://docs.ansible.com/projects/ansible/latest/community/development_process.html) * [Other Tools and Programs](https://docs.ansible.com/projects/ansible/latest/community/other_tools_and_programs.html) * [Working with the Ansible repo](https://docs.ansible.com/projects/ansible/latest/community/contributions.html#working-with-the-ansible-repo) * [Advanced Contributor Guide](https://docs.ansible.com/projects/ansible/latest/community/advanced_index.html) * [Committers Guidelines](https://docs.ansible.com/projects/ansible/latest/community/committer_guidelines.html) * [GitHub Admins](https://docs.ansible.com/projects/ansible/latest/community/github_admins.html) * [Ansible Ecosystem Project Development Resources](https://docs.ansible.com/projects/ansible/latest/community/ecosystem_project_resources.html) * [Ansible documentation style guide](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html) * [Linguistic guidelines](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#linguistic-guidelines) * [reStructuredText guidelines](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#restructuredtext-guidelines) * [Markdown guidelines](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#markdown-guidelines) * [Accessibility guidelines](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#accessibility-guidelines) * [More resources](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#more-resources) Extending Ansible * [Developer Guide](https://docs.ansible.com/projects/ansible/latest/dev_guide/index.html) * [Adding modules and plugins locally](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_locally.html) * [Should you develop a module?](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules.html) * [Developing modules](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_general.html) * [Contributing your module to an existing Ansible collection](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_checklist.html) * [Conventions, tips, and pitfalls](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_best_practices.html) * [Ansible and Python 3](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_python_3.html) * [Debugging modules](https://docs.ansible.com/projects/ansible/latest/dev_guide/debugging.html) * [Module format and documentation](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_documenting.html) * [Ansible markup](https://docs.ansible.com/projects/ansible/latest/dev_guide/ansible_markup.html) * [Adjacent YAML documentation files](https://docs.ansible.com/projects/ansible/latest/dev_guide/sidecar.html) * [Windows module development walkthrough](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_general_windows.html) * [Creating a new collection](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_in_groups.html) * [Testing Ansible](https://docs.ansible.com/projects/ansible/latest/dev_guide/testing.html) * [The lifecycle of an Ansible module or plugin](https://docs.ansible.com/projects/ansible/latest/dev_guide/module_lifecycle.html) * [Developing plugins](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_plugins.html) * [Developing dynamic inventory](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_inventory.html) * [Developing `ansible-core`](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_core.html) * [Ansible module architecture](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_program_flow_modules.html) * [Python API](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_api.html) * [Rebasing a pull request](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_rebasing.html) * [Using and developing module utilities](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_module_utilities.html) * [Ansible collection creator path](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_collections_path.html) * [Developing collections](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_collections.html) * [Migrating Roles to Roles in Collections on Galaxy](https://docs.ansible.com/projects/ansible/latest/dev_guide/migrating_roles.html) * [Collection Galaxy metadata structure](https://docs.ansible.com/projects/ansible/latest/dev_guide/collections_galaxy_meta.html) * [Ansible architecture](https://docs.ansible.com/projects/ansible/latest/dev_guide/overview_architecture.html) Common Ansible Scenarios * [Legacy Public Cloud Guides](https://docs.ansible.com/projects/ansible/latest/scenario_guides/cloud_guides.html) Network Automation * [Network Getting Started](https://docs.ansible.com/projects/ansible/latest/network/getting_started/index.html) * [Basic Concepts](https://docs.ansible.com/projects/ansible/latest/network/getting_started/basic_concepts.html) * [How Network Automation is Different](https://docs.ansible.com/projects/ansible/latest/network/getting_started/network_differences.html) * [Run Your First Command and Playbook](https://docs.ansible.com/projects/ansible/latest/network/getting_started/first_playbook.html) * [Build Your Inventory](https://docs.ansible.com/projects/ansible/latest/network/getting_started/first_inventory.html) * [Use Ansible network roles](https://docs.ansible.com/projects/ansible/latest/network/getting_started/network_roles.html) * [Beyond the basics](https://docs.ansible.com/projects/ansible/latest/network/getting_started/intermediate_concepts.html) * [Working with network connection options](https://docs.ansible.com/projects/ansible/latest/network/getting_started/network_connection_options.html) * [Resources and next steps](https://docs.ansible.com/projects/ansible/latest/network/getting_started/network_resources.html) * [Network Advanced Topics](https://docs.ansible.com/projects/ansible/latest/network/user_guide/index.html) * [Network Resource Modules](https://docs.ansible.com/projects/ansible/latest/network/user_guide/network_resource_modules.html) * [Ansible Network Examples](https://docs.ansible.com/projects/ansible/latest/network/user_guide/network_best_practices_2.5.html) * [Parsing semi-structured text with Ansible](https://docs.ansible.com/projects/ansible/latest/network/user_guide/cli_parsing.html) * [Validate data against set criteria with Ansible](https://docs.ansible.com/projects/ansible/latest/network/user_guide/validate.html) * [Network Debug and Troubleshooting Guide](https://docs.ansible.com/projects/ansible/latest/network/user_guide/network_debug_troubleshooting.html) * [Working with command output and prompts in network modules](https://docs.ansible.com/projects/ansible/latest/network/user_guide/network_working_with_command_output.html) * [Ansible Network FAQ](https://docs.ansible.com/projects/ansible/latest/network/user_guide/faq.html) * [Platform Options](https://docs.ansible.com/projects/ansible/latest/network/user_guide/platform_index.html) * [Network Developer Guide](https://docs.ansible.com/projects/ansible/latest/network/dev_guide/index.html) * [Developing network resource modules](https://docs.ansible.com/projects/ansible/latest/network/dev_guide/developing_resource_modules_network.html) * [Developing network plugins](https://docs.ansible.com/projects/ansible/latest/network/dev_guide/developing_plugins_network.html) * [Documenting new network platforms](https://docs.ansible.com/projects/ansible/latest/network/dev_guide/documenting_modules_network.html) Ansible Galaxy * [Galaxy User Guide](https://docs.ansible.com/projects/ansible/latest/galaxy/user_guide.html) * [Finding collections on Galaxy](https://docs.ansible.com/projects/ansible/latest/galaxy/user_guide.html#finding-collections-on-galaxy) * [Finding roles on Galaxy](https://docs.ansible.com/projects/ansible/latest/galaxy/user_guide.html#finding-roles-on-galaxy) * [Installing roles from Galaxy](https://docs.ansible.com/projects/ansible/latest/galaxy/user_guide.html#installing-roles-from-galaxy) * [Galaxy Developer Guide](https://docs.ansible.com/projects/ansible/latest/galaxy/dev_guide.html) * [Creating collections for Galaxy](https://docs.ansible.com/projects/ansible/latest/galaxy/dev_guide.html#creating-collections-for-galaxy) * [Creating roles for Galaxy](https://docs.ansible.com/projects/ansible/latest/galaxy/dev_guide.html#creating-roles-for-galaxy) Reference & Appendices * [Collection Index](https://docs.ansible.com/projects/ansible/latest/collections/index.html) * [Indexes of all modules and plugins](https://docs.ansible.com/projects/ansible/latest/collections/all_plugins.html) * [Playbook Keywords](https://docs.ansible.com/projects/ansible/latest/reference_appendices/playbooks_keywords.html) * [Return Values](https://docs.ansible.com/projects/ansible/latest/reference_appendices/common_return_values.html) * [Ansible Configuration Settings](https://docs.ansible.com/projects/ansible/latest/reference_appendices/config.html) * [Controlling how Ansible behaves: precedence rules](https://docs.ansible.com/projects/ansible/latest/reference_appendices/general_precedence.html) * [YAML Syntax](https://docs.ansible.com/projects/ansible/latest/reference_appendices/YAMLSyntax.html) * [Python 3 Support](https://docs.ansible.com/projects/ansible/latest/reference_appendices/python_3_support.html) * [Interpreter Discovery](https://docs.ansible.com/projects/ansible/latest/reference_appendices/interpreter_discovery.html) * [Releases and maintenance](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html) * [Testing Strategies](https://docs.ansible.com/projects/ansible/latest/reference_appendices/test_strategies.html) * [Sanity Tests](https://docs.ansible.com/projects/ansible/latest/dev_guide/testing/sanity/index.html) * [Frequently Asked Questions](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html) * [Glossary](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html) * [Ansible Reference: Module Utilities](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html) * [Special Variables](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html) * [Red Hat Ansible Automation Platform](https://docs.ansible.com/projects/ansible/latest/reference_appendices/tower.html) * [Ansible Automation Hub](https://docs.ansible.com/projects/ansible/latest/reference_appendices/automationhub.html) * [Logging Ansible output](https://docs.ansible.com/projects/ansible/latest/reference_appendices/logging.html) Roadmaps * [Ansible Roadmap](https://docs.ansible.com/projects/ansible/latest/roadmap/ansible_roadmap_index.html) * [Ansible project 13.0](https://docs.ansible.com/projects/ansible/latest/roadmap/COLLECTIONS_13.html) * [Ansible project 12.0](https://docs.ansible.com/projects/ansible/latest/roadmap/COLLECTIONS_12.html) * [Ansible project 11.0](https://docs.ansible.com/projects/ansible/latest/roadmap/COLLECTIONS_11.html) * [Ansible project 10.0](https://docs.ansible.com/projects/ansible/latest/roadmap/COLLECTIONS_10.html) * [Ansible project 9.0](https://docs.ansible.com/projects/ansible/latest/roadmap/COLLECTIONS_9.html) * [Ansible project 8.0](https://docs.ansible.com/projects/ansible/latest/roadmap/COLLECTIONS_8.html) * [Ansible project 7.0](https://docs.ansible.com/projects/ansible/latest/roadmap/COLLECTIONS_7.html) * [Ansible project 6.0](https://docs.ansible.com/projects/ansible/latest/roadmap/COLLECTIONS_6.html) * [Ansible project 5.0](https://docs.ansible.com/projects/ansible/latest/roadmap/COLLECTIONS_5.html) * [Ansible project 4.0](https://docs.ansible.com/projects/ansible/latest/roadmap/COLLECTIONS_4.html) * [Ansible project 3.0](https://docs.ansible.com/projects/ansible/latest/roadmap/COLLECTIONS_3_0.html) * [Ansible project 2.10](https://docs.ansible.com/projects/ansible/latest/roadmap/COLLECTIONS_2_10.html) * [Older Roadmaps](https://docs.ansible.com/projects/ansible/latest/roadmap/old_roadmap_index.html) * [ansible-core Roadmaps](https://docs.ansible.com/projects/ansible/latest/roadmap/ansible_core_roadmap_index.html) * [Ansible-core 2.20](https://docs.ansible.com/projects/ansible/latest/roadmap/ROADMAP_2_20.html) * [Ansible-core 2.19](https://docs.ansible.com/projects/ansible/latest/roadmap/ROADMAP_2_19.html) * [Ansible-core 2.18](https://docs.ansible.com/projects/ansible/latest/roadmap/ROADMAP_2_18.html) * [Ansible-core 2.17](https://docs.ansible.com/projects/ansible/latest/roadmap/ROADMAP_2_17.html) * [Ansible-core 2.16](https://docs.ansible.com/projects/ansible/latest/roadmap/ROADMAP_2_16.html) * [Ansible-core 2.15](https://docs.ansible.com/projects/ansible/latest/roadmap/ROADMAP_2_15.html) * [Ansible-core 2.14](https://docs.ansible.com/projects/ansible/latest/roadmap/ROADMAP_2_14.html) * [Ansible-core 2.13](https://docs.ansible.com/projects/ansible/latest/roadmap/ROADMAP_2_13.html) * [Ansible-core 2.12](https://docs.ansible.com/projects/ansible/latest/roadmap/ROADMAP_2_12.html) * [Ansible-core 2.11](https://docs.ansible.com/projects/ansible/latest/roadmap/ROADMAP_2_11.html) * [Ansible-base 2.10](https://docs.ansible.com/projects/ansible/latest/roadmap/ROADMAP_2_10.html) --- # Ansible Compat Library [Skip to content](https://docs.ansible.com/projects/compat/#examples) [](https://github.com/ansible/ansible-compat/blob/main/docs/index.md "Edit this page") Examples[¶](https://docs.ansible.com/projects/compat/#examples "Permanent link") ================================================================================= Using Ansible runtime[¶](https://docs.ansible.com/projects/compat/#using-ansible-runtime "Permanent link") ----------------------------------------------------------------------------------------------------------- example.py `[](https://docs.ansible.com/projects/compat/#__codelineno-0-1) """Sample use of Runtime class.""" [](https://docs.ansible.com/projects/compat/#__codelineno-0-2) [](https://docs.ansible.com/projects/compat/#__codelineno-0-3) from ansible_compat.runtime import Runtime [](https://docs.ansible.com/projects/compat/#__codelineno-0-4) [](https://docs.ansible.com/projects/compat/#__codelineno-0-5) [](https://docs.ansible.com/projects/compat/#__codelineno-0-6) def test_runtime_example() -> None: [](https://docs.ansible.com/projects/compat/#__codelineno-0-7) """Test basic functionality of Runtime class.""" [](https://docs.ansible.com/projects/compat/#__codelineno-0-8) # instantiate the runtime using isolated mode, so installing new [](https://docs.ansible.com/projects/compat/#__codelineno-0-9) # roles/collections do not pollute the default setup. [](https://docs.ansible.com/projects/compat/#__codelineno-0-10) runtime = Runtime(isolated=True, max_retries=3) [](https://docs.ansible.com/projects/compat/#__codelineno-0-11) [](https://docs.ansible.com/projects/compat/#__codelineno-0-12) # Print Ansible core version [](https://docs.ansible.com/projects/compat/#__codelineno-0-13) _ = runtime.version # 2.9.10 (Version object) [](https://docs.ansible.com/projects/compat/#__codelineno-0-14) # Get configuration info from runtime [](https://docs.ansible.com/projects/compat/#__codelineno-0-15) _ = runtime.config.collections_path [](https://docs.ansible.com/projects/compat/#__codelineno-0-16) [](https://docs.ansible.com/projects/compat/#__codelineno-0-17) # Detect if current project is a collection and install its requirements [](https://docs.ansible.com/projects/compat/#__codelineno-0-18) runtime.prepare_environment(install_local=True) # will retry 3 times if needed [](https://docs.ansible.com/projects/compat/#__codelineno-0-19) [](https://docs.ansible.com/projects/compat/#__codelineno-0-20) # Install a new collection (will retry 3 times if needed) [](https://docs.ansible.com/projects/compat/#__codelineno-0-21) runtime.install_collection("examples/reqs_v2/community-molecule-0.1.0.tar.gz") [](https://docs.ansible.com/projects/compat/#__codelineno-0-22) [](https://docs.ansible.com/projects/compat/#__codelineno-0-23) # Execute a command [](https://docs.ansible.com/projects/compat/#__codelineno-0-24) result = runtime.run(["ansible-doc", "--list"]) [](https://docs.ansible.com/projects/compat/#__codelineno-0-25) assert result.returncode == 0` Access to Ansible configuration[¶](https://docs.ansible.com/projects/compat/#access-to-ansible-configuration "Permanent link") ------------------------------------------------------------------------------------------------------------------------------- As you may not want to parse `ansible-config dump` yourself, you can make use of a simple python class that facilitates access to it, using python data types. `[](https://docs.ansible.com/projects/compat/#__codelineno-1-1) """Sample usage of AnsibleConfig.""" [](https://docs.ansible.com/projects/compat/#__codelineno-1-2) [](https://docs.ansible.com/projects/compat/#__codelineno-1-3) from ansible_compat.config import AnsibleConfig [](https://docs.ansible.com/projects/compat/#__codelineno-1-4) [](https://docs.ansible.com/projects/compat/#__codelineno-1-5) [](https://docs.ansible.com/projects/compat/#__codelineno-1-6) def test_example_config() -> None: [](https://docs.ansible.com/projects/compat/#__codelineno-1-7) """Test basic functionality of AnsibleConfig.""" [](https://docs.ansible.com/projects/compat/#__codelineno-1-8) cfg = AnsibleConfig() [](https://docs.ansible.com/projects/compat/#__codelineno-1-9) assert isinstance(cfg.ACTION_WARNINGS, bool) [](https://docs.ansible.com/projects/compat/#__codelineno-1-10) # you can also use lowercase: [](https://docs.ansible.com/projects/compat/#__codelineno-1-11) assert isinstance(cfg.action_warnings, bool) [](https://docs.ansible.com/projects/compat/#__codelineno-1-12) # you can also use it as dictionary [](https://docs.ansible.com/projects/compat/#__codelineno-1-13) assert cfg["action_warnings"] == cfg.action_warnings` --- # Installing - Ansible Pytest Documentation [Skip to content](https://docs.ansible.com/projects/pytest-ansible/installing/#installing) [](https://github.com/ansible/pytest-ansible/blob/main/docs/installing.md "Edit this page") Installing[¶](https://docs.ansible.com/projects/pytest-ansible/installing/#installing "Permanent link") ======================================================================================================== Requirements[¶](https://docs.ansible.com/projects/pytest-ansible/installing/#requirements "Permanent link") ------------------------------------------------------------------------------------------------------------ * Ansible 2.9 or newer * Pytest Installing the latest version[¶](https://docs.ansible.com/projects/pytest-ansible/installing/#installing-the-latest-version "Permanent link") ---------------------------------------------------------------------------------------------------------------------------------------------- You can install the most recent version of pytest-ansible with the \[pip\] Python package manager. `[](https://docs.ansible.com/projects/pytest-ansible/installing/#__codelineno-0-1) pip install pytest-ansible` Install this plugin using `pip`: `[](https://docs.ansible.com/projects/pytest-ansible/installing/#__codelineno-1-1) pip install pytest-ansible` --- # Community - Ansible Pytest Documentation [Skip to content](https://docs.ansible.com/projects/pytest-ansible/community/#community) [](https://github.com/ansible/pytest-ansible/blob/main/docs/community.md "Edit this page") Community[¶](https://docs.ansible.com/projects/pytest-ansible/community/#community "Permanent link") ===================================================================================================== Connect with the pytest-ansible community! Join the Ansible forum to ask questions, get help, and interact with the community. * [Get Help](https://forum.ansible.com/c/help/6) : get help or help others. Please add appropriate tags if you start new discussions, for example you can use the `devtools` tag. * [Social Spaces](https://forum.ansible.com/c/chat/4) : meet and interact with fellow enthusiasts. * [News & Announcements](https://forum.ansible.com/c/news/5) : track project-wide announcements including social events. To get release announcements and important changes from the community, see the [Bullhorn newsletter](https://docs.ansible.com/ansible/devel/community/communication.html#the-bullhorn) . If you encounter security-related concerns, report them via email to [security@ansible.com](mailto:security@ansible.com) . --- # Galaxy NG [Skip to content](https://docs.ansible.com/projects/galaxy-ng/en/latest/#galaxy-ng) [](https://github.com/ansible/galaxy_ng/edit/main/docs/index.md "Edit this page") [](https://github.com/ansible/galaxy_ng/raw/main/docs/index.md "View source of this page") ![](https://docs.ansible.com/projects/galaxy-ng/en/latest/imgs/medium.png) Warning This documentation is a **Work In Progress** some pages are incomplete. Galaxy NG[¶](https://docs.ansible.com/projects/galaxy-ng/en/latest/#galaxy-ng "Permanent link") ================================================================================================ ![](https://raw.githubusercontent.com/ansible/logos/be211ebccc316652eb725db688e75d932f8fa073/galaxy/galaxy-logo.svg) [![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=ansible_galaxy_ng&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=ansible_galaxy_ng) [![Build Status](https://github.com/ansible/galaxy_ng/actions/workflows/ci-docker-compose-integration.yml/badge.svg)](https://github.com/ansible/galaxy_ng/actions/workflows/ci-docker-compose-integration.yml) [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=ansible_galaxy_ng&metric=coverage)](https://sonarcloud.io/summary/new_code?id=ansible_galaxy_ng) **Source Code**: [https://github.com/ansible/galaxy\_ng](https://github.com/ansible/galaxy_ng) A [Pulp](https://pulpproject.org/) plugin to support hosting your very own Ansible Galaxy server. Our mission is to help organizations share Ansible automation and promote a culture of collaboration around Ansible automation development. We'll be providing features that make it easy to create, discover, use and distribute Ansible automation content. For users[¶](https://docs.ansible.com/projects/galaxy-ng/en/latest/#for-users "Permanent link") ------------------------------------------------------------------------------------------------ Check out our: * [Installation guide](https://docs.ansible.com/projects/galaxy-ng/en/latest/usage_guide/installation.html) to install Galaxy NG * [Collection guide](https://docs.ansible.com/projects/galaxy-ng/en/latest/usage_guide/collections.html) for information on managing collections * [Execution environment guide](https://docs.ansible.com/projects/galaxy-ng/en/latest/usage_guide/execution_environments.html) for information on managing execution environments * [RBAC and User management guide](https://docs.ansible.com/projects/galaxy-ng/en/latest/usage_guide/rbac.html) for information on setting up users and managing permissions Back to top --- # Glossary — Ansible Builder Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/builder/en/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Builder Documentation](https://docs.ansible.com/projects/builder/en/latest/) * [](https://docs.ansible.com/projects/builder/en/latest/) * Glossary * [View page source](https://docs.ansible.com/projects/builder/en/latest/_sources/glossary.rst.txt) * * * Glossary[](https://docs.ansible.com/projects/builder/en/latest/glossary/#glossary "Link to this heading") =========================================================================================================== execution environment[](https://docs.ansible.com/projects/builder/en/latest/glossary/#term-execution-environment "Link to this term") execution environments are container images intended to be used as Ansible control nodes. Starting in version 2.0, [ansible-runner](https://docs.ansible.com/projects/runner/en/latest/) . can make use of these images. Control node[](https://docs.ansible.com/projects/builder/en/latest/glossary/#term-Control-node "Link to this term") The machine or container running Ansible. See the [Ansible documentation](https://docs.ansible.com/projects/ansible/latest/network/getting_started/basic_concepts.html#control-node) for a more comprehensive explanation. --- # Installation — Ansible Builder Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/builder/en/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Builder Documentation](https://docs.ansible.com/projects/builder/en/latest/) * [](https://docs.ansible.com/projects/builder/en/latest/) * Installation * [View page source](https://docs.ansible.com/projects/builder/en/latest/_sources/installation.rst.txt) * * * Installation[](https://docs.ansible.com/projects/builder/en/latest/installation/#installation "Link to this heading") ======================================================================================================================= [Requirements](https://docs.ansible.com/projects/builder/en/latest/installation/#id1) [](https://docs.ansible.com/projects/builder/en/latest/installation/#requirements "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * To build images, you must install a containerization tool - either `podman` or `docker` - as well as the `ansible-builder` Python package. * The `--container-runtime` option must correspond to the containerization tool you use. * `ansible-builder` version `3.x` requires Python `3.9` or higher. [Base Image Requirements](https://docs.ansible.com/projects/builder/en/latest/installation/#id2) [](https://docs.ansible.com/projects/builder/en/latest/installation/#base-image-requirements "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Ansible Builder requires RPM-based container images (those using `dnf` or `microdnf` package management) as the base for execution environments. Non-RPM-based distributions such as Debian, Ubuntu, or Alpine are not supported. For detailed information about choosing an appropriate base image and a list of images that should work, see the [Choosing a base image](https://docs.ansible.com/projects/builder/en/latest/#choosing-base-image) section. [Install from PyPI](https://docs.ansible.com/projects/builder/en/latest/installation/#id3) [](https://docs.ansible.com/projects/builder/en/latest/installation/#install-from-pypi "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- $ pip3 install ansible-builder Note An **alternative** approach to installing `ansible-builder` is using the `ansible-dev-tools` package. [Ansible Development Tools (ADT)](https://docs.ansible.com/projects/dev-tools/) is a single Python package that includes all necessary tools to set up a development environment, generate new collections, build and test the content. \# This also installs ansible-core if it is not already installed $ pip3 install ansible-dev-tools [Install from Source](https://docs.ansible.com/projects/builder/en/latest/installation/#id4) [](https://docs.ansible.com/projects/builder/en/latest/installation/#install-from-source "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- To install from the mainline development branch: $ pip3 install https://github.com/ansible/ansible-builder/archive/devel.zip To install from a specific tag or branch, replace `` in the following example: $ pip3 install https://github.com/ansible/ansible-builder/archive/.zip --- # New Ansible Releases - Ansible Package Release Management [Skip to content](https://docs.ansible.com/projects/ansible-build-data/new-ansible/#new-ansible-releases) New Ansible Releases[¶](https://docs.ansible.com/projects/ansible-build-data/new-ansible/#new-ansible-releases "Permanent link") ================================================================================================================================= Preamble[¶](https://docs.ansible.com/projects/ansible-build-data/new-ansible/#preamble "Permanent link") --------------------------------------------------------------------------------------------------------- Releasing new Ansible major versions and frozen releases requires some special handling. For information about the general release process, see [Ansible Release Process](https://docs.ansible.com/projects/ansible-build-data/release-process/) . Setting up for a new major release[¶](https://docs.ansible.com/projects/ansible-build-data/new-ansible/#setting-up-for-a-new-major-release "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------------------------- After the release of `X.0.0`, it is necessary to create the directory structure for Ansible `X+1`. 1. Determine the current major version and next major version: `[](https://docs.ansible.com/projects/ansible-build-data/new-ansible/#__codelineno-0-1) CURRENT_MAJOR_VERSION=11 [](https://docs.ansible.com/projects/ansible-build-data/new-ansible/#__codelineno-0-2) NEXT_MAJOR_VERSION=12` 2. Create the major version directory: `[](https://docs.ansible.com/projects/ansible-build-data/new-ansible/#__codelineno-1-1) mkdir "${NEXT_MAJOR_VERSION}/"` 3. Copy over the `ansible.in` and `collection-meta.yaml` files: `[](https://docs.ansible.com/projects/ansible-build-data/new-ansible/#__codelineno-2-1) cp "${CURRENT_MAJOR_VERSION}/ansible.in" "${CURRENT_MAJOR_VERSION}/collection-meta.yaml" \ [](https://docs.ansible.com/projects/ansible-build-data/new-ansible/#__codelineno-2-2) "${NEXT_MAJOR_VERSION}/"` 4. Symlink `${CURRENT_MAJOR_VERSION}.0.0`'s deps file to `${NEXT_MAJOR_VERSION}/ancestor.deps`: `[](https://docs.ansible.com/projects/ansible-build-data/new-ansible/#__codelineno-3-1) ln -sr "${CURRENT_MAJOR_VERSION}/ansible-${CURRENT_MAJOR_VERSION}.0.0.deps" \ [](https://docs.ansible.com/projects/ansible-build-data/new-ansible/#__codelineno-3-2) "${NEXT_MAJOR_VERSION}/ancestor.deps"` 5. Create a stub `changelog.yaml` file: `[](https://docs.ansible.com/projects/ansible-build-data/new-ansible/#__codelineno-4-1) cat <${NEXT_MAJOR_VERSION}/changelog.yaml [](https://docs.ansible.com/projects/ansible-build-data/new-ansible/#__codelineno-4-2) --- [](https://docs.ansible.com/projects/ansible-build-data/new-ansible/#__codelineno-4-3) ancestor: ${CURRENT_MAJOR_VERSION}.0.0 [](https://docs.ansible.com/projects/ansible-build-data/new-ansible/#__codelineno-4-4) releases: {} [](https://docs.ansible.com/projects/ansible-build-data/new-ansible/#__codelineno-4-5) EOF` 6. Create a blank `validate-tags-ignores` file: `[](https://docs.ansible.com/projects/ansible-build-data/new-ansible/#__codelineno-5-1) touch "${NEXT_MAJOR_VERSION}/validate-tags-ignores"` 7. Create a blank `ansible-${NEXT_MAJOR_VERSION}.constraints` file: `[](https://docs.ansible.com/projects/ansible-build-data/new-ansible/#__codelineno-6-1) touch "${NEXT_MAJOR_VERSION}/ansible-${NEXT_MAJOR_VERSION}.constraints"` You might need to fill this with some initial data. 8. Add the next major version to ansible-build-data's CI: Open `.github/workflows/antsibull-build.yml` and add the following block to the matrix: `[](https://docs.ansible.com/projects/ansible-build-data/new-ansible/#__codelineno-7-1) - name: Ansible ${NEXT_MAJOR_VERSION} [](https://docs.ansible.com/projects/ansible-build-data/new-ansible/#__codelineno-7-2) ansible_version: ${NEXT_MAJOR_VERSION}.99.0 [](https://docs.ansible.com/projects/ansible-build-data/new-ansible/#__codelineno-7-3) ansible_major_version: ${NEXT_MAJOR_VERSION}` 9. Update `collection-meta.yaml` and `ansible.in`: 1. Find all collection entries from `collections` in `collections-meta.yaml` that have a `removal` entry with `major_version` equal to `${NEXT_MAJOR_VERSION}`. * If the `removal` entry has an `updates` and the last entry is about keeping them (`readded_version` or `cancelled_version`), remove the `removal` entry completely. * Otherwise, cut out the collection's entry and paste it into a temporary buffer / file. 2. For every cut out metadata entry, remove the corresponding entry in `ansible.in`. 3. For every cut out metadata entry, find the correct place in `removed_collections` in `collections-meta.yaml` to insert the removed part from `collections-meta.yaml` and paste the entry there. Modify the entry as follows: * Replace `major_version: ${NEXT_MAJOR_VERSION}` by `version: ${NEXT_MAJOR_VERSION}.0.0a1`. * Remove `announce_version` if present. * Remove `updates` if present. 10. Validate build data: `[](https://docs.ansible.com/projects/ansible-build-data/new-ansible/#__codelineno-8-1) antsibull-build lint-build-data --data-dir "${NEXT_MAJOR_VERSION}" "${NEXT_MAJOR_VERSION}"` 11. Commit the changes: `[](https://docs.ansible.com/projects/ansible-build-data/new-ansible/#__codelineno-9-1) git add "${NEXT_MAJOR_VERSION}" .github/workflows/antsibull-build.yml` 12. Submit a PR against [the ansible-build-data repository](https://github.com/ansible-community/ansible-build-data/) . --- # Ansible AWX Operator Documentation [Skip to content](https://docs.ansible.com/projects/awx-operator/en/latest/#awx-operator) [](https://github.com/ansible/awx-operator/blob/devel/docs/index.md "Edit this page") AWX Operator[¶](https://docs.ansible.com/projects/awx-operator/en/latest/#awx-operator "Permanent link") ========================================================================================================= [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![Build Status](https://github.com/ansible/awx-operator/workflows/CI/badge.svg?event=push)](https://github.com/ansible/awx-operator/actions) [![Code of Conduct](https://img.shields.io/badge/code%20of%20conduct-Ansible-yellow.svg)](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html) An [Ansible AWX](https://github.com/ansible/awx) operator for Kubernetes built with [Operator SDK](https://github.com/operator-framework/operator-sdk) and Ansible. The AWX Operator is meant to be deployed in your Kubernetes cluster(s) and can be used to install and manage the lifecycle of an AWX instance in the same namespace. Documentation[¶](https://docs.ansible.com/projects/awx-operator/en/latest/#documentation "Permanent link") ----------------------------------------------------------------------------------------------------------- The AWX Operator documentation is available at [https://ansible.readthedocs.io/projects/awx-operator/](https://ansible.readthedocs.io/projects/awx-operator/) > Helm chart documentation is available at [https://ansible-community.github.io/awx-operator-helm/](https://ansible-community.github.io/awx-operator-helm/) Contributing[¶](https://docs.ansible.com/projects/awx-operator/en/latest/#contributing "Permanent link") --------------------------------------------------------------------------------------------------------- Please visit [our contributing guidelines](https://github.com/ansible/awx-operator/blob/devel/CONTRIBUTING.md) . For docs changes, create PRs on the appropriate files in the `/docs` folder. The development environment consists of running an [`up.sh`](https://github.com/ansible/awx-operator/blob/devel/up.sh) and a [`down.sh`](https://github.com/ansible/awx-operator/blob/devel/down.sh) script, which applies or deletes yaml on the Openshift or K8s cluster you are connected to. See the [development.md](https://github.com/ansible/awx-operator/blob/devel/docs/development.md) for information on how to deploy and test changes from your branch. Author[¶](https://docs.ansible.com/projects/awx-operator/en/latest/#author "Permanent link") --------------------------------------------------------------------------------------------- This operator was originally built in 2019 by [Jeff Geerling](https://www.jeffgeerling.com/) and is now maintained by the Ansible Team Code of Conduct[¶](https://docs.ansible.com/projects/awx-operator/en/latest/#code-of-conduct "Permanent link") --------------------------------------------------------------------------------------------------------------- We ask all of our community members and contributors to adhere to the [Ansible code of conduct](http://docs.ansible.com/ansible/latest/community/code_of_conduct.html) . If you have questions or need assistance, please reach out to our community team at [codeofconduct@ansible.com](mailto:codeofconduct@ansible.com) Get Involved[¶](https://docs.ansible.com/projects/awx-operator/en/latest/#get-involved "Permanent link") --------------------------------------------------------------------------------------------------------- We welcome your feedback, questions and ideas. Here's how to reach the community. ### Forum[¶](https://docs.ansible.com/projects/awx-operator/en/latest/#forum "Permanent link") Join the [Ansible Forum](https://forum.ansible.com/) as a single starting point and our default communication platform for questions and help, development discussions, events, and much more. [Register](https://forum.ansible.com/signup?) to join the community. Search by categories and tags to find interesting topics or start a new one; subscribe only to topics you need! * [Get Help](https://forum.ansible.com/c/help/6) : get help or help others. Please add appropriate tags if you start new discussions, for example `awx-operator` and `documentation`. * [Posts tagged with 'awx-operator'](https://forum.ansible.com/tag/awx-operator) : subscribe to participate in project-related conversations. * [Bullhorn newsletter](https://docs.ansible.com/ansible/devel/community/communication.html#the-bullhorn) used to announce releases and important changes. * [Social Spaces](https://forum.ansible.com/c/chat/4) : gather and interact with fellow enthusiasts. * [News & Announcements](https://forum.ansible.com/c/news/5) : track project-wide announcements including social events. For more information on the forum navigation, see [Navigating the Ansible forum](https://forum.ansible.com/t/navigating-the-ansible-forum-tags-categories-and-concepts/39) post. ### Matrix[¶](https://docs.ansible.com/projects/awx-operator/en/latest/#matrix "Permanent link") For real-time interactions, conversations in the community happen over the Matrix protocol in the following channels: * [#awx:ansible.com](https://matrix.to/#/#awx:ansible.com) : AWX and AWX-Operator project-related discussions. * [#docs:ansible.im](https://matrix.to/#/#docs:ansible.im) : Ansible, AWX and AWX-Operator documentation-related discussions. For more information, see the community-hosted [Matrix FAQ](https://hackmd.io/@ansible-community/community-matrix-faq) . --- # Join the Community - antsibull-docs – Ansible Documentation Build Scripts [Skip to content](https://docs.ansible.com/projects/antsibull-docs/community/#community) Community[¶](https://docs.ansible.com/projects/antsibull-docs/community/#community "Permanent link") ===================================================================================================== We welcome your feedback, questions and ideas. Here's how to reach the community. Forum[¶](https://docs.ansible.com/projects/antsibull-docs/community/#forum "Permanent link") --------------------------------------------------------------------------------------------- Join the [Ansible Forum](https://forum.ansible.com/) as a single starting point and our default communication platform for questions and help, development discussions, events, and much more. [Register on the Forum](https://forum.ansible.com/signup?) to join the community. Search by categories and tags to find interesting topics or start a new one; subscribe only to topics you need! * [Posts tagged with 'antsibull'](https://forum.ansible.com/tag/antsibull) : subscribe to participate in project-related conversations. * [Social Spaces](https://forum.ansible.com/c/chat/4) : gather and interact with fellow enthusiasts. * [News & Announcements](https://forum.ansible.com/c/news/5) : track project-wide announcements including social events. The [Bullhorn newsletter](https://docs.ansible.com/projects/ansible/devel/community/communication.html#the-bullhorn) , which is used to announce releases and important changes, can also be found here. For more information on the forum navigation, see the [Navigating the Ansible forum](https://forum.ansible.com/t/navigating-the-ansible-forum-tags-categories-and-concepts/39) post. Matrix[¶](https://docs.ansible.com/projects/antsibull-docs/community/#matrix "Permanent link") ----------------------------------------------------------------------------------------------- For real-time interactions, join the [#antsibull:ansible.com Matrix room](https://matrix.to/#/#antsibull:ansible.com) . See the [Ansible communication guide](https://docs.ansible.com/projects/ansible/devel/community/communication.html#real-time-chat) for more information on Matrix. --- # Getting Started - Ansible Pytest Documentation [Skip to content](https://docs.ansible.com/projects/pytest-ansible/getting_started/#getting-started) [](https://github.com/ansible/pytest-ansible/blob/main/docs/getting_started.md "Edit this page") Getting Started[¶](https://docs.ansible.com/projects/pytest-ansible/getting_started/#getting-started "Permanent link") ======================================================================================================================= Unit Testing for Ansible Collections[¶](https://docs.ansible.com/projects/pytest-ansible/getting_started/#unit-testing-for-ansible-collections "Permanent link") ----------------------------------------------------------------------------------------------------------------------------------------------------------------- The `pytest-ansible` plugin allows ansible collection's unit tests to be run with only `pytest`. It offers a focused approach to testing individual Ansible modules. With this plugin, you can write and execute unit tests specifically for Ansible modules, ensuring the accuracy and reliability of your module code. This is particularly useful for verifying the correctness of module behavior in isolation. To use `pytest-ansible`, follow these steps: 1. Install the plugin using \[pip\]: `[](https://docs.ansible.com/projects/pytest-ansible/getting_started/#__codelineno-0-1) pip install pytest-ansible` 1. Ensure you have Python 3.10 or greater, ansible-core, and pytest installed. 2. Depending on your preferred directory structure, you can clone collections into the appropriate paths. 3. **Collection Tree Approach**: The preferred approach is to clone the collections being developed into it's proper collection tree path. This eliminates the need for any symlinks and other collections being developed can be cloned into the same tree structure. `[](https://docs.ansible.com/projects/pytest-ansible/getting_started/#__codelineno-1-1) git clone collections/ansible_collections//` Note: Run `pytest` in the root of the collection directory, adjacent to the collection's `galaxy.yml` file. 4. **Shallow Tree Approach**: `[](https://docs.ansible.com/projects/pytest-ansible/getting_started/#__codelineno-2-1) git clone ` Notes: - Run `pytest` in the root of the collection directory, adjacent to the collection's `galaxy.yml` file. - A collections directory will be created in the repository directory, and collection content will be linked into it. 5. Execute the unit tests using pytest: `pytest tests` Help[¶](https://docs.ansible.com/projects/pytest-ansible/getting_started/#help "Permanent link") ------------------------------------------------------------------------------------------------- The following may be added to the collections' `pyproject.toml` file to limit warnings and set the default path for the collection's tests `[](https://docs.ansible.com/projects/pytest-ansible/getting_started/#__codelineno-3-1) [tool.pytest.ini_options] [](https://docs.ansible.com/projects/pytest-ansible/getting_started/#__codelineno-3-2) testpaths = [ [](https://docs.ansible.com/projects/pytest-ansible/getting_started/#__codelineno-3-3) "tests", [](https://docs.ansible.com/projects/pytest-ansible/getting_started/#__codelineno-3-4) ] [](https://docs.ansible.com/projects/pytest-ansible/getting_started/#__codelineno-3-5) filterwarnings = [ [](https://docs.ansible.com/projects/pytest-ansible/getting_started/#__codelineno-3-6) 'ignore:AnsibleCollectionFinder has already been configured', [](https://docs.ansible.com/projects/pytest-ansible/getting_started/#__codelineno-3-7) ]` Information from the `galaxy.yml` file is used to build the `collections` directory structure and link the contents. The `galaxy.yml` file should reflect the correct collection namespace and name. One way to detect issues without running the tests is to run: `[](https://docs.ansible.com/projects/pytest-ansible/getting_started/#__codelineno-4-1) pytest --collect-only` The follow errors may be seen: `[](https://docs.ansible.com/projects/pytest-ansible/getting_started/#__codelineno-5-1) E ModuleNotFoundError: No module named 'ansible_collections'` * Check the `galaxy.yml` file for an accurate namespace and name * Ensure `pytest` is being run from the collection's root directory, adjacent to the `galaxy.yml` `[](https://docs.ansible.com/projects/pytest-ansible/getting_started/#__codelineno-6-1) HINT: remove __pycache__ / .pyc files and/or use a unique basename for your test file modules` Molecule Scenario Integration[¶](https://docs.ansible.com/projects/pytest-ansible/getting_started/#molecule-scenario-integration "Permanent link") --------------------------------------------------------------------------------------------------------------------------------------------------- This functionality assists in running Molecule `scenarios` using `pytest`. It enables pytest discovery of all `molecule.yml` files inside the codebase and runs them as pytest tests. It allows you to include Molecule scenarios as part of your pytest test suite, allowing you to thoroughly test your Ansible roles and playbooks across different scenarios and environments. Running molecule scenarios using pytest[¶](https://docs.ansible.com/projects/pytest-ansible/getting_started/#running-molecule-scenarios-using-pytest "Permanent link") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- Molecule scenarios can be tested using 2 different methods if molecule is installed. **Recommended:** Add a `test_integration.py` file to the `tests/integration` directory of the ansible collection: `[](https://docs.ansible.com/projects/pytest-ansible/getting_started/#__codelineno-7-1) """Tests for molecule scenarios.""" [](https://docs.ansible.com/projects/pytest-ansible/getting_started/#__codelineno-7-2) [](https://docs.ansible.com/projects/pytest-ansible/getting_started/#__codelineno-7-3) from __future__ import absolute_import, division, print_function [](https://docs.ansible.com/projects/pytest-ansible/getting_started/#__codelineno-7-4) [](https://docs.ansible.com/projects/pytest-ansible/getting_started/#__codelineno-7-5) from pytest_ansible.molecule import MoleculeScenario [](https://docs.ansible.com/projects/pytest-ansible/getting_started/#__codelineno-7-6) [](https://docs.ansible.com/projects/pytest-ansible/getting_started/#__codelineno-7-7) [](https://docs.ansible.com/projects/pytest-ansible/getting_started/#__codelineno-7-8) def test_integration(molecule_scenario: MoleculeScenario) -> None: [](https://docs.ansible.com/projects/pytest-ansible/getting_started/#__codelineno-7-9) """Run molecule for each scenario. [](https://docs.ansible.com/projects/pytest-ansible/getting_started/#__codelineno-7-10) [](https://docs.ansible.com/projects/pytest-ansible/getting_started/#__codelineno-7-11) :param molecule_scenario: The molecule scenario object [](https://docs.ansible.com/projects/pytest-ansible/getting_started/#__codelineno-7-12) """ [](https://docs.ansible.com/projects/pytest-ansible/getting_started/#__codelineno-7-13) proc = molecule_scenario.test() [](https://docs.ansible.com/projects/pytest-ansible/getting_started/#__codelineno-7-14) assert proc.returncode == 0` The `molecule_scenario` fixture provides parameterized molecule scenarios discovered in the collection's `extensions/molecule` directory, as well as other directories within the collection. `molecule test -s ` will be run for each scenario and a completed subprocess returned from the `test()` call. --- # home - Ansible Creator Documentation [Skip to content](https://docs.ansible.com/projects/creator/#welcome-to-ansible-creator-documentation) [](https://github.com/ansible/ansible-creator/blob/main/docs/index.md "Edit this page") [](https://github.com/ansible/ansible-creator/raw/main/docs/index.md "View source of this page") Welcome to Ansible-Creator Documentation[¶](https://docs.ansible.com/projects/creator/#welcome-to-ansible-creator-documentation "Permanent link") ================================================================================================================================================== The `ansible-creator` is a Command-Line Interface (CLI) tool designed for effortlessly scaffolding all your Ansible content. Whether you are initializing an Ansible Collection or creating the framework for specific plugins, this tool streamlines the process with efficiency and precision based on your requirements. This documentation serves as a detailed guide for using ansible-creator, emphasizing the 'init' and 'add' functionalities. The 'init' functionality initializes a new Ansible project whereas 'add' enables you to add resources to an existing ansible project. Licensing[¶](https://docs.ansible.com/projects/creator/#licensing "Permanent link") ------------------------------------------------------------------------------------ **ansible-creator** is licensed under the Apache License version 2. Refer to the [LICENSE](http://www.apache.org/licenses/LICENSE-2.0) file for the full text. Back to top --- # Collection-level dependencies — Ansible Builder Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/builder/en/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Builder Documentation](https://docs.ansible.com/projects/builder/en/latest/) * [](https://docs.ansible.com/projects/builder/en/latest/) * Collection-level dependencies * [View page source](https://docs.ansible.com/projects/builder/en/latest/_sources/collection_metadata.rst.txt) * * * Collection-level dependencies[](https://docs.ansible.com/projects/builder/en/latest/collection_metadata/#collection-level-dependencies "Link to this heading") ================================================================================================================================================================ When Ansible Builder installs collections into an execution environment, it also installs their controller-side Python or system package dependencies listed by each collection on Galaxy. For Ansible Builder to find and install collection dependencies, those dependencies must be defined in files in a collection repository. Note If present, the files below must be included in the packaged collection on Galaxy. Ansible Builder cannot install dependencies listed in files that are included in the `build_ignore` of a collection, because those files are not included in the collection artifact. If you are a collection maintainer, make sure the controller-side dependencies are specified and [verified](https://docs.ansible.com/projects/builder/en/latest/collection_metadata/#verify-collection-metadata) . We recommend you specify paths to dependency files in the `meta/execution-environment.yml` file. Here is an example of its content: dependencies: python: meta/ee-requirements.txt \# List Python package requirements in the file system: meta/ee-bindep.txt \# List system package requirements in the file If the `meta/execution-environment.yml` file is not present, by default, Ansible Builder will expect the dependencies to be defined in: * the `requirements.txt` file in the collection root directory for Python package requirements * the `bindep.txt` file in the collection root directory for system package requirements Note If your collection uses the `requirements.txt` or `bindep.txt` files in its root directory for anything else but its controller-side dependencies, for example, for listing testing requirements, make sure you use the `meta/execution-environment.yml` file to specify other dependency files for execution environment purposes. Dependency introspection[](https://docs.ansible.com/projects/builder/en/latest/collection_metadata/#dependency-introspection "Link to this heading") ====================================================================================================================================================== If any dependencies are given, the introspection is run by Ansible Builder so that the requirements are found before container image assembly. A user can see the introspection output during the builder intermediate phase using the `build -v3` option. How to verify collection-level metadata[](https://docs.ansible.com/projects/builder/en/latest/collection_metadata/#how-to-verify-collection-level-metadata "Link to this heading") ==================================================================================================================================================================================== Note Running the introspect command described below is not part of a typical workflow for building and using execution environments. Collection developers can verify that dependencies specified in the collection will be processed correctly by Ansible Builder. To do that, the collection has to be installed locally. When installing collections using ansible-galaxy[](https://docs.ansible.com/projects/builder/en/latest/collection_metadata/#when-installing-collections-using-ansible-galaxy "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ The easiest way to install a collection is to use the [ansible-galaxy](https://docs.ansible.com/projects/ansible/latest/collections_guide/collections_installing.html#installing-collections-with-ansible-galaxy) command which is a part of the `ansible` package. Run the `introspect` command against your collection path: ansible\-builder introspect COLLECTION\_PATH The default collection path used by the `ansible-galaxy` command is `~/.ansible/collections/`. Read more about collection paths in the [Ansible configuration settings](https://docs.ansible.com/projects/ansible/latest/reference_appendices/config.html#collections-paths) guide. Note Use the `-v3` option to `introspect` to see logging messages about requirements that are being excluded. When installing collections manually[](https://docs.ansible.com/projects/builder/en/latest/collection_metadata/#when-installing-collections-manually "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ If you download collection tarballs from [Galaxy](https://galaxy.ansible.com/) manually or clone collection git repositories, for the `introspect` command to work properly, be sure you store your collections using the following directory structure: ansible\_collections/NAMESPACE/COLLECTION For example, if you need to inspect the `community.docker` collection, the path will be: ansible\_collections/community/docker Then, if the `ansible_collection` directory is in your home directory, you can run `introspect` with the following command: ansible\-builder introspect ~/ ### Python Dependencies[](https://docs.ansible.com/projects/builder/en/latest/collection_metadata/#python-dependencies "Link to this heading") Ansible Builder combines all the Python requirements files from all collections into a single file. Certain package names are specifically _ignored_ by `ansible-builder`, meaning that Ansible Builder does not include them in the combined file of Python dependencies, even if a collection lists them as dependencies. These include test packages and packages that provide Ansible itself. The full list can be found in `EXCLUDE_REQUIREMENTS` in `src/ansible_builder/_target_scripts/introspect.py`. If you need to include one of these ignored package names, use the `--user-pip` option of the `introspect` command to list it in the user requirements file. Packages supplied this way are not processed against the list of excluded Python packages. Note These dependencies are subject to the same [PEP 508](https://peps.python.org/pep-0508/) format restrictions described for Python requirements in the [EE definition specification](https://docs.ansible.com/projects/builder/en/latest/definition/#python-pep508) . ### System-level Dependencies[](https://docs.ansible.com/projects/builder/en/latest/collection_metadata/#system-level-dependencies "Link to this heading") For system packages, use the `bindep` format to specify cross-platform requirements, so they can be installed by whichever package management system the execution environment uses. Collections should specify necessary requirements for `[platform:rpm]`. Ansible Builder combines system package entries from multiple collections into a single file. * Requirements with `compile` profile indicate that these requirements are needed to install other requirements (especially Python ones), but are not required to be in the final build. * Requirements with `epel` profile indicate that EPEL repositories will be enabled before installing these requirements. * Only requirements with _no_ profiles (runtime requirements) are installed to the image. Entries from multiple collections which are outright duplicates of each other may be consolidated in the combined file. --- # Home - Tox Ansible Documentation [Skip to content](https://docs.ansible.com/projects/tox-ansible/#tox-ansible-documentation) [](https://github.com/ansible/tox-ansible/blob/main/docs/index.md "Edit this page") Tox Ansible Documentation[¶](https://docs.ansible.com/projects/tox-ansible/#tox-ansible-documentation "Permanent link") ======================================================================================================================== > Need help or want to discuss the project? See our [Contributor guide](https://ansible.readthedocs.io/projects/tox-ansible/contributor_guide/#talk-to-us) > to join the conversation! About Tox Ansible[¶](https://docs.ansible.com/projects/tox-ansible/#about-tox-ansible "Permanent link") -------------------------------------------------------------------------------------------------------- `tox-ansible` is a utility designed to simplify the testing of ansible content collections. Implemented as `tox` plugin, `tox-ansible` provides a simple way to test ansible content collections across multiple python interpreter and ansible versions. `tox-ansible` uses familiar python testing tools to perform the actual testing. It uses `tox` to create and manage the testing environments, `ansible-test sanity` to run the sanity tests, and `pytest` to run the unit and integration tests. This eliminated the black box nature of other approaches and allows for more control over the testing process. When used on a local development system, each of the environments are left intact after a test run. This allows for easy debugging of failed tests for a given test type, python interpreter and ansible version. By using `tox` to create and manage the testing environments, Test outcomes should always be the same on a local development system as they are in a CI/CD pipeline. `tox` virtual environments are created in the `.tox` directory. These are easily deleted and recreated if needed. --- # Community - antsibull-changelog – Ansible Changelog Tool [Skip to content](https://docs.ansible.com/projects/antsibull-changelog/community/#community) Community[¶](https://docs.ansible.com/projects/antsibull-changelog/community/#community "Permanent link") ========================================================================================================== We welcome your feedback, questions and ideas. Here's how to reach the community. Forum[¶](https://docs.ansible.com/projects/antsibull-changelog/community/#forum "Permanent link") -------------------------------------------------------------------------------------------------- Join the [Ansible Forum](https://forum.ansible.com/) as a single starting point and our default communication platform for questions and help, development discussions, events, and much more. [Register on the Forum](https://forum.ansible.com/signup?) to join the community. Search by categories and tags to find interesting topics or start a new one; subscribe only to topics you need! * [Posts tagged with 'antsibull'](https://forum.ansible.com/tag/antsibull) : subscribe to participate in project-related conversations. * [Social Spaces](https://forum.ansible.com/c/chat/4) : gather and interact with fellow enthusiasts. * [News & Announcements](https://forum.ansible.com/c/news/5) : track project-wide announcements including social events. The [Bullhorn newsletter](https://docs.ansible.com/projects/ansible/devel/community/communication.html#the-bullhorn) , which is used to announce releases and important changes, can also be found here. For more information on the forum navigation, see the [Navigating the Ansible forum](https://forum.ansible.com/t/navigating-the-ansible-forum-tags-categories-and-concepts/39) post. Matrix[¶](https://docs.ansible.com/projects/antsibull-changelog/community/#matrix "Permanent link") ---------------------------------------------------------------------------------------------------- For real-time interactions, join the [#antsibull:ansible.com Matrix room](https://matrix.to/#/#antsibull:ansible.com) . See the [Ansible communication guide](https://docs.ansible.com/projects/ansible/devel/community/communication.html#real-time-chat) for more information on Matrix. --- # Installation - Tox Ansible Documentation [Skip to content](https://docs.ansible.com/projects/tox-ansible/installation/#installation) [](https://github.com/ansible/tox-ansible/blob/main/docs/installation.md "Edit this page") Installation[¶](https://docs.ansible.com/projects/tox-ansible/installation/#installation "Permanent link") =========================================================================================================== > Need help or want to discuss the project? See our [Contributor guide](https://ansible.readthedocs.io/projects/tox-ansible/contributor_guide/#talk-to-us) > to join the conversation! Getting started with tox-ansible is as simple as: `[](https://docs.ansible.com/projects/tox-ansible/installation/#__codelineno-0-1) pip install tox-ansible` Dependencies[¶](https://docs.ansible.com/projects/tox-ansible/installation/#dependencies "Permanent link") ----------------------------------------------------------------------------------------------------------- `tox-ansible` will install additional dependencies if necessary: * `tox` version 4.0 or greater. * `pytest-ansible` version 3.1.0 or greater. * `pytest` * `pytest-xdist` * `pyyaml` Each generated test environment will also install: * `ansible-dev-environment` (ade) -- handles collection installation, ansible-core versioning, and Python dependency resolution. --- # Configuration - Tox Ansible Documentation [Skip to content](https://docs.ansible.com/projects/tox-ansible/configuration/#configuration) [](https://github.com/ansible/tox-ansible/blob/main/docs/configuration.md "Edit this page") Configuration[¶](https://docs.ansible.com/projects/tox-ansible/configuration/#configuration "Permanent link") ============================================================================================================== `tox-ansible` should be configured using a `tox-ansible.ini` file. Using a `tox-ansible.ini` file allows for the introduction of the `tox-ansible` plugin to a repository that may already have an existing `tox` configuration without conflicts. If no configuration overrides are needed, the `tox-ansible.ini` file may be empty but should be present. In addition to all `tox` supported keywords the `ansible` section and `skip` keyword are available: `[](https://docs.ansible.com/projects/tox-ansible/configuration/#__codelineno-0-1) # tox-ansible.ini [](https://docs.ansible.com/projects/tox-ansible/configuration/#__codelineno-0-2) [ansible] [](https://docs.ansible.com/projects/tox-ansible/configuration/#__codelineno-0-3) skip = [](https://docs.ansible.com/projects/tox-ansible/configuration/#__codelineno-0-4) 2.9 [](https://docs.ansible.com/projects/tox-ansible/configuration/#__codelineno-0-5) devel` This will skip tests in any environment that uses Ansible 2.9 or the devel branch. The list of strings is used for a simple string in string comparison of environment names. ### Overriding the configuration[¶](https://docs.ansible.com/projects/tox-ansible/configuration/#overriding-the-configuration "Permanent link") Any configuration in either the `[testenv]` section or an environment section `[testenv:integration-py3.12-{devel,milestone}]` can override some or all of the `tox-ansible` environment configurations. For example `[](https://docs.ansible.com/projects/tox-ansible/configuration/#__codelineno-1-1) [testenv] [](https://docs.ansible.com/projects/tox-ansible/configuration/#__codelineno-1-2) commands_pre = [](https://docs.ansible.com/projects/tox-ansible/configuration/#__codelineno-1-3) true [](https://docs.ansible.com/projects/tox-ansible/configuration/#__codelineno-1-4) [](https://docs.ansible.com/projects/tox-ansible/configuration/#__codelineno-1-5) [testenv:integration-py3.12-{devel,milestone}] [](https://docs.ansible.com/projects/tox-ansible/configuration/#__codelineno-1-6) commands = [](https://docs.ansible.com/projects/tox-ansible/configuration/#__codelineno-1-7) true` will result in: `[](https://docs.ansible.com/projects/tox-ansible/configuration/#__codelineno-2-1) # tox-ansible.ini [](https://docs.ansible.com/projects/tox-ansible/configuration/#__codelineno-2-2) [testenv:integration-py3.12-devel] [](https://docs.ansible.com/projects/tox-ansible/configuration/#__codelineno-2-3) commands_pre = true [](https://docs.ansible.com/projects/tox-ansible/configuration/#__codelineno-2-4) commands = true` Used without caution, this configuration can result in unexpected behavior, and possible false positive or false negative test results. --- # FAQ - Tox Ansible Documentation [Skip to content](https://docs.ansible.com/projects/tox-ansible/faq/#frequently-asked-questions) [](https://github.com/ansible/tox-ansible/blob/main/docs/faq.md "Edit this page") Frequently asked questions[¶](https://docs.ansible.com/projects/tox-ansible/faq/#frequently-asked-questions "Permanent link") ============================================================================================================================== > Need help or want to discuss the project? See our [Contributor guide](https://ansible.readthedocs.io/projects/tox-ansible/contributor_guide/#talk-to-us) > join the conversation! How does it work?[¶](https://docs.ansible.com/projects/tox-ansible/faq/#how-does-it-work "Permanent link") ----------------------------------------------------------------------------------------------------------- `tox` will, by default, create a Python virtual environment for a given environment. `tox-ansible` adds Ansible collection specific build and test logic to tox by delegating collection installation to [ansible-dev-environment](https://github.com/ansible/ansible-dev-environment) (ade). For each test environment, `tox-ansible` runs `ade install` as a pre-command which: 1. Installs the requested version of `ansible-core` (from PyPI, a GitHub branch, or a URL). 2. Builds and installs the collection from the current directory into the virtual environment's site-packages. 3. Discovers and installs Python dependencies declared by the collection and its transitive dependencies using `ansible-builder introspect`. `tox-ansible` also installs any Python dependencies from a `test-requirements.txt` (or `requirements-test.txt`) and `requirements.txt` file. `tox-ansible` sets the `ANSIBLE_COLLECTIONS_PATH` environment variable to `"."` (the current directory). This prevents ansible-core from scanning system and user collection paths and isolates the collection under test. The collection itself is installed into the virtual environment's site-packages via an editable install (`ade install -e`), so Ansible discovers it through Python's import machinery. The `pytest-ansible` plugin injects the `ANSIBLE_COLLECTIONS_PATH` environment variable into the collection loader so ansible-core can locate the collection. `pytest` is used to run both the `unit` and `integration tests`. `ansible-test sanity` is used to run the `sanity` tests. For more details on the architecture and how `tox-ansible` and `ade` work together, see the [Architecture](https://docs.ansible.com/projects/tox-ansible/architecture/) page. For full configuration examples for each of the sanity, integration, and unit tests including the commands being run and the environment variables being set and passed, see the following: * [integration](https://github.com/ansible/tox-ansible/blob/main/docs/integration.ini) * [sanity](https://github.com/ansible/tox-ansible/blob/main/docs/sanity.ini) * [unit](https://github.com/ansible/tox-ansible/blob/main/docs/unit.ini) See the [tox documentation](https://tox.readthedocs.io/en/latest/) for more information on tox. --- # Automated Ansible Release Process - Ansible Package Release Management [Skip to content](https://docs.ansible.com/projects/ansible-build-data/automated-process/#how-to-release-a-new-version-of-the-ansible-community-package-automated-release-process) How to release a new version of the Ansible Community Package — Automated Release Process[¶](https://docs.ansible.com/projects/ansible-build-data/automated-process/#how-to-release-a-new-version-of-the-ansible-community-package-automated-release-process "Permanent link") =============================================================================================================================================================================================================================================================================== Preamble[¶](https://docs.ansible.com/projects/ansible-build-data/automated-process/#preamble "Permanent link") --------------------------------------------------------------------------------------------------------------- This document describes the (mostly) automated ansible community package release process. The automated processes uses GitHub Actions to automate the [manual release process](https://docs.ansible.com/projects/ansible-build-data/release-process/) . Note Throughout this page, placeholder values in code blocks are formatted as `${PLACEHOLDER_VALUE}` where `PLACEHOLDER_VALUE` describes the value to specify. Setup for the release[¶](https://docs.ansible.com/projects/ansible-build-data/automated-process/#setup-for-the-release "Permanent link") ----------------------------------------------------------------------------------------------------------------------------------------- ### Credentials[¶](https://docs.ansible.com/projects/ansible-build-data/automated-process/#credentials "Permanent link") Note that most of the following items cannot be done by yourself, but need someone from the Ansible community team to assign them to you. You need to earn some trust first before this will happen. * Become a member of the [ansible-build-data](https://github.com/ansible-community/ansible-build-data) repo. * Become member of the Ansible Release Management working group on Github. * For making the announcements relating to releases, please join the following Matrix rooms: * [`#release-management:ansible.com`](https://matrix.to/#/#release-management:ansible.com) * [`#community:ansible.com`](https://matrix.to/#/#community:ansible.com) * [`#packaging:ansible.com`](https://matrix.to/#/#packaging:ansible.com) * [`#social:ansible.com`](https://matrix.to/#/#social:ansible.com) (mention `@newsbot`) * Join Release Management Working Group in [Ansible Forum](https://forum.ansible.com/g/release-managers) . ### Read about the following[¶](https://docs.ansible.com/projects/ansible-build-data/automated-process/#read-about-the-following "Permanent link") * [Trusted Publisher in PyPI](https://docs.pypi.org/trusted-publishers/) . * [Examine the GitHub Actions release workflow](https://github.com/ansible-community/ansible-build-data/blob/main/.github/workflows/ansible-release.yml) . * [Talk on Using Trusted Publishing to Ansible release](https://docs.pypi.org/trusted-publishers/) * Ask and show intention to be the Release Manager in the release-management working group. * Shadow the release manager for 2 releases. * [Release Roadmap](https://docs.ansible.com/projects/ansible/devel/roadmap) ### Process summary[¶](https://docs.ansible.com/projects/ansible-build-data/automated-process/#process-summary "Permanent link") * Communicate with the Community about the start and the progress on the [#release-management:ansible.com Matrix channel](https://matrix.to/#/#release-management:ansible.com) . * Follow the release workflow as mentioned below. Trigger the workflow[¶](https://docs.ansible.com/projects/ansible-build-data/automated-process/#trigger-the-workflow "Permanent link") --------------------------------------------------------------------------------------------------------------------------------------- 1. Trigger [the automated workflow](https://github.com/ansible-community/ansible-build-data/actions/workflows/ansible-release.yml) on the **Actions** tab of the repository. This workflow has multiple inputs. The most important is the release version, such as `11.2.0` or `12.0.0rc1`. This always has to be specified. The following additional inputs are required for special releases. Generally you do not need to pass them and can rely on their defaults. Cases where you need these inputs are described in the [Special builds](https://docs.ansible.com/projects/ansible-build-data/automated-process/#special-builds) section below. * You can optionally decide whether to preserve existing `.deps` files. The default is to regenerate them. * You can optionally decide whether the `.build` file should be regenerated during alpha and beta-1 releases. * You can also specify an existing branch in the [`ansible-build-data` repository](https://github.com/ansible-community/ansible-build-data/) to create the PR on. The process will create a PR in the [`ansible-build-data` repository](https://github.com/ansible-community/ansible-build-data/) . Afterwards, it will wait for approval before continuing with uploading the package to PyPI. All users in the [ansible-community/release-management-wg group](https://github.com/orgs/ansible-community/teams/release-management-wg) [1](https://docs.ansible.com/projects/ansible-build-data/automated-process/#fn:1) will be informed with a notification once the approval is needed. The notification includes a link to the page where the upload step can be approved. 2. If a porting guide exists in the `ansible-build-data` PR, trigger [the automated workflow](https://github.com/ansible/ansible-documentation/actions/workflows/release-porting-guide.yml) on the **Actions** tab of the `ansible-documentation` repository to create the porting guide PR. This workflow has the following inputs: * **Release Branch name**. Specify the name of the branch from the newly created [ansible-build-data](https://github.com/ansible-community/ansible-build-data/) PR for the release, for example: `refs/pull/576/merge`. This branch refers to the current state of Pull Request #576 in the ansible-build-data repository. You need to adjust the number to the PR's number. * **Exact release version**. Specify a release version such as `11.2.0` or `12.0.0rc1`. * **Use the workflow from** the **Branch: devel** `devel` is selected as the branch by default. Do not edit this while doing the release. This option is there to test the workflow itself. The process will create a PR in the [`ansible-documentation` repository](https://github.com/ansible/ansible-documentation/) .The release manager needs to check the Porting Guide PR and change the status to 'ready to review.' Afterwards, the [ansible-community/release-management-wg group](https://github.com/orgs/ansible-community/teams/release-management-wg) [1](https://docs.ansible.com/projects/ansible-build-data/automated-process/#fn:1) needs to be informed in [the Matrix #release-management room](https://docs.ansible.com/projects/ansible-build-data/automated-process/#release-management:ansible.com) about the PR. (Write a message like this: `There is a [Porting Guide PR](PR url), can someone please go ahead and have a look, review and merge it.`) 3. After both PRs (in `ansible-build-data` and `ansible-documentation`) are approved, merge the `ansible-build-data` PR and approve the next workflow step (**in this order!** the next steps of the workflow require the PR to be merged!). This will upload the package to PyPI and tag the release in `ansible-build-data`. 4. Merge the porting guide PR, and request backports to the latest `stable-x` branches down to the ansible-core version that is included in the Ansible release. Documentation mantainers can add the appropriate backport labels to enable these automatically. 5. Make sure that you have installed [`antsibull-build`](https://pypi.org/project/antsibull-build/) and a supported clipboard library. You can do that like this: `[](https://docs.ansible.com/projects/ansible-build-data/automated-process/#__codelineno-0-1) pip install antsibull-build[clipboard]` 6. Then announce the release on the Forum and Matrix by running the following command in the `${MAJOR_VERSION}` directory of the `ansible-build-data` checkout: `[](https://docs.ansible.com/projects/ansible-build-data/automated-process/#__codelineno-1-1) antsibull-build announcements --send --data-dir . ${VERSION} [ --end-of-life ]` The `--end-of-life` flag should be added if this is the final release for the `${MAJOR_VERSION}` major release train. This will open your default browser to do the announcement on the forum. It will also tell you where to announce this on Matrix, ask for the URL of the forum thread, and create a suitable text in your clipboard that you can copy to Matrix. Special builds[¶](https://docs.ansible.com/projects/ansible-build-data/automated-process/#special-builds "Permanent link") --------------------------------------------------------------------------------------------------------------------------- ### Builds with a specific release summary other than the default one[¶](https://docs.ansible.com/projects/ansible-build-data/automated-process/#builds-with-a-specific-release-summary-other-than-the-default-one "Permanent link") Sometimes you want to use a different release summary than the default one. For example for the Ansible 9.5.1 release, we included some text that explained why the release has version 9.5.1 and not 9.5.0. For this, create a new branch in `ansible-build-data`. Add a `release_summary` changelog entry for the new release to the `changelog.yaml` file in the major version's directory. Make sure to follow the same basic structure of the version's record in `changelog.yaml`. This can look as follows: ``[](https://docs.ansible.com/projects/ansible-build-data/automated-process/#__codelineno-2-1) releases: [](https://docs.ansible.com/projects/ansible-build-data/automated-process/#__codelineno-2-2) ... [](https://docs.ansible.com/projects/ansible-build-data/automated-process/#__codelineno-2-3) 12.3.4: [](https://docs.ansible.com/projects/ansible-build-data/automated-process/#__codelineno-2-4) changes: [](https://docs.ansible.com/projects/ansible-build-data/automated-process/#__codelineno-2-5) release_summary: | [](https://docs.ansible.com/projects/ansible-build-data/automated-process/#__codelineno-2-6) Release Date: 2024-05-14 [](https://docs.ansible.com/projects/ansible-build-data/automated-process/#__codelineno-2-7) [](https://docs.ansible.com/projects/ansible-build-data/automated-process/#__codelineno-2-8) Porting Guide `_ [](https://docs.ansible.com/projects/ansible-build-data/automated-process/#__codelineno-2-9) [](https://docs.ansible.com/projects/ansible-build-data/automated-process/#__codelineno-2-10) This is a special release because of ...`` After that, you can start the automated workflow. You need to set the following option next to the release version: 1. Set `existing-branch` to the branch you pushed to the `ansible-build-data` repository. ### Additional release candidates (rc2 etc.)[¶](https://docs.ansible.com/projects/ansible-build-data/automated-process/#additional-release-candidates-rc2-etc "Permanent link") For these release candidates, you only want to bump very specific collection versions, and not use new bugfix releases of potentially all included collections. For this, create a new branch in `ansible-build-data` where you copy the `.deps` file of the previous release candidate to the location of the `.deps` file of the planned release. Then you modify the new `.deps` file with the version updates you plan to make and update `_ansible_version`. After that, you can start the automated workflow. You need to set the following options next to the release version: 1. Set `preserve-deps` to `true`; 2. Set `existing-branch` to the branch you pushed to the `ansible-build-data` repository. ### New major release (x.0.0)[¶](https://docs.ansible.com/projects/ansible-build-data/automated-process/#new-major-release-x00 "Permanent link") The new major release should include exactly the same dependencies as the last release candidate. For this, create a new branch in `ansible-build-data` where you copy the `.deps` file of the last release candidate to the location of the `.deps` file of the planned major release. Update `_ansible_version` in the new `.deps` file, but don't change it in any other way. After that, you can start the automated workflow. You need to set the following options next to the release version: 1. Set `preserve-deps` to `true`; 2. Set `existing-branch` to the branch you pushed to the `ansible-build-data` repository. When the new major release has been done, remember to prepare the directory for the next major Ansible release. How to do this is described in [Setting up for a new major release](https://docs.ansible.com/projects/ansible-build-data/new-ansible/#setting-up-for-a-new-major-release) . * * * 1. This group is configured as "Required reviewers" for the "Configure pypi" build environment in GitHub Actions of the `ansible-build-data` repository. [↩](https://docs.ansible.com/projects/ansible-build-data/automated-process/#fnref:1 "Jump back to footnote 1 in the text") [↩](https://docs.ansible.com/projects/ansible-build-data/automated-process/#fnref2:1 "Jump back to footnote 1 in the text") --- # Manual Ansible Release Process - Ansible Package Release Management [Skip to content](https://docs.ansible.com/projects/ansible-build-data/release-process/#how-to-release-a-new-version-of-the-ansible-community-package-manual-release-process) How to release a new version of the Ansible Community Package — Manual Release Process[¶](https://docs.ansible.com/projects/ansible-build-data/release-process/#how-to-release-a-new-version-of-the-ansible-community-package-manual-release-process "Permanent link") ======================================================================================================================================================================================================================================================================= Preamble[¶](https://docs.ansible.com/projects/ansible-build-data/release-process/#preamble "Permanent link") ------------------------------------------------------------------------------------------------------------- This document describes the "manual" ansible community package release process. There exists an [automated version of this process](https://docs.ansible.com/projects/ansible-build-data/automated-process/) using GitHub Actions. Note Throughout this page, placeholder values in code blocks are formatted as `${PLACEHOLDER_VALUE}` where `PLACEHOLDER_VALUE` describes the value to fill in. Set up container[¶](https://docs.ansible.com/projects/ansible-build-data/release-process/#set-up-container "Permanent link") ----------------------------------------------------------------------------------------------------------------------------- Release managers may choose to preform the following steps inside a podman or docker container created from the [`docker.io/library/python:3.10`](https://hub.docker.com/_/python) image. Make sure to mount your working directory as a volume so you don't have to set up new repository clones every time. `[](https://docs.ansible.com/projects/ansible-build-data/release-process/#__codelineno-0-1) podman run --name ansible-release -v ${PERSISTENT_DIRECTORY}:/pwd:z -w /pwd -ti docker.io/library/python:3.10 bash` Set up repository clones[¶](https://docs.ansible.com/projects/ansible-build-data/release-process/#set-up-repository-clones "Permanent link") --------------------------------------------------------------------------------------------------------------------------------------------- First, you need to set up ansible-build-data and antsibull-build repository clones. This only needs to be done once. 1. [Fork](https://github.com/ansible-community/ansible-build-data/fork) the [ansible-build-data](https://github.com/ansible-community/ansible-build-data) repository. 2. Checkout the antsibull-build and ansible-documentation repositories and change into antsibull-build. `[](https://docs.ansible.com/projects/ansible-build-data/release-process/#__codelineno-1-1) git clone https://github.com/ansible/ansible-documentation [](https://docs.ansible.com/projects/ansible-build-data/release-process/#__codelineno-1-2) git clone https://github.com/ansible-community/antsibull-build [](https://docs.ansible.com/projects/ansible-build-data/release-process/#__codelineno-1-3) cd antsibull-build` 3. Checkout ansible-build-data and configure your fork. To checkout the repository run `[](https://docs.ansible.com/projects/ansible-build-data/release-process/#__codelineno-2-1) mkdir build [](https://docs.ansible.com/projects/ansible-build-data/release-process/#__codelineno-2-2) cd build [](https://docs.ansible.com/projects/ansible-build-data/release-process/#__codelineno-2-3) git clone https://github.com/ansible-community/ansible-build-data [](https://docs.ansible.com/projects/ansible-build-data/release-process/#__codelineno-2-4) cd ansible-build-data` Then, configure your fork. This guide uses your Github username as the fork remote name. `[](https://docs.ansible.com/projects/ansible-build-data/release-process/#__codelineno-3-1) git remote add ${GH_USERNAME} https://github.com/${GH_USERNAME}/ansible-build-data [](https://docs.ansible.com/projects/ansible-build-data/release-process/#__codelineno-3-2) git fetch ${GH_USERNAME} -v` Perform release process[¶](https://docs.ansible.com/projects/ansible-build-data/release-process/#perform-release-process "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------- 1. Change into the antsibull-build checkout. Make sure you have the `main` branch checked out and run `git pull` to update to the latest commit. 2. Create a clean virtual environment for the release process. `[](https://docs.ansible.com/projects/ansible-build-data/release-process/#__codelineno-4-1) rm -rf release-venv [](https://docs.ansible.com/projects/ansible-build-data/release-process/#__codelineno-4-2) python3 -m venv release-venv [](https://docs.ansible.com/projects/ansible-build-data/release-process/#__codelineno-4-3) . ./release-venv/bin/activate [](https://docs.ansible.com/projects/ansible-build-data/release-process/#__codelineno-4-4) python3 -m pip install -U pip` Install the `antsibull-build`, `ansible-core`, and `twine` python packages, as well as the community.general collection. `[](https://docs.ansible.com/projects/ansible-build-data/release-process/#__codelineno-5-1) python3 -m pip install antsibull-build ansible-core twine [](https://docs.ansible.com/projects/ansible-build-data/release-process/#__codelineno-5-2) ansible-galaxy collection install --force community.general` 3. Run the [ansible release playbook](https://github.com/ansible-community/antsibull-build/blob/main/playbooks/build-single-release.yaml) with the appropriate options. You can see the [argument spec](https://github.com/ansible-community/antsibull-build/blob/main/roles/build-release/meta/argument_specs.yml) for a full breakdown, but this describes the basic usage. `[](https://docs.ansible.com/projects/ansible-build-data/release-process/#__codelineno-6-1) export ANSIBLE_CALLBACK_RESULT_FORMAT=yaml [](https://docs.ansible.com/projects/ansible-build-data/release-process/#__codelineno-6-2) ansible-playbook playbooks/build-single-release.yaml -e antsibull_ansible_version=${VERSION}` Note When building ansible versions greater than 9.0.0a1, `Validate tags file` task failures will fail the release playbook instead of warning and moving on. See [policies.md](https://github.com/gotmax23/ansible-build-data/blob/docs/docs/policies.md#enforcement) for how to proceed if this step fails. 4. Commit the changes and push them to your fork. You can run the following commands to do so `[](https://docs.ansible.com/projects/ansible-build-data/release-process/#__codelineno-7-1) cd build/ansible-build-data [](https://docs.ansible.com/projects/ansible-build-data/release-process/#__codelineno-7-2) git switch -c release-${VERSION} [](https://docs.ansible.com/projects/ansible-build-data/release-process/#__codelineno-7-3) git add ${MAJOR_VERSION}/ [](https://docs.ansible.com/projects/ansible-build-data/release-process/#__codelineno-7-4) git commit -m "Ansible ${VERSION}: Dependencies, changelog and porting guide" [](https://docs.ansible.com/projects/ansible-build-data/release-process/#__codelineno-7-5) git push -u ${GH_USERNAME} release-${VERSION}` Then, submit a pull request against ansible-build-data upstream. 5. Submit a PR to ansible/ansible-documentation to add the new porting guide to the docsite. Copy the porting guide to the ansible docsite directory in your ansible checkout with the following command `[](https://docs.ansible.com/projects/ansible-build-data/release-process/#__codelineno-8-1) cp ${MAJOR_VERSION}/porting_guide_${MAJOR_VERSION}.rst ../ansible-documentation/docs/docsite/rst/porting_guides/` switch to the ansible checkout, commit and push the changes, and then submit a PR as you normally would. You can use `Add Ansible community ${VERSION} porting guide` as the commit message. 6. Once the ansible-build-data PR has been merged, publish the build artifacts to PyPI. From the antsibull-build repository root, run `[](https://docs.ansible.com/projects/ansible-build-data/release-process/#__codelineno-9-1) twine upload build/ansible-${VERSION}.tar.gz build/ansible-${VERSION}*.whl` 7. Tag the release commit in the ansible-build-data repository. `[](https://docs.ansible.com/projects/ansible-build-data/release-process/#__codelineno-10-1) cd build/ansible-build-data [](https://docs.ansible.com/projects/ansible-build-data/release-process/#__codelineno-10-2) git switch main [](https://docs.ansible.com/projects/ansible-build-data/release-process/#__codelineno-10-3) git pull [](https://docs.ansible.com/projects/ansible-build-data/release-process/#__codelineno-10-4) git tag ${VERSION} ${MERGED_PR_COMMIT_HASH} -a -m "Ansible ${VERSION}: Changelog, Porting Guide and Dependent Collection Details" [](https://docs.ansible.com/projects/ansible-build-data/release-process/#__codelineno-10-5) git push --follow-tags` 8. Announce the release on the Forum and Matrix by running the following command in the `${MAJOR_VERSION}` directory of the `ansible-build-data` checkout: `[](https://docs.ansible.com/projects/ansible-build-data/release-process/#__codelineno-11-1) antsibull-build announcements --send --data-dir . ${VERSION} [ --end-of-life ]` The `--end-of-life` flag should be added if this is the final release for the `${MAJOR_VERSION}` major release train. This will open your default browser to do the announcement on the forum. It will also tell you where to announce this on Matrix, ask for the URL of the forum thread, and create a suitable text in your clipboard that you can copy to Matrix. --- # home - Ansible Pytest Documentation [Skip to content](https://docs.ansible.com/projects/pytest-ansible/#ansible-pytest-documentation) [](https://github.com/ansible/pytest-ansible/blob/main/docs/index.md "Edit this page") Ansible Pytest Documentation[¶](https://docs.ansible.com/projects/pytest-ansible/#ansible-pytest-documentation "Permanent link") ================================================================================================================================= About Ansible Pytest[¶](https://docs.ansible.com/projects/pytest-ansible/#about-ansible-pytest "Permanent link") ----------------------------------------------------------------------------------------------------------------- The `pytest-ansible` plugin is designed to provide seamless integration between `pytest` and `Ansible`, allowing you to efficiently run and test Ansible-related tasks and scenarios within your pytest test suite. This plugin enhances the testing workflow by offering three distinct pieces of functionality: 1. **Unit Testing for Ansible Collections**: This feature aids in running unit tests for `Ansible collections` using `pytest`. It allows you to validate the behavior of your Ansible `modules` and `roles` in isolation, ensuring that each component functions as expected. 2. **Molecule Scenario Integration**: The plugin assists in running Molecule `scenarios` using `pytest`. This integration streamlines the testing of Ansible roles and playbooks across different environments, making it easier to identify and fix issues across diverse setups. 3. **Ansible Integration for Pytest Tests**: With this functionality, you can seamlessly use `Ansible` from within your `pytest` tests. This opens up possibilities to interact with Ansible components and perform tasks like provisioning resources, testing configurations, and more, all while leveraging the power and flexibility of pytest. --- # Official Ansible docsite - antsibull-docs – Ansible Documentation Build Scripts [Skip to content](https://docs.ansible.com/projects/antsibull-docs/package-docs/#the-official-ansible-docsite) The official Ansible docsite[¶](https://docs.ansible.com/projects/antsibull-docs/package-docs/#the-official-ansible-docsite "Permanent link") ============================================================================================================================================== antsibull-docs is used in the build pipeline of the official Ansible docsites at [docs.ansible.com/projects/ansible/devel](https://docs.ansible.com/projects/ansible/devel/) and [docs.ansible.com/projects/ansible/latest](https://docs.ansible.com/projects/ansible/latest/) to generate the documentation for all collections included in Ansible. It is also used for the [ansible-core documentation](https://docs.ansible.com/projects/ansible-core/devel/) to generate the documentation for `ansible.builtin`, the collection included with ansible-core. The RST sources for all other files of the Ansible docsite can be found in the [ansible/ansible-documentation GitHub repository](https://github.com/ansible/ansible-documentation/) . This repository also contains the docsite build scripts. antsibull-docs is called from [hacking/build\_library/build\_ansible/command\_plugins/docs\_build.py](https://github.com/ansible/ansible-documentation/blob/devel/hacking/build_library/build_ansible/command_plugins/docs_build.py) . This uses the `devel` and `stable` subcommands of antsibull-docs. For its input, data from the [ansible-community/ansible-build-data GitHub repository](https://github.com/ansible-community/ansible-build-data) is used. For building stable docs for a major Ansible version `$X`, the latest `ansible-$X.$Y.$Z.deps` file in the `$X/` directory in `ansible-build-data` is used. For building the `devel` docs, the list of collections is used from the latest `$Y/ansible.in` file in `ansible-build-data` with the largest `$Y` that can be found in the repository. Then the latest version of every collection listed in `$Y/ansible.in` is used. For the exact build process, please refer to the build process in the ansible-documentation repository. --- # antsibull-docs – Ansible Documentation Build Scripts [Skip to content](https://docs.ansible.com/projects/antsibull-docs/#antsibull-docs-building-ansible-documentation) antsibull-docs – Building Ansible documentation[¶](https://docs.ansible.com/projects/antsibull-docs/#antsibull-docs-building-ansible-documentation "Permanent link") ===================================================================================================================================================================== [![Discuss on Matrix at #antsibull:ansible.com](https://img.shields.io/matrix/antsibull:ansible.com.svg?server_fqdn=ansible-accounts.ems.host&label=Discuss%20on%20Matrix%20at%20%23antsibull:ansible.com&logo=matrix)](https://matrix.to/#/#antsibull:ansible.com) [![Discuss on Matrix at #docs:ansible.com](https://img.shields.io/matrix/docs:ansible.com.svg?server_fqdn=ansible-accounts.ems.host&label=Discuss%20on%20Matrix%20at%20%23docs:ansible.com&logo=matrix)](https://matrix.to/#/#docs:ansible.com) This package provides tooling for validating and building Ansible documentation. It mainly consists of a CLI tool, `antsibull-docs`, and a Sphinx extension. The main output format are [reStructured Text (RST)](https://en.wikipedia.org/wiki/ReStructuredText) files for consumption by [Sphinx](https://en.wikipedia.org/wiki/Sphinx_(documentation_generator)) . **Collection maintainers and authors should look at the [Creating a collection docsite](https://docs.ansible.com/projects/antsibull-docs/collection-docs/) section of this docsite.** antsibull-docs is covered by the [Ansible Code of Conduct](https://docs.ansible.com/projects/ansible/latest/community/code_of_conduct.html) . Note Need help or want to discuss the project? See our [Community guide](https://docs.ansible.com/projects/antsibull-docs/community/) to learn how to join the conversation! `antsibull-docs` subcommands[¶](https://docs.ansible.com/projects/antsibull-docs/#antsibull-docs-subcommands "Permanent link") ------------------------------------------------------------------------------------------------------------------------------- The main CLI tool, `antsibull-docs`, has multiple subcommands: * The `devel` and `stable` subcommands are used for building the official Ansible docsites at [docs.ansible.com/projects/ansible/devel](https://docs.ansible.com/projects/ansible/devel/) and [docs.ansible.com/projects/ansible/latest](https://docs.ansible.com/projects/ansible/latest/) . * The `current` and `collection` subcommands are used for building docsites for individual collections. * The `plugin` and `collection-plugins` subcommands are used for rendering documentation for individual (or all) plugins, modules, or roles. * The `lint-collection-docs` and `lint-core-docs` subcommands are used for linting collection and ansible-core documentation. The former is described in more detail in [Creating a collection docsite](https://docs.ansible.com/projects/antsibull-docs/collection-docs/) . * The `sphinx-init` subcommmand is used for setting up a Sphinx-based collection docsite. This is described in more detail in [Creating a collection docsite](https://docs.ansible.com/projects/antsibull-docs/collection-docs/) . * The `ansible-output` subcommmand can render ansible-playbook output directly in RST files. This is described in more detail in [Updating ansible-playbook output in RST files](https://docs.ansible.com/projects/antsibull-docs/ansible-output/) . Using the Sphinx extension[¶](https://docs.ansible.com/projects/antsibull-docs/#using-the-sphinx-extension "Permanent link") ----------------------------------------------------------------------------------------------------------------------------- The `sphinx_antsibull_ext` [Sphinx extension](https://www.sphinx-doc.org/en/master/) provides minimal CSS and several roles used by the written RST files to render the documentation correctly. To use it, include it in your Sphinx configuration `conf.py`: `[](https://docs.ansible.com/projects/antsibull-docs/#__codelineno-0-1) # Add it to 'extensions': [](https://docs.ansible.com/projects/antsibull-docs/#__codelineno-0-2) extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'notfound.extension', 'sphinx_antsibull_ext']` It is possible to configure the color scheme used by the extension using the `antsibull_ext_color_scheme` configuration. Currently, the following values are supported: 1. `default`: the default colors. 2. `default-dark`: a dark color scheme. 3. `default-autodark`: the default colors or the dark colors, depending on a `prefers-color-scheme` media query. 4. `none`: define no colors. You can use this if you want to override all colors by your own definition and thus have no need for the default colors to be included. The default color scheme can be found in [src/sphinx\_antsibull\_ext/css/colors-default.scss](https://github.com/ansible-community/antsibull-docs/blob/main/src/sphinx_antsibull_ext/css/colors-default.scss) . See the [MDN page on using CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) for information on how the color definitions work. Please note that the color scheme only works for HTML output. The colors for LaTeX / PDF output are hardcoded and currently cannot be modified. License[¶](https://docs.ansible.com/projects/antsibull-docs/#license "Permanent link") --------------------------------------------------------------------------------------- Unless otherwise noted in the code, it is licensed under the terms of the GNU General Public License v3 or, at your option, later. See [LICENSES/GPL-3.0-or-later.txt](https://github.com/ansible-community/antsibull-docs/tree/main/LICENSE) for a copy of the license. The repository follows the [REUSE Specification](https://reuse.software/spec/) for declaring copyright and licensing information. The only exception are changelog fragments in `changelog/fragments/`. --- # antsibull-changelog – Ansible Changelog Tool [Skip to content](https://docs.ansible.com/projects/antsibull-changelog/#antsibull-changelog) antsibull-changelog[¶](https://docs.ansible.com/projects/antsibull-changelog/#antsibull-changelog "Permanent link") ==================================================================================================================== [![Discuss on Matrix at #antsibull:ansible.com](https://img.shields.io/matrix/antsibull:ansible.com.svg?server_fqdn=ansible-accounts.ems.host&label=Discuss%20on%20Matrix%20at%20%23antsibull:ansible.com&logo=matrix)](https://matrix.to/#/#antsibull:ansible.com) [![Nox badge](https://github.com/ansible-community/antsibull-changelog/workflows/nox/badge.svg?event=push&branch=main)](https://github.com/ansible-community/antsibull-changelog/actions?query=workflow%3A%22nox%22+branch%3Amain) [![Codecov badge](https://img.shields.io/codecov/c/github/ansible-community/antsibull-changelog)](https://codecov.io/gh/ansible-community/antsibull-changelog) A changelog generator used by ansible-core and Ansible collections. * Using the [`antsibull-changelog` CLI tool for collections](https://docs.ansible.com/projects/antsibull-changelog/changelogs/) . * Using the [`antsibull-changelog` CLI tool for other projects](https://docs.ansible.com/projects/antsibull-changelog/other-projects/) . * Documentation on the [`changelogs/config.yaml` configuration file for `antsibull-changelog`](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/) . * Documentation on the [`changelog.yaml` format](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/) . antsibull-changelog is covered by the [Ansible Code of Conduct](https://docs.ansible.com/projects/ansible/latest/community/code_of_conduct.html) . To see how antsibull-changelog changes, please look at the [antsibull-changelog changelog](https://github.com/ansible-community/antsibull-changelog/blob/main/CHANGELOG.md) . Note Need help or want to discuss the project? See our [Community guide](https://docs.ansible.com/projects/antsibull-changelog/community/) to learn how to join the conversation! Installation[¶](https://docs.ansible.com/projects/antsibull-changelog/#installation "Permanent link") ------------------------------------------------------------------------------------------------------ It can be installed with pip: `[](https://docs.ansible.com/projects/antsibull-changelog/#__codelineno-0-1) pip install antsibull-changelog` For python projects, `antsibull-changelog release` can retrieve the current version from `pyproject.toml`. You can install the project with `[](https://docs.ansible.com/projects/antsibull-changelog/#__codelineno-1-1) pip install antsibull-changelog[toml]` to pull in the necessary toml parser for this feature. The `toml` extra is always available, but it is noop on Python >= 3.11, as `tomllib` is part of the standard library. For more information, see the [documentation](https://docs.ansible.com/projects/antsibull-changelog/changelogs/) . License[¶](https://docs.ansible.com/projects/antsibull-changelog/#license "Permanent link") -------------------------------------------------------------------------------------------- Unless otherwise noted in the code, it is licensed under the terms of the GNU General Public License v3 or, at your option, later. See [LICENSES/GPL-3.0-or-later.txt](https://github.com/ansible-community/antsibull-changelog/tree/main/LICENSE) for a copy of the license. The repository follows the [REUSE Specification](https://reuse.software/spec/) for declaring copyright and licensing information. The only exception are changelog fragments in `changelog/fragments/`. --- # Maintainers | Ansible documentation | Ansible documentation Join us at [Red Hat Summit in Atlanta](https://www.redhat.com/en/summit?sc_id=RHCTE0250000464461) to learn about Ansible Automation Platform | May 11-14, 2026 Maintainers ----------- Ansible community maintainers are trusted contributors who oversee project lifecycle and overall health. Top links for maintainers ------------------------- [News for maintainers](https://forum.ansible.com/tag/news-for-maintainers) [Community topics](https://docs.ansible.com/ansible/devel/community/communication.html#ansible-community-topics) [Package inclusion requests](https://docs.ansible.com/ansible/devel/community/steering/community_steering_committee.html#collection-inclusion-requests-workflow) * * * ### Learn about community maintainer responsibilities [Review community maintainer responsibilities](https://docs.ansible.com/ansible/latest/community/maintainers_guidelines.html) [Backport merged pull requests to stable branches](https://docs.ansible.com/ansible/latest/community/maintainers_workflow.html#backporting) [Regularly release stable versions](https://docs.ansible.com/ansible/latest/community/collection_contributors/collection_releasing.html#releasing) [Look after collection documentation](https://docs.ansible.com/ansible/latest/community/maintainers_guidelines.html#maintaining-good-collection-documentation) ### Expand community around a collection [Explore ways to grow community](https://docs.ansible.com/ansible/latest/community/maintainers_guidelines.html#expanding-the-collection-community) [Maintain good contributor documentation](https://docs.ansible.com/ansible/latest/community/maintainers_guidelines.html#maintaining-good-collection-documentation) [Understand Ansible contributor paths](https://docs.ansible.com/ansible/latest/community/contributor_path.html) ### Get collections included in the Ansible package [Understand the inclusion process](https://docs.ansible.com/ansible/devel/community/steering/community_steering_committee.html#collection-inclusion-requests-workflow) [Review other inclusion requests](https://github.com/ansible-collections/ansible-inclusion/blob/main/README.md#review-process) [Submit your collection for inclusion](https://github.com/ansible-collections/ansible-inclusion/blob/main/README.md#submission-process) ### Participate in cross-project governance [Discuss and vote on community topics](https://docs.ansible.com/ansible/devel/community/communication.html#ansible-community-topics) [Join the Ansible community steering committee](https://docs.ansible.com/ansible/latest/community/contributor_path.html#become-a-steering-committee-member) * [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) * [Privacy policy](https://www.redhat.com/en/about/privacy-policy) * [Code of conduct](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html) Sponsored by [![Red Hat logo.](https://docs.ansible.com/assets/images/redhat_reversed.svg)](https://www.redhat.com/en/technologies/management/ansible?sc_id=RHCTE0250000464439) --- # Installing Ansible Runner — Ansible Runner Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/runner/en/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Runner Documentation](https://docs.ansible.com/projects/runner/en/stable/) * [](https://docs.ansible.com/projects/runner/en/latest/) * Installing Ansible Runner * [View page source](https://docs.ansible.com/projects/runner/en/latest/_sources/install.rst.txt) * * * Installing Ansible Runner[](https://docs.ansible.com/projects/runner/en/latest/install/#installing-ansible-runner "Link to this heading") =========================================================================================================================================== Ansible Runner requires Python >= 3.10 and is provided from several different locations depending on how you want to use it. Using pip[](https://docs.ansible.com/projects/runner/en/latest/install/#using-pip "Link to this heading") ----------------------------------------------------------------------------------------------------------- To install the latest version from the Python Package Index: $ pip install ansible-runner Fedora[](https://docs.ansible.com/projects/runner/en/latest/install/#fedora "Link to this heading") ----------------------------------------------------------------------------------------------------- To install from the Fedora repositories: $ dnf install python3-ansible-runner From source[](https://docs.ansible.com/projects/runner/en/latest/install/#from-source "Link to this heading") --------------------------------------------------------------------------------------------------------------- Check out the source code from [github](https://github.com/ansible/ansible-runner) : $ git clone git://github.com/ansible/ansible-runner Or download from the [releases page](https://github.com/ansible/ansible-runner/releases) Create a virtual environment using Python and activate it: $ virtualenv env $ source env/bin/activate Then install: $ cd ansible-runner $ pip install -e . Build the distribution[](https://docs.ansible.com/projects/runner/en/latest/install/#build-the-distribution "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------- To produce both wheel and sdist: $ python3 -m pip install build $ python3 -m build To only produce an installable `wheel`: $ python3 -m build --wheel To produce a distribution tarball: $ python3 -m build --sdist --- # Community — Ansible Runner Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/runner/en/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Runner Documentation](https://docs.ansible.com/projects/runner/en/stable/) * [](https://docs.ansible.com/projects/runner/en/latest/) * Community * [View page source](https://docs.ansible.com/projects/runner/en/latest/_sources/community.rst.txt) * * * Community[](https://docs.ansible.com/projects/runner/en/latest/community/#community "Link to this heading") ============================================================================================================= We welcome your feedback, questions and ideas. Here’s how to reach the community. Code of Conduct[](https://docs.ansible.com/projects/runner/en/latest/community/#code-of-conduct "Link to this heading") ------------------------------------------------------------------------------------------------------------------------- All communication and interactions in the Ansible community are governed by the [Ansible code of conduct](https://docs.ansible.com/projects/ansible/devel/community/code_of_conduct.html) . Please read and abide by it! Reach out to our community team at [codeofconduct@ansible.com](mailto:codeofconduct%40ansible.com) if you have any questions or need assistance. Ansible Forum[](https://docs.ansible.com/projects/runner/en/latest/community/#ansible-forum "Link to this heading") --------------------------------------------------------------------------------------------------------------------- Join the [Ansible Forum](https://forum.ansible.com/) , the default communication platform for questions and help, development discussions, events, and much more. [Register](https://forum.ansible.com/signup?) to join the community. Search by categories and tags to find interesting topics or start a new one; subscribe only to topics you need! * [Get Help](https://forum.ansible.com/c/help/6) : get help or help others. Please add appropriate tags if you start new discussions, for example `ansible-runner`, `playbook`, and `awx`. * [Posts tagged with ‘ansible-runner’](https://forum.ansible.com/tag/ansible-runner) : subscribe to participate in project-related conversations. * [Bullhorn newsletter](https://docs.ansible.com/projects/ansible/devel/community/communication.html#the-bullhorn) : used to announce releases and important changes. * [Social Spaces](https://forum.ansible.com/c/chat/4) : gather and interact with fellow enthusiasts. * [News & Announcements](https://forum.ansible.com/c/news/5) : track project-wide announcements including social events. See [Navigating the Ansible forum](https://forum.ansible.com/t/navigating-the-ansible-forum-tags-categories-and-concepts/39) for some practical advice on finding your way around. Source Code[](https://docs.ansible.com/projects/runner/en/latest/community/#source-code "Link to this heading") ----------------------------------------------------------------------------------------------------------------- The ansible-runner source code is hosted on GitHub. Contributions, bug reports, and feature requests are welcome! * [GitHub Repository](https://github.com/ansible/ansible-runner) : Browse the source code, open issues, or submit pull requests. --- # Ansible Navigator Documentation [](https://github.com/ansible/ansible-navigator/blob/main/docs/index.md "Edit this page") Ansible Navigator Documentation[¶](https://docs.ansible.com/projects/navigator/#ansible-navigator-documentation "Permanent link") ================================================================================================================================== `ansible-navigator` is a command-line tool and a text-based user interface (TUI) for creating, reviewing, running and troubleshooting Ansible content, including inventories, playbooks, collections, documentation and container images (execution environments). A demo of the interface can be found [on YouTube](https://www.youtube.com/watch?v=J9PBKi8ydi4) . To learn how to easily start leveraging the container technology with `ansible-navigator`, see the [Getting started with Execution Environments guide](https://docs.ansible.com/ansible/devel/getting_started_ee/index.html) . * [Installation](https://docs.ansible.com/projects/navigator/installation/) * [Settings](https://docs.ansible.com/projects/navigator/settings/) * [Subcommands](https://docs.ansible.com/projects/navigator/subcommands/) * [FAQ](https://docs.ansible.com/projects/navigator/faq/) Contributions * [Code Of Conduct](https://docs.ansible.com/projects/navigator/contributing/community/) * [Security](https://docs.ansible.com/projects/navigator/contributing/security/) * [Guidelines](https://docs.ansible.com/projects/navigator/contributing/guidelines/) --- # Introduction to Ansible Builder — Ansible Builder Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/builder/en/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Builder Documentation](https://docs.ansible.com/projects/builder/en/latest/) * [](https://docs.ansible.com/projects/builder/en/latest/#) * Introduction to Ansible Builder * [View page source](https://docs.ansible.com/projects/builder/en/latest/_sources/index.rst.txt) * * * Introduction to Ansible Builder[](https://docs.ansible.com/projects/builder/en/latest/#introduction-to-ansible-builder "Link to this heading") ================================================================================================================================================ With `ansible-builder` you can configure and build portable, consistent, customized Ansible control nodes that are packaged as containers by Podman or Docker. These containers are known as execution environments. You can use them on AWX or Ansible Controller, with Ansible Navigator, for local playbook development and testing, in your CI pipelines, and anywhere else you run automation. You can design and distribute specialized execution environments for your Ansible content, choosing the versions of Python and ansible-core you want, and installing only the Python packages, system packages, and Ansible collections you need for your tasks. Note Need help or want to discuss Ansible Builder including the documentation? See the [Community guide](https://docs.ansible.com/projects/builder/en/latest/community/#community) to learn how to join the conversation! [Container concepts and terms](https://docs.ansible.com/projects/builder/en/latest/#id1) [](https://docs.ansible.com/projects/builder/en/latest/#container-concepts-and-terms "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Ansible Builder depends on more generalized containerization tools like Podman or Docker. Before you start using Ansible Builder, you should understand the following concepts and terms relevant to any use of containers: * **Build instruction file** (called a `Containerfile` in Podman and a `Dockerfile` in Docker): an instruction file for creating a container image by installing and configuring the code and dependencies. * **Container**: a package of code and dependencies that runs a service or an application across a variety of computing environments. * **Image**: a complete but inactive version of a container - you can distribute images and create one or more containers based on each image. [What are execution environments?](https://docs.ansible.com/projects/builder/en/latest/#id2) [](https://docs.ansible.com/projects/builder/en/latest/#what-are-execution-environments "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Refer to the [Getting started with Execution Environments guide](https://docs.ansible.com/projects/ansible/devel/getting_started_ee/index.html) for details. [Quickstart for Ansible Builder](https://docs.ansible.com/projects/builder/en/latest/#id3) [](https://docs.ansible.com/projects/builder/en/latest/#quickstart-for-ansible-builder "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- To get started with Ansible Builder, you must install the `ansible-builder` utility and a containerization tool. Once you have the tools you need, create an [execution environment definition](https://docs.ansible.com/projects/builder/en/latest/definition/#builder-ee-definition) file. By default, this file is called `execution-environment.yml` (the `.yaml` extension is also accepted). In the execution environment definition file, you can specify the exact content you want to include in your execution environment. You can specify these items: * the base container image * the version of Python * the version of ansible-core * the version of ansible-runner * Ansible collections, with version restrictions * system packages, with version restrictions * Python packages, with version restrictions * other items to download, install, or configure [Choosing a base image](https://docs.ansible.com/projects/builder/en/latest/#id4) [](https://docs.ansible.com/projects/builder/en/latest/#choosing-a-base-image "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Ansible Builder requires RPM-based container images that use the `dnf` or `microdnf` package manager. Non-RPM-based distributions (such as Debian, Ubuntu, or Alpine) are not supported and will fail to build. Ansible Builder’s default configuration and internal tooling assume the use of `dnf` package management, which is present on RPM-based Linux distributions. The following are examples of images that should work with Ansible Builder: * **CentOS Stream**: `quay.io/centos/centos:stream9` * **Rocky Linux**: `quay.io/rockylinux/rockylinux:9` * **Fedora**: `registry.fedoraproject.org/fedora:43` * **Red Hat Universal Base Image (UBI)**: `registry.access.redhat.com/ubi9/ubi:latest` * **RHEL-based Ansible Automation Platform images**: `registry.redhat.io/ansible-automation-platform-*/ee-*` The examples above demonstrate compatible images, but any RPM-based image with `dnf` or `microdnf` should work. When choosing a base image, prefer smaller images when possible, as they result in smaller final execution environment images. However, ensure you understand what packages are already installed on the base image to avoid redundant installations. For example, some base images already have Python installed, while others do not. [How Ansible Builder executes](https://docs.ansible.com/projects/builder/en/latest/#id5) [](https://docs.ansible.com/projects/builder/en/latest/#how-ansible-builder-executes "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Ansible Builder can execute two separate steps: * The first step is to create a build instruction file (`Containerfile` for Podman, `Dockerfile` for Docker) and a build context based on the execution environment definition file. * The second step is to run a containerization tool (Podman or Docker) to build an image based on the build instruction file and build context. The `ansible-builder build` command runs both steps. The `ansible-builder create` command runs only the first step. For more details, read through the [CLI usage docs](https://docs.ansible.com/projects/builder/en/latest/usage/#builder-cli) . ### [How Ansible Builder builds images](https://docs.ansible.com/projects/builder/en/latest/#id6) [](https://docs.ansible.com/projects/builder/en/latest/#how-ansible-builder-builds-images "Link to this heading") Ansible Builder executes four stages when it runs your containerization tool to build a container image. The same four stages get executed if you build your container image directly with Podman or Docker, using a build instruction file and context generated by `ansible-builder create`. These stages are: 1. **Base**: uses Podman or Docker to pull the base image you defined, then installs the Python version (if defined and different from any Python on the base image), pip, ansible-runner, and ansible-core or ansible. All three later stages of the build process build on the output of the Base stage. 2. **Galaxy**: downloads the collections you defined from Galaxy and stashes them locally as files. 3. **Builder**: downloads the other packages (Python packages and system packages) you defined and stash them locally as files. 4. **Final**: integrates the first three stages, installing all the stashed files on the output of the Base stage and generating a new image that includes all the content. Ansible Builder injects hooks at each stage of the container build process so you can add custom steps before and after every build stage. You may need to install certain packages or utilities before the Galaxy and Builder stages. For example, if you need to install a collection from GitHub, you must install git after the Base stage to make it available during the Galaxy stage. To add custom build steps, add an `additional_build_steps` section to your execution environment definition. For more details, read through the [CLI usage docs](https://docs.ansible.com/projects/builder/en/latest/usage/#builder-cli) . [Defining collection dependencies](https://docs.ansible.com/projects/builder/en/latest/#id7) [](https://docs.ansible.com/projects/builder/en/latest/#defining-collection-dependencies "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- When Ansible Builder installs collections into an execution environment, it also installs each collection’s dependencies if they are specified. Collection maintainers can learn to correctly declare dependencies for their collections from the [collection-level dependencies](https://docs.ansible.com/projects/builder/en/latest/collection_metadata/#builder-collection-metadata) page. Contents: * [Introduction to Ansible Builder](https://docs.ansible.com/projects/builder/en/latest/#) * [Community](https://docs.ansible.com/projects/builder/en/latest/community/) * [Code of Conduct](https://docs.ansible.com/projects/builder/en/latest/community/#code-of-conduct) * [Ansible Forum](https://docs.ansible.com/projects/builder/en/latest/community/#ansible-forum) * [Installation](https://docs.ansible.com/projects/builder/en/latest/installation/) * [Requirements](https://docs.ansible.com/projects/builder/en/latest/installation/#requirements) * [Base Image Requirements](https://docs.ansible.com/projects/builder/en/latest/installation/#base-image-requirements) * [Install from PyPI](https://docs.ansible.com/projects/builder/en/latest/installation/#install-from-pypi) * [Install from Source](https://docs.ansible.com/projects/builder/en/latest/installation/#install-from-source) * [Execution environment definition](https://docs.ansible.com/projects/builder/en/latest/definition/) * [Overview](https://docs.ansible.com/projects/builder/en/latest/definition/#overview) * [Version 3 sample files](https://docs.ansible.com/projects/builder/en/latest/definition/#version-3-sample-files) * [Configuration options](https://docs.ansible.com/projects/builder/en/latest/definition/#configuration-options) * [additional\_build\_files](https://docs.ansible.com/projects/builder/en/latest/definition/#additional-build-files) * [additional\_build\_steps](https://docs.ansible.com/projects/builder/en/latest/definition/#additional-build-steps) * [build\_arg\_defaults](https://docs.ansible.com/projects/builder/en/latest/definition/#build-arg-defaults) * [dependencies](https://docs.ansible.com/projects/builder/en/latest/definition/#dependencies) * [images](https://docs.ansible.com/projects/builder/en/latest/definition/#images) * [options](https://docs.ansible.com/projects/builder/en/latest/definition/#options) * [version](https://docs.ansible.com/projects/builder/en/latest/definition/#version) * [CLI Usage](https://docs.ansible.com/projects/builder/en/latest/usage/) * [The `build` command](https://docs.ansible.com/projects/builder/en/latest/usage/#the-build-command) * [Flags for the `build` command](https://docs.ansible.com/projects/builder/en/latest/usage/#flags-for-the-build-command) * [`--tag`](https://docs.ansible.com/projects/builder/en/latest/usage/#tag) * [`--file`](https://docs.ansible.com/projects/builder/en/latest/usage/#file) * [`--galaxy-keyring`](https://docs.ansible.com/projects/builder/en/latest/usage/#galaxy-keyring) * [`--galaxy-ignore-signature-status-code`](https://docs.ansible.com/projects/builder/en/latest/usage/#galaxy-ignore-signature-status-code) * [`--galaxy-required-valid-signature-count`](https://docs.ansible.com/projects/builder/en/latest/usage/#galaxy-required-valid-signature-count) * [`--context`](https://docs.ansible.com/projects/builder/en/latest/usage/#context) * [`--build-arg`](https://docs.ansible.com/projects/builder/en/latest/usage/#build-arg) * [`--container-runtime`](https://docs.ansible.com/projects/builder/en/latest/usage/#container-runtime) * [`--container-policy`](https://docs.ansible.com/projects/builder/en/latest/usage/#container-policy) * [`--container-keyring`](https://docs.ansible.com/projects/builder/en/latest/usage/#container-keyring) * [`--extra-build-cli-args`](https://docs.ansible.com/projects/builder/en/latest/usage/#extra-build-cli-args) * [`--verbosity`](https://docs.ansible.com/projects/builder/en/latest/usage/#verbosity) * [`--prune-images`](https://docs.ansible.com/projects/builder/en/latest/usage/#prune-images) * [`--squash`](https://docs.ansible.com/projects/builder/en/latest/usage/#squash) * [The `create` command](https://docs.ansible.com/projects/builder/en/latest/usage/#the-create-command) * [The `introspect` command](https://docs.ansible.com/projects/builder/en/latest/usage/#the-introspect-command) * [Flags for the `introspect` command](https://docs.ansible.com/projects/builder/en/latest/usage/#flags-for-the-introspect-command) * [`folder`](https://docs.ansible.com/projects/builder/en/latest/usage/#folder) * [`--write-pip`](https://docs.ansible.com/projects/builder/en/latest/usage/#write-pip) * [`--write-bindep`](https://docs.ansible.com/projects/builder/en/latest/usage/#write-bindep) * [`--user-pip`](https://docs.ansible.com/projects/builder/en/latest/usage/#user-pip) * [`--user-bindep`](https://docs.ansible.com/projects/builder/en/latest/usage/#user-bindep) * [`--exclude-pip-reqs`](https://docs.ansible.com/projects/builder/en/latest/usage/#exclude-pip-reqs) * [`--exclude-bindep-reqs`](https://docs.ansible.com/projects/builder/en/latest/usage/#exclude-bindep-reqs) * [`--exclude-collection-reqs`](https://docs.ansible.com/projects/builder/en/latest/usage/#exclude-collection-reqs) * [Examples](https://docs.ansible.com/projects/builder/en/latest/usage/#examples) * [Deprecated Features](https://docs.ansible.com/projects/builder/en/latest/usage/#deprecated-features) * [Collection-level dependencies](https://docs.ansible.com/projects/builder/en/latest/collection_metadata/) * [Dependency introspection](https://docs.ansible.com/projects/builder/en/latest/collection_metadata/#dependency-introspection) * [How to verify collection-level metadata](https://docs.ansible.com/projects/builder/en/latest/collection_metadata/#how-to-verify-collection-level-metadata) * [When installing collections using ansible-galaxy](https://docs.ansible.com/projects/builder/en/latest/collection_metadata/#when-installing-collections-using-ansible-galaxy) * [When installing collections manually](https://docs.ansible.com/projects/builder/en/latest/collection_metadata/#when-installing-collections-manually) * [Python Dependencies](https://docs.ansible.com/projects/builder/en/latest/collection_metadata/#python-dependencies) * [System-level Dependencies](https://docs.ansible.com/projects/builder/en/latest/collection_metadata/#system-level-dependencies) * [Ansible Builder Porting Guides](https://docs.ansible.com/projects/builder/en/latest/porting_guides/porting_guide/) * [Ansible Builder 3.2 Porting Guide](https://docs.ansible.com/projects/builder/en/latest/porting_guides/porting_guide_v3.2/) * [New Features](https://docs.ansible.com/projects/builder/en/latest/porting_guides/porting_guide_v3.2/#new-features) * [Behavior Changes](https://docs.ansible.com/projects/builder/en/latest/porting_guides/porting_guide_v3.2/#behavior-changes) * [Deprecations](https://docs.ansible.com/projects/builder/en/latest/porting_guides/porting_guide_v3.2/#deprecations) * [Ansible Builder 3.1 Porting Guide](https://docs.ansible.com/projects/builder/en/latest/porting_guides/porting_guide_v3.1/) * [Python Requirements Handling](https://docs.ansible.com/projects/builder/en/latest/porting_guides/porting_guide_v3.1/#python-requirements-handling) * [Common Issues](https://docs.ansible.com/projects/builder/en/latest/porting_guides/porting_guide_v3.1/#common-issues) * [Ansible Builder 3.0 Porting Guide](https://docs.ansible.com/projects/builder/en/latest/porting_guides/porting_guide_v3.0/) * [Overview](https://docs.ansible.com/projects/builder/en/latest/porting_guides/porting_guide_v3.0/#overview) * [Porting options](https://docs.ansible.com/projects/builder/en/latest/porting_guides/porting_guide_v3.0/#porting-options) * [Glossary](https://docs.ansible.com/projects/builder/en/latest/glossary/) Common Scenarios * [Copying arbitrary files to EE](https://docs.ansible.com/projects/builder/en/latest/scenario_guides/scenario_copy/) * [Building EEs with environment variables](https://docs.ansible.com/projects/builder/en/latest/scenario_guides/scenario_using_env/) * [Building EEs with environment variables for Galaxy configuration](https://docs.ansible.com/projects/builder/en/latest/scenario_guides/scenario_custom/) * [Passing Secrets](https://docs.ansible.com/projects/builder/en/latest/scenario_guides/scenario_secret_passing/) * [Validating Installed Python Dependencies](https://docs.ansible.com/projects/builder/en/latest/scenario_guides/scenario_pip_check/) --- # Community — Ansible Builder Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/builder/en/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Builder Documentation](https://docs.ansible.com/projects/builder/en/latest/) * [](https://docs.ansible.com/projects/builder/en/latest/) * Community * [View page source](https://docs.ansible.com/projects/builder/en/latest/_sources/community.rst.txt) * * * Community[](https://docs.ansible.com/projects/builder/en/latest/community/#community "Link to this heading") ============================================================================================================== We welcome your feedback, questions and ideas. Here’s how to reach the community. Code of Conduct[](https://docs.ansible.com/projects/builder/en/latest/community/#code-of-conduct "Link to this heading") -------------------------------------------------------------------------------------------------------------------------- All communication and interactions in the Ansible Builder community are governed by the [Ansible code of conduct](https://docs.ansible.com/projects/ansible/devel/community/code_of_conduct.html) . Please read and abide by it! Reach out to our community team at [codeofconduct@ansible.com](mailto:codeofconduct%40ansible.com) if you have any questions or need assistance. Ansible Forum[](https://docs.ansible.com/projects/builder/en/latest/community/#ansible-forum "Link to this heading") ---------------------------------------------------------------------------------------------------------------------- Join the [Ansible Forum](https://forum.ansible.com/) , the default communication platform for questions and help, development discussions, events, and much more. [Register](https://forum.ansible.com/signup?) to join the community. Search by categories and tags to find interesting topics or start a new one; subscribe only to topics you need! * [Get Help](https://forum.ansible.com/c/help/6) : get help or help others. Please add appropriate tags if you start new discussions, for example ansible-builder, ee, and documentation. * [Posts tagged with ‘ansible-builder’](https://forum.ansible.com/tag/ansible-builder) : subscribe to participate in project-related conversations. * [Bullhorn newsletter](https://docs.ansible.com/projects/ansible/devel/community/communication.html#the-bullhorn) : used to announce releases and important changes. * [Social Spaces](https://forum.ansible.com/c/chat/4) : gather and interact with fellow enthusiasts. * [News & Announcements](https://forum.ansible.com/c/news/5) : track project-wide announcements including social events. See [Navigating the Ansible forum](https://forum.ansible.com/t/navigating-the-ansible-forum-tags-categories-and-concepts/39) for some practical advice on finding your way around. --- # Ansible AWX Documentation — Ansible AWX community documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/awx/en/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ AWX community documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/awx/en/latest/#) * Ansible AWX Documentation * [View page source](https://docs.ansible.com/projects/awx/en/latest/_sources/index.rst.txt) * * * Ansible AWX Documentation[](https://docs.ansible.com/projects/awx/en/latest/#ansible-awx-documentation "Link to this heading") ================================================================================================================================ Ansible AWX helps teams manage complex multi-tier deployments by adding control, knowledge, and delegation to Ansible-powered environments. Welcome * [Release Notes](https://docs.ansible.com/projects/awx/en/latest/relnotes.html) * [Known Issues](https://docs.ansible.com/projects/awx/en/latest/relnotes.html#known-issues) * [Job slicing and limit interactions](https://docs.ansible.com/projects/awx/en/latest/relnotes.html#job-slicing-and-limit-interactions) * [Misuse of job slicing can cause errors in job scheduling](https://docs.ansible.com/projects/awx/en/latest/relnotes.html#misuse-of-job-slicing-can-cause-errors-in-job-scheduling) Community * [AWX Contributor’s Guide](https://docs.ansible.com/projects/awx/en/latest/contributor/index.html) * [1\. Introduction](https://docs.ansible.com/projects/awx/en/latest/contributor/intro.html) * [2\. Communication](https://docs.ansible.com/projects/awx/en/latest/contributor/communication.html) * [3\. Setting up your development environment](https://docs.ansible.com/projects/awx/en/latest/contributor/setting_up.html) * [4\. What should I work on?](https://docs.ansible.com/projects/awx/en/latest/contributor/work_items.html) * [5\. Reporting Issues](https://docs.ansible.com/projects/awx/en/latest/contributor/report_issues.html) * [Django Development Requirements](https://docs.ansible.com/projects/awx/en/latest/contributor/DJANGO_REQUIREMENTS.html) * [1\. Project Structure](https://docs.ansible.com/projects/awx/en/latest/contributor/DJANGO_REQUIREMENTS.html#project-structure) * [2\. Settings Management](https://docs.ansible.com/projects/awx/en/latest/contributor/DJANGO_REQUIREMENTS.html#settings-management) * [3\. URL Patterns and Routing](https://docs.ansible.com/projects/awx/en/latest/contributor/DJANGO_REQUIREMENTS.html#url-patterns-and-routing) * [4\. Model Design](https://docs.ansible.com/projects/awx/en/latest/contributor/DJANGO_REQUIREMENTS.html#model-design) * [5\. REST API Development](https://docs.ansible.com/projects/awx/en/latest/contributor/DJANGO_REQUIREMENTS.html#rest-api-development) * [6\. Security Requirements](https://docs.ansible.com/projects/awx/en/latest/contributor/DJANGO_REQUIREMENTS.html#security-requirements) * [7\. Database Management](https://docs.ansible.com/projects/awx/en/latest/contributor/DJANGO_REQUIREMENTS.html#database-management) * [8\. Testing Standards](https://docs.ansible.com/projects/awx/en/latest/contributor/DJANGO_REQUIREMENTS.html#testing-standards) * [9\. Application Configuration](https://docs.ansible.com/projects/awx/en/latest/contributor/DJANGO_REQUIREMENTS.html#application-configuration) * [10\. Middleware Implementation](https://docs.ansible.com/projects/awx/en/latest/contributor/DJANGO_REQUIREMENTS.html#middleware-implementation) * [11\. Deployment Patterns](https://docs.ansible.com/projects/awx/en/latest/contributor/DJANGO_REQUIREMENTS.html#deployment-patterns) * [Compliance Checklist](https://docs.ansible.com/projects/awx/en/latest/contributor/DJANGO_REQUIREMENTS.html#compliance-checklist) * [References](https://docs.ansible.com/projects/awx/en/latest/contributor/DJANGO_REQUIREMENTS.html#references) * [API Development Requirements](https://docs.ansible.com/projects/awx/en/latest/contributor/API_REQUIREMENTS.html) * [1\. API Architecture and Configuration](https://docs.ansible.com/projects/awx/en/latest/contributor/API_REQUIREMENTS.html#api-architecture-and-configuration) * [2\. REST API Design Standards](https://docs.ansible.com/projects/awx/en/latest/contributor/API_REQUIREMENTS.html#rest-api-design-standards) * [3\. Authentication and Authorization](https://docs.ansible.com/projects/awx/en/latest/contributor/API_REQUIREMENTS.html#authentication-and-authorization) * [4\. Serialization and Data Validation](https://docs.ansible.com/projects/awx/en/latest/contributor/API_REQUIREMENTS.html#serialization-and-data-validation) * [5\. Performance and Optimization](https://docs.ansible.com/projects/awx/en/latest/contributor/API_REQUIREMENTS.html#performance-and-optimization) * [6\. Error Handling and Status Codes](https://docs.ansible.com/projects/awx/en/latest/contributor/API_REQUIREMENTS.html#error-handling-and-status-codes) * [7\. API Documentation and Discovery](https://docs.ansible.com/projects/awx/en/latest/contributor/API_REQUIREMENTS.html#api-documentation-and-discovery) * [8\. API Versioning Strategy](https://docs.ansible.com/projects/awx/en/latest/contributor/API_REQUIREMENTS.html#api-versioning-strategy) * [9\. Testing Requirements](https://docs.ansible.com/projects/awx/en/latest/contributor/API_REQUIREMENTS.html#testing-requirements) * [10\. Security Requirements](https://docs.ansible.com/projects/awx/en/latest/contributor/API_REQUIREMENTS.html#security-requirements) * [Compliance Checklist](https://docs.ansible.com/projects/awx/en/latest/contributor/API_REQUIREMENTS.html#compliance-checklist) * [References](https://docs.ansible.com/projects/awx/en/latest/contributor/API_REQUIREMENTS.html#references) Developers * [AWX API Reference](https://docs.ansible.com/projects/awx/en/latest/rest_api/index.html) * [AWX API Reference](https://docs.ansible.com/projects/awx/en/latest/rest_api/index.html) * [1\. Tools](https://docs.ansible.com/projects/awx/en/latest/rest_api/tools.html) * [2\. Browsable API](https://docs.ansible.com/projects/awx/en/latest/rest_api/browseable.html) * [3\. Conventions](https://docs.ansible.com/projects/awx/en/latest/rest_api/conventions.html) * [4\. Sorting](https://docs.ansible.com/projects/awx/en/latest/rest_api/sorting.html) * [5\. Searching](https://docs.ansible.com/projects/awx/en/latest/rest_api/searching.html) * [6\. Filtering](https://docs.ansible.com/projects/awx/en/latest/rest_api/filtering.html) * [7\. Pagination](https://docs.ansible.com/projects/awx/en/latest/rest_api/pagination.html) * [8\. Access Resources](https://docs.ansible.com/projects/awx/en/latest/rest_api/access_resources.html) * [9\. Read-only Fields](https://docs.ansible.com/projects/awx/en/latest/rest_api/read_only_fields.html) * [10\. Authentication Methods Using the API](https://docs.ansible.com/projects/awx/en/latest/rest_api/authentication.html) * [11\. The _awx-manage_ Utility](https://docs.ansible.com/projects/awx/en/latest/rest_api/awx-manage.html) * [12\. AWX API Reference Guide](https://docs.ansible.com/projects/awx/en/latest/rest_api/api_ref.html) * [AWX OpenAPI Schema](https://docs.ansible.com/projects/awx/en/latest/open_api/index.html) --- # ansible-navigator subcommands - Ansible Navigator Documentation [Skip to content](https://docs.ansible.com/projects/navigator/subcommands/#available-subcommands) [](https://github.com/ansible/ansible-navigator/blob/main/docs/subcommands.md "Edit this page") ansible-navigator subcommands[¶](https://docs.ansible.com/projects/navigator/subcommands/#ansible-navigator-subcommands "Permanent link") ========================================================================================================================================== Available subcommands[¶](https://docs.ansible.com/projects/navigator/subcommands/#available-subcommands "Permanent link") -------------------------------------------------------------------------------------------------------------------------- builder Build [execution environment](https://ansible.readthedocs.io/en/latest/getting_started_ee/index.html) (container image) CLI Example: `ansible-navigator builder --help` Colon command: `:builder` Version added: `:v2.0` collections Explore available collections CLI Example: `ansible-navigator collections --help` Colon command: `:collections` Version added: `:v1.0` config Explore the current ansible configuration CLI Example: `ansible-navigator config --help` Colon command: `:config` Version added: `:v1.0` doc Review documentation for a module or plugin CLI Example: `ansible-navigator doc --help` Colon command: `:doc` Version added: `:v1.0` exec Run a command within an execution environment CLI Example: `ansible-navigator exec --help` Colon command: `:exec` Version added: `:v2.0` images Explore execution environment images CLI Example: `ansible-navigator images --help` Colon command: `:images` Version added: `:v1.0` inventory Explore an inventory CLI Example: `ansible-navigator inventory --help` Colon command: `:inventory` Version added: `:v1.0` lint Lint a file or directory for common errors and issues CLI Example: `ansible-navigator lint --help` Colon command: `:lint` Version added: `:v2.0` replay Explore a previous run using a playbook artifact CLI Example: `ansible-navigator replay --help` Colon command: `:replay` Version added: `:v1.0` run Run a playbook CLI Example: `ansible-navigator run --help` Colon command: `:run` Version added: `:v1.0` settings Review the current ansible-navigator settings CLI Example: `ansible-navigator settings --help` Colon command: `:settings` Version added: `:v2.0` welcome Start at the welcome page CLI Example: `ansible-navigator welcome --help` Colon command: `:welcome` Version added: `:v1.0` Mapping ansible-navigator commands to ansible commands[¶](https://docs.ansible.com/projects/navigator/subcommands/#mapping-ansible-navigator-commands-to-ansible-commands "Permanent link") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Some ansible-navigator commands map to ansible commands. The list below provides some examples. ### `ansible`[¶](https://docs.ansible.com/projects/navigator/subcommands/#ansible "Permanent link") Use `ansible-navigator exec -- ansible` from shell. The exec subcommand requires execution environment support. ### `ansible-builder`[¶](https://docs.ansible.com/projects/navigator/subcommands/#ansible-builder "Permanent link") Use `ansible-navigator builder` from shell.`ansible-builder` is installed with `ansible-navigator` ### `ansible-config`[¶](https://docs.ansible.com/projects/navigator/subcommands/#ansible-config "Permanent link") Use `ansible-navigator config` from shell, or `:config` from the `ansible-navigator` prompt. ### `ansible-doc`[¶](https://docs.ansible.com/projects/navigator/subcommands/#ansible-doc "Permanent link") Use `ansible-navigator doc` from shell, or `:doc` from the `ansible-navigator` prompt. ### `ansible-inventory`[¶](https://docs.ansible.com/projects/navigator/subcommands/#ansible-inventory "Permanent link") Use `ansible-navigator inventory` from shell, or `:inventory` from the `ansible-navigator` prompt. ### `ansible-galaxy`[¶](https://docs.ansible.com/projects/navigator/subcommands/#ansible-galaxy "Permanent link") Use `ansible-navigator exec -- ansible-galaxy ...` from shell. The exec subcommand requires execution environment support. ### `ansible-lint`[¶](https://docs.ansible.com/projects/navigator/subcommands/#ansible-lint "Permanent link") Use `ansible-navigator lint` from shell, or `:lint` from the `ansible-navigator` prompt. `ansible-lint` needs to be installed locally or in the selected execution-environment. ### `ansible-playbook`[¶](https://docs.ansible.com/projects/navigator/subcommands/#ansible-playbook "Permanent link") Use `ansible-navigator run` from shell or `:run` from the `ansible-navigator` prompt. ### `ansible-test`[¶](https://docs.ansible.com/projects/navigator/subcommands/#ansible-test "Permanent link") Use `ansible-navigator exec -- ansible-test ...` from shell. The `exec` subcommand requires execution environment support. ### `ansible-vault`[¶](https://docs.ansible.com/projects/navigator/subcommands/#ansible-vault "Permanent link") Use `ansible-navigator exec -- ansible-vault ...` from shell. The `exec` subcommand requires execution environment support. --- # Contributor Guide - Tox Ansible Documentation [Skip to content](https://docs.ansible.com/projects/tox-ansible/contributor_guide/#contributor-guide) [](https://github.com/ansible/tox-ansible/blob/main/docs/contributor_guide.md "Edit this page") Contributor Guide[¶](https://docs.ansible.com/projects/tox-ansible/contributor_guide/#contributor-guide "Permanent link") ========================================================================================================================== To contribute to `tox-ansible`, please use pull requests on a branch of your own fork. After [creating your fork on GitHub](https://docs.github.com/en/get-started/quickstart/contributing-to-projects) , you can do: `[](https://docs.ansible.com/projects/tox-ansible/contributor_guide/#__codelineno-0-1) $ git clone --recursive git@github.com:your-name/tox-ansible [](https://docs.ansible.com/projects/tox-ansible/contributor_guide/#__codelineno-0-2) $ cd tox-ansible [](https://docs.ansible.com/projects/tox-ansible/contributor_guide/#__codelineno-0-3) $ git checkout -b your-branch-name [](https://docs.ansible.com/projects/tox-ansible/contributor_guide/#__codelineno-0-4) # DO SOME CODING HERE [](https://docs.ansible.com/projects/tox-ansible/contributor_guide/#__codelineno-0-5) $ git add your new files [](https://docs.ansible.com/projects/tox-ansible/contributor_guide/#__codelineno-0-6) $ git commit -v [](https://docs.ansible.com/projects/tox-ansible/contributor_guide/#__codelineno-0-7) $ git push origin your-branch-name` You will then be able to create a pull request from your commit. Prerequisites: 1. All fixes to core functionality (i.e. anything except docs or examples) should be accompanied by tests that fail prior to your change and succeed afterwards. 2. Before sending a PR, make sure that `tox -e lint` passes. Feel free to raise issues in the repo if you feel unable to contribute a code fix. Possible security bugs should be reported via email to [security@ansible.com](mailto:security@ansible.com) . Talk to us[¶](https://docs.ansible.com/projects/tox-ansible/contributor_guide/#talk-to-us "Permanent link") ------------------------------------------------------------------------------------------------------------ ### Code of Conduct[¶](https://docs.ansible.com/projects/tox-ansible/contributor_guide/#code-of-conduct "Permanent link") Please read and adhere to the [Ansible Community Code of Conduct](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html) in all your interactions with the Ansible community. ### Forum[¶](https://docs.ansible.com/projects/tox-ansible/contributor_guide/#forum "Permanent link") Join the [Ansible Forum](https://forum.ansible.com/) as a single starting point and our default communication platform for questions and help, development discussions, events, and much more. [Register](https://forum.ansible.com/signup?) to join the community. Search by categories and tags to find interesting topics or start a new one; subscribe only to topics you need! * [Get Help](https://forum.ansible.com/c/help/6) : get help or help others. Please add appropriate tags if you start new discussions, for example `devtools`. * [Posts tagged with 'devtools'](https://forum.ansible.com/tag/devtools) : subscribe to participate in project-related conversations. * [Bullhorn newsletter](https://docs.ansible.com/ansible/devel/community/communication.html#the-bullhorn) used to announce releases and important changes. * [Social Spaces](https://forum.ansible.com/c/chat/4) : gather and interact with fellow enthusiasts. * [News & Announcements](https://forum.ansible.com/c/news/5) : track project-wide announcements including social events. See `Navigating the Ansible forum `\_ for some practical advice on finding your way around. ### Matrix[¶](https://docs.ansible.com/projects/tox-ansible/contributor_guide/#matrix "Permanent link") For real-time interactions, conversations in the community happen over the Matrix protocol in the [#devtools:ansible.com](https://matrix.to/#/#devtools:ansible.com) . For more information, see the community-hosted [Matrix FAQ](https://hackmd.io/@ansible-community/community-matrix-faq) . --- # CLI Usage — Ansible Builder Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/builder/en/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Builder Documentation](https://docs.ansible.com/projects/builder/en/latest/) * [](https://docs.ansible.com/projects/builder/en/latest/) * CLI Usage * [View page source](https://docs.ansible.com/projects/builder/en/latest/_sources/usage.rst.txt) * * * CLI Usage[](https://docs.ansible.com/projects/builder/en/latest/usage/#cli-usage "Link to this heading") ========================================================================================================== Ansible Builder can execute two separate steps. The first step is to create a build instruction file (Containerfile for Podman, Dockerfile for Docker) and a build context based on your [definition](https://docs.ansible.com/projects/builder/en/latest/definition/#builder-ee-definition) file. The second step is to run a containerization tool (Podman or Docker) to build an image based on the build instruction file and build context. The `ansible-builder build` command executes both steps, giving you a build instruction file, a build context, and a fully built container image. The `ansible-builder create` command only executes the first step, giving you a build instruction file and a build context. If you use `ansible-builder create`, you can use the resulting build instruction file and build context to build your container images on the platform of your choice. Note Ansible Builder is colorized by default when outputting to a terminal. Color output can be disabled by setting the `NO_COLOR` environment variable to any non-empty value, or by setting the `CLICOLOR` environment variable to `0`. [The `build` command](https://docs.ansible.com/projects/builder/en/latest/usage/#id7) [](https://docs.ansible.com/projects/builder/en/latest/usage/#the-build-command "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The `ansible-builder build` command: * takes an [execution environment definition file](https://docs.ansible.com/projects/builder/en/latest/definition/#builder-ee-definition) as an input, * outputs a build instruction file (Containerfile for Podman, Dockerfile for Docker), * creates a build context necessary for building an execution environment image, * builds the image. By default, it looks for a file named `execution-environment.yml` (or `execution-environment.yaml`) in the current directory. To build an execution environment using the default definition file, run: $ ansible-builder build Running command: podman build -f context/Containerfile -t ansible-execution-env:latest context Complete! The build context can be found at: /path/to/context Ansible Builder produces a ready-to-use container image and preserves the build context, which you can use to rebuild the image at a different time and/or location with the tooling of your choice. [Flags for the `build` command](https://docs.ansible.com/projects/builder/en/latest/usage/#id8) [](https://docs.ansible.com/projects/builder/en/latest/usage/#flags-for-the-build-command "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [`--tag`](https://docs.ansible.com/projects/builder/en/latest/usage/#id9) [](https://docs.ansible.com/projects/builder/en/latest/usage/#tag "Link to this heading") Customizes the tagged name applied to the built image. To create an image with a custom name: $ ansible-builder build --tag=my-custom-ee More recent versions of `ansible-builder` support multiple tags: $ ansible-builder build --tag=tag1 --tag=tag2 ### [`--file`](https://docs.ansible.com/projects/builder/en/latest/usage/#id10) [](https://docs.ansible.com/projects/builder/en/latest/usage/#file "Link to this heading") Specifies the execution environment file. To use a file other than the default: $ ansible-builder build --file=my-ee-def.yml ### [`--galaxy-keyring`](https://docs.ansible.com/projects/builder/en/latest/usage/#id11) [](https://docs.ansible.com/projects/builder/en/latest/usage/#galaxy-keyring "Link to this heading") Specifies a keyring for `ansible-galaxy` to use to verify collection signatures during installation. To verify collection signatures: $ ansible-builder create --galaxy-keyring=/path/to/pubring.kbx $ ansible-builder build --galaxy-keyring=/path/to/pubring.kbx If you do not pass this option, no signature verification is performed. If you do pass this option, but the version of Ansible is too old to support this feature, you will see an error during the image build process. ### [`--galaxy-ignore-signature-status-code`](https://docs.ansible.com/projects/builder/en/latest/usage/#id12) [](https://docs.ansible.com/projects/builder/en/latest/usage/#galaxy-ignore-signature-status-code "Link to this heading") Ignores certain errors that may occur while verifying collections. This option is passed unmodified to `ansible-galaxy` calls. Valid only when `--galaxy-keyring` is also set. See the `ansible-galaxy` documentation for more information. $ ansible-builder create --galaxy-keyring=/path/to/pubring.kbx --galaxy-ignore-signature-status-code 500 $ ansible-builder build --galaxy-keyring=/path/to/pubring.kbx --galaxy-ignore-signature-status-code 500 ### [`--galaxy-required-valid-signature-count`](https://docs.ansible.com/projects/builder/en/latest/usage/#id13) [](https://docs.ansible.com/projects/builder/en/latest/usage/#galaxy-required-valid-signature-count "Link to this heading") Overrides the number of required valid collection signatures. This option is passed unmodified to `ansible-galaxy` calls. Valid only when `--galaxy-keyring` is also set. See the `ansible-galaxy` documentation for more information. $ ansible-builder create --galaxy-keyring=/path/to/pubring.kbx --galaxy-required-valid-signature-count 3 $ ansible-builder build --galaxy-keyring=/path/to/pubring.kbx --galaxy-required-valid-signature-count 3 ### [`--context`](https://docs.ansible.com/projects/builder/en/latest/usage/#id14) [](https://docs.ansible.com/projects/builder/en/latest/usage/#context "Link to this heading") Specifies the directory name for the build context Ansible Builder creates. Default directory name is `context` in the current working directory. To specify another location: $ ansible-builder build --context=/path/to/dir ### [`--build-arg`](https://docs.ansible.com/projects/builder/en/latest/usage/#id15) [](https://docs.ansible.com/projects/builder/en/latest/usage/#build-arg "Link to this heading") Passes build-time arguments to Podman or Docker. Specify these flags or variables the same way you would with `podman build` or `docker build`. By default, the Containerfile / Dockerfile created by Ansible Builder contains a build argument `EE_BASE_IMAGE`, which can be useful for rebuilding execution environments without modifying any files. $ ansible-builder build --build-arg FOO=bar To use different build arguments, you can specify `--build-arg` multiple times: $ ansible-builder build --build-arg FOO=bar --build-arg SIMPLE=sample To use a custom base image: $ ansible-builder build --build-arg EE\_BASE\_IMAGE=registry.example.com/another-ee ### [`--container-runtime`](https://docs.ansible.com/projects/builder/en/latest/usage/#id16) [](https://docs.ansible.com/projects/builder/en/latest/usage/#container-runtime "Link to this heading") Specifies the containerization tool used to build images. Default is Podman. To use Docker: $ ansible-builder build --container-runtime=docker ### [`--container-policy`](https://docs.ansible.com/projects/builder/en/latest/usage/#id17) [](https://docs.ansible.com/projects/builder/en/latest/usage/#container-policy "Link to this heading") Note Added in version 1.2 Specifies the container image validation policy to use. Valid only when [\--container-runtime](https://docs.ansible.com/projects/builder/en/latest/usage/#container-runtime) is `podman`. Valid values are one of: * `ignore_all`: Run podman with generated policy that ignores all signatures. * `system`: Relies on podman’s consumption of system policy/signature with inline keyring paths. No builder-specific overrides are possible. * `signature_required`: Run podman with `--pull-always` and a generated policy that rejects all by default, with generated identity requirements for referenced container images, using an explicitly-provided keyring (specified with the [\--container-keyring](https://docs.ansible.com/projects/builder/en/latest/usage/#container-keyring) CLI option). ### [`--container-keyring`](https://docs.ansible.com/projects/builder/en/latest/usage/#id18) [](https://docs.ansible.com/projects/builder/en/latest/usage/#container-keyring "Link to this heading") Note Added in version 1.2 Specifies the path to a GPG keyring file to use for validating container image signatures. ### [`--extra-build-cli-args`](https://docs.ansible.com/projects/builder/en/latest/usage/#id19) [](https://docs.ansible.com/projects/builder/en/latest/usage/#extra-build-cli-args "Link to this heading") Note Added in version 3.1 This option allows the user to pass any additional command line arguments to the container engine build command (`docker build` or `podman build`). Take care when using this option as there is no attempt to identify or resolve conflicting argument values from this option and arguments normally added by `ansible-builder`. $ ansible-builder build --extra-build-cli-args='--pull --env=MY\_ENV\_VAR' ### [`--verbosity`](https://docs.ansible.com/projects/builder/en/latest/usage/#id20) [](https://docs.ansible.com/projects/builder/en/latest/usage/#verbosity "Link to this heading") Customizes the level of verbosity: $ ansible-builder build --verbosity 2 You may also use `-v` for the shorthand version. You may either specify an integer for the verbosity level, or supply multiples of the option. Individual instances of `-v` will stack. For example, the following are equivalent to setting the verbosity level to `3`: $ ansible-builder build -v 3 $ ansible-builder build -vvv $ ansible-builder build -v -v -v ### [`--prune-images`](https://docs.ansible.com/projects/builder/en/latest/usage/#id21) [](https://docs.ansible.com/projects/builder/en/latest/usage/#prune-images "Link to this heading") Removes unused images created after the build process: $ ansible-builder build --prune-images Note This flag removes all the dangling images on the given machine whether they already existed or were created by `ansible-builder` build process. ### [`--squash`](https://docs.ansible.com/projects/builder/en/latest/usage/#id22) [](https://docs.ansible.com/projects/builder/en/latest/usage/#squash "Link to this heading") Controls the final image layer squashing. Valid values are: * `new`: Squash all of the final image’s new layers into a single new layer (preexisting layers are not squashed). * `all`: Squash all of the final image’s layers, including those inherited from the base image, into a single new layer. * `off`: Turn off layer squashing. This is the default. Note This flag is compatible only with the `podman` runtime and will be ignored for any other runtime. Docker does not support layer squashing; it is considered an experimental feature. [The `create` command](https://docs.ansible.com/projects/builder/en/latest/usage/#id23) [](https://docs.ansible.com/projects/builder/en/latest/usage/#the-create-command "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The `ansible-builder create` command accepts an execution environment definition as an input and outputs the build context necessary for building an execution environment image. However, the `create` command _will not_ build the execution environment image; this is useful for creating just the build context and a `Containerfile` that can then be shared. [The `introspect` command](https://docs.ansible.com/projects/builder/en/latest/usage/#id24) [](https://docs.ansible.com/projects/builder/en/latest/usage/#the-introspect-command "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The `ansible-builder introspect` command loops over collections in a specified folder and returns data about their dependencies. This command is used internally by `ansible-builder` and is exposed here for verification purposes. It is primarily targeted toward collection authors and maintainers who need to understand or validate collection dependencies. To introspect collections in the default location: $ ansible-builder introspect [Flags for the `introspect` command](https://docs.ansible.com/projects/builder/en/latest/usage/#id25) [](https://docs.ansible.com/projects/builder/en/latest/usage/#flags-for-the-introspect-command "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ ### [`folder`](https://docs.ansible.com/projects/builder/en/latest/usage/#id26) [](https://docs.ansible.com/projects/builder/en/latest/usage/#folder "Link to this heading") The Ansible collections path to introspect. This is a positional argument that specifies the location of the collections to analyze. The folder must contain an `ansible_collections` subdirectory. If not supplied, it will default to collections installed in `/usr/share/ansible/collections`. $ ansible-builder introspect /path/to/collections ### [`--write-pip`](https://docs.ansible.com/projects/builder/en/latest/usage/#id27) [](https://docs.ansible.com/projects/builder/en/latest/usage/#write-pip "Link to this heading") Write the combined pip requirements to a file. This option outputs all Python dependencies found across the introspected collections to the specified file. $ ansible-builder introspect --write-pip=requirements.txt /path/to/collections ### [`--write-bindep`](https://docs.ansible.com/projects/builder/en/latest/usage/#id28) [](https://docs.ansible.com/projects/builder/en/latest/usage/#write-bindep "Link to this heading") Write the combined bindep requirements to a file. This option outputs all system-level dependencies found across the introspected collections to the specified file. $ ansible-builder introspect --write-bindep=bindep.txt /path/to/collections ### [`--user-pip`](https://docs.ansible.com/projects/builder/en/latest/usage/#id29) [](https://docs.ansible.com/projects/builder/en/latest/usage/#user-pip "Link to this heading") Specify an additional pip requirements file to combine with collection requirements. This is useful when you have custom Python dependencies that should be included alongside the collection dependencies. $ ansible-builder introspect --user-pip=user-requirements.txt --write-pip=combined.txt /path/to/collections ### [`--user-bindep`](https://docs.ansible.com/projects/builder/en/latest/usage/#id30) [](https://docs.ansible.com/projects/builder/en/latest/usage/#user-bindep "Link to this heading") Specify an additional bindep requirements file to combine with collection requirements. This is useful when you have custom system-level dependencies that should be included alongside the collection dependencies. $ ansible-builder introspect --user-bindep=user-bindep.txt --write-bindep=combined.txt /path/to/collections ### [`--exclude-pip-reqs`](https://docs.ansible.com/projects/builder/en/latest/usage/#id31) [](https://docs.ansible.com/projects/builder/en/latest/usage/#exclude-pip-reqs "Link to this heading") Exclude specific pip requirements listed in a file. Each line in the file should contain one Python package name to exclude from the final output. $ ansible-builder introspect --exclude-pip-reqs=exclude.txt --write-pip=filtered.txt /path/to/collections ### [`--exclude-bindep-reqs`](https://docs.ansible.com/projects/builder/en/latest/usage/#id32) [](https://docs.ansible.com/projects/builder/en/latest/usage/#exclude-bindep-reqs "Link to this heading") Exclude specific bindep requirements listed in a file. Each line in the file should contain one system package name to exclude from the final output. $ ansible-builder introspect --exclude-bindep-reqs=exclude.txt --write-bindep=filtered.txt /path/to/collections ### [`--exclude-collection-reqs`](https://docs.ansible.com/projects/builder/en/latest/usage/#id33) [](https://docs.ansible.com/projects/builder/en/latest/usage/#exclude-collection-reqs "Link to this heading") Exclude all requirements from specific collections listed in a file. Each line in the file should contain one collection name (in the format `namespace.name`) whose requirements should be excluded from the final output. $ ansible-builder introspect --exclude-collection-reqs=collections-to-skip.txt /path/to/collections Note The `introspect` command also supports the `--verbosity` flag, which works the same way as described in the `build` command documentation above. [Examples](https://docs.ansible.com/projects/builder/en/latest/usage/#id34) [](https://docs.ansible.com/projects/builder/en/latest/usage/#examples "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The example in `test/data/pytz` requires the `awx.awx` collection in the execution environment definition. The lookup plugin `awx.awx.schedule_rrule` requires the PyPI `pytz` and another library to work. If `test/data/pytz/execution-environment.yml` file is given to the `ansible-builder build` command, then it will install the collection inside the image, read `requirements.txt` inside of the collection, and then install `pytz` into the image. The image produced can be used inside of an `ansible-runner` project by placing these variables inside the `env/settings` file, inside of the private data directory. \--- container\_image: image-name process\_isolation\_executable: podman \# or docker process\_isolation: true The `awx.awx` collection is a subset of content included in the default AWX execution environment. More details can be found at the [awx-ee](https://github.com/ansible/awx-ee) repository. [Deprecated Features](https://docs.ansible.com/projects/builder/en/latest/usage/#id35) [](https://docs.ansible.com/projects/builder/en/latest/usage/#deprecated-features "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The `--base-image` CLI option has been removed. See the `--build-arg` option for a replacement. --- # Contributing - Ansible Creator Documentation [Skip to content](https://docs.ansible.com/projects/creator/contributing/#contributing-to-ansible-creator) [](https://github.com/ansible/ansible-creator/blob/main/docs/contributing.md "Edit this page") [](https://github.com/ansible/ansible-creator/raw/main/docs/contributing.md "View source of this page") Contributing to ansible-creator[¶](https://docs.ansible.com/projects/creator/contributing/#contributing-to-ansible-creator "Permanent link") ============================================================================================================================================= To actively contribute to the development and enhancement of ansible-creator, your participation is valued. Please use pull requests on a branch of your own fork. After [creating your fork on GitHub](https://docs.github.com/en/get-started/quickstart/contributing-to-projects) , you can do: `[](https://docs.ansible.com/projects/creator/contributing/#__codelineno-0-1) $ git clone --recursive git@github.com:your-name/ansible-creator [](https://docs.ansible.com/projects/creator/contributing/#__codelineno-0-2) $ cd ansible-creator [](https://docs.ansible.com/projects/creator/contributing/#__codelineno-0-3) $ git checkout -b your-branch-name [](https://docs.ansible.com/projects/creator/contributing/#__codelineno-0-4) [](https://docs.ansible.com/projects/creator/contributing/#__codelineno-0-5) # DO SOME CODING HERE [](https://docs.ansible.com/projects/creator/contributing/#__codelineno-0-6) [](https://docs.ansible.com/projects/creator/contributing/#__codelineno-0-7) $ git add your new files [](https://docs.ansible.com/projects/creator/contributing/#__codelineno-0-8) $ git commit -v [](https://docs.ansible.com/projects/creator/contributing/#__codelineno-0-9) $ git push origin your-branch-name` You will then be able to create a pull request from your commit. This will initiate the process of reviewing and merging your contributions. For contributions affecting core functionality (i.e., anything except docs or examples), ensure to include corresponding tests that validate the changes. Even if you're not providing a code fix, your input is valuable—feel free to raise [issues](https://github.com/ansible/ansible-creator/issues) in the repository. Standards[¶](https://docs.ansible.com/projects/creator/contributing/#standards "Permanent link") ------------------------------------------------------------------------------------------------- All pull requests undergo automated tests. To ensure that your changes align with project standards, run checks locally before pushing commits using [tox](https://tox.wiki/en/latest/) . Get in touch[¶](https://docs.ansible.com/projects/creator/contributing/#get-in-touch "Permanent link") ------------------------------------------------------------------------------------------------------- Connect with the ansible-creator community! Join the Ansible forum to ask questions, get help, and interact with us. * [Get Help](https://forum.ansible.com/c/help/6) : get help or help others. Please add appropriate tags if you start new discussions, for example the `ansible-creator` or `devtools` tags. * [Social Spaces](https://forum.ansible.com/c/chat/4) : meet and interact with fellow enthusiasts. * [News & Announcements](https://forum.ansible.com/c/news/5) : track project-wide announcements including social events. To get release announcements and important changes from the community, see the [Bullhorn newsletter](https://docs.ansible.com/ansible/devel/community/communication.html#the-bullhorn) . If you encounter security-related concerns, report them via email to [security@ansible.com](mailto:security@ansible.com) . Code of Conduct[¶](https://docs.ansible.com/projects/creator/contributing/#code-of-conduct "Permanent link") ------------------------------------------------------------------------------------------------------------- As with all Ansible projects, adhere to the [Code of Conduct](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html) to foster a respectful and inclusive collaborative environment. Your contributions, feedback, and engagement are essential to the success of ansible-creator. Back to top --- # Ansible Development Environment Documentation [Skip to content](https://docs.ansible.com/projects/dev-environment/#ansible-development-environment) [](https://github.com/ansible/ansible-dev-environment/blob/main/docs/index.md "Edit this page") Ansible Development Environment[¶](https://docs.ansible.com/projects/dev-environment/#ansible-development-environment "Permanent link") ======================================================================================================================================== A pip-like install for Ansible collections. Communication[¶](https://docs.ansible.com/projects/dev-environment/#communication "Permanent link") ---------------------------------------------------------------------------------------------------- * Join the Ansible forum: * [Get Help](https://forum.ansible.com/c/help/6) : get help or help others. Please add appropriate tags if you start new discussions. * [Social Spaces](https://forum.ansible.com/c/chat/4) : gather and interact with fellow enthusiasts. * [News & Announcements](https://forum.ansible.com/c/news/5) : track project-wide announcements including social events. * [Bullhorn newsletter](https://docs.ansible.com/ansible/devel/community/communication.html#the-bullhorn) : used to announce releases and important changes. For more information about communication, see the [Ansible communication guide](https://docs.ansible.com/ansible/devel/community/communication.html) . Features[¶](https://docs.ansible.com/projects/dev-environment/#features "Permanent link") ------------------------------------------------------------------------------------------ * Promotes an "ephemeral" development approach * Ensures the current development environment is isolated * Install all collection python requirements * Install all collection test requirements * Checks for missing system packages * Symlinks the current collection into the current python interpreter's site-packages * Install all collection collection dependencies into the current python interpreter's site-packages * Uses `uv env` instead of python's venv when available to boost performance. Can be disabled with `SKIP_UV=1` By placing collections into the python site-packages directory they are discoverable by ansible as well as python and pytest. Usage[¶](https://docs.ansible.com/projects/dev-environment/#usage "Permanent link") ------------------------------------------------------------------------------------ ### Setting up a development environment[¶](https://docs.ansible.com/projects/dev-environment/#setting-up-a-development-environment "Permanent link") Recommendation The **recommended** approach to install `ansible-dev-environment` is using the `ansible-dev-tools` package. [Ansible Development Tools](https://docs.ansible.com/projects/dev-tools/) aims to streamline the setup and usage of several tools needed in order to create [Ansible](https://www.ansible.com/) content. It combines critical Ansible development packages into a unified Python package. `[](https://docs.ansible.com/projects/dev-environment/#__codelineno-0-1) # This also installs ansible-core if it is not already installed [](https://docs.ansible.com/projects/dev-environment/#__codelineno-0-2) pip3 install ansible-dev-tools` `[](https://docs.ansible.com/projects/dev-environment/#__codelineno-1-1) pip3 install ansible-dev-environment --user` `[](https://docs.ansible.com/projects/dev-environment/#__codelineno-2-1) $ git clone [](https://docs.ansible.com/projects/dev-environment/#__codelineno-2-2) $ cd [](https://docs.ansible.com/projects/dev-environment/#__codelineno-2-3) $ ade install -e .\[test] --venv .venv [](https://docs.ansible.com/projects/dev-environment/#__codelineno-2-4) INFO: Found collection name: network.interfaces from /home/bthornto/github/network.interfaces/galaxy.yml. [](https://docs.ansible.com/projects/dev-environment/#__codelineno-2-5) INFO: Creating virtual environment: /home/bthornto/github/network.interfaces/venv [](https://docs.ansible.com/projects/dev-environment/#__codelineno-2-6) INFO: Virtual environment: /home/bthornto/github/network.interfaces/venv [](https://docs.ansible.com/projects/dev-environment/#__codelineno-2-7) INFO: Using specified interpreter: /home/bthornto/github/network.interfaces/venv/bin/python [](https://docs.ansible.com/projects/dev-environment/#__codelineno-2-8) INFO: Requirements file /home/bthornto/github/network.interfaces/requirements.txt is empty, skipping [](https://docs.ansible.com/projects/dev-environment/#__codelineno-2-9) INFO: Installing python requirements from /home/bthornto/github/network.interfaces/test-requirements.txt [](https://docs.ansible.com/projects/dev-environment/#__codelineno-2-10) INFO: Installing ansible-core. [](https://docs.ansible.com/projects/dev-environment/#__codelineno-2-11) INFO: Initializing build directory: /home/bthornto/github/network.interfaces/build [](https://docs.ansible.com/projects/dev-environment/#__codelineno-2-12) INFO: Copying collection to build directory using git ls-files. [](https://docs.ansible.com/projects/dev-environment/#__codelineno-2-13) INFO: Running ansible-galaxy to build collection. [](https://docs.ansible.com/projects/dev-environment/#__codelineno-2-14) INFO: Running ansible-galaxy to install collection and it's dependencies. [](https://docs.ansible.com/projects/dev-environment/#__codelineno-2-15) INFO: Removing installed /home/bthornto/github/network.interfaces/venv/lib64/python3.11/site-packages/ansible_collections/network/interfaces [](https://docs.ansible.com/projects/dev-environment/#__codelineno-2-16) INFO: Symlinking /home/bthornto/github/network.interfaces/venv/lib64/python3.11/site-packages/ansible_collections/network/interfaces to /home/bthornto/github/network.interfaces [](https://docs.ansible.com/projects/dev-environment/#__codelineno-2-17) WARNING: A virtual environment was specified but has not been activated. [](https://docs.ansible.com/projects/dev-environment/#__codelineno-2-18) WARNING: Please activate the virtual environment: [](https://docs.ansible.com/projects/dev-environment/#__codelineno-2-19) source venv/bin/activate` ### Tearing down the development environment[¶](https://docs.ansible.com/projects/dev-environment/#tearing-down-the-development-environment "Permanent link") `[](https://docs.ansible.com/projects/dev-environment/#__codelineno-3-1) $ ade uninstall ansible.scm [](https://docs.ansible.com/projects/dev-environment/#__codelineno-3-2) INFO Found collection name: ansible.scm from /home/bthornto/github/ansible.scm/galaxy.yml. [](https://docs.ansible.com/projects/dev-environment/#__codelineno-3-3) INFO Requirements file /home/bthornto/github/ansible.scm/requirements.txt is empty, skipping [](https://docs.ansible.com/projects/dev-environment/#__codelineno-3-4) INFO Uninstalling python requirements from /home/bthornto/github/ansible.scm/test-requirements.txt [](https://docs.ansible.com/projects/dev-environment/#__codelineno-3-5) INFO Removed ansible.utils: /home/bthornto/github/ansible.scm/venv/lib64/python3.11/site-packages/ansible_collections/ansible/utils [](https://docs.ansible.com/projects/dev-environment/#__codelineno-3-6) INFO Removed ansible.utils*.info: /home/bthornto/github/ansible.scm/venv/lib64/python3.11/site-packages/ansible_collections/ansible.utils-2.10.3.info [](https://docs.ansible.com/projects/dev-environment/#__codelineno-3-7) INFO Removed ansible.scm: /home/bthornto/github/ansible.scm/venv/lib64/python3.11/site-packages/ansible_collections/ansible/scm [](https://docs.ansible.com/projects/dev-environment/#__codelineno-3-8) INFO Removed collection namespace root: /home/bthornto/github/ansible.scm/venv/lib64/python3.11/site-packages/ansible_collections/ansible [](https://docs.ansible.com/projects/dev-environment/#__codelineno-3-9) INFO Removed collection root: /home/bthornto/github/ansible.scm/venv/lib64/python3.11/site-packages/ansible_collections` Help[¶](https://docs.ansible.com/projects/dev-environment/#help "Permanent link") ---------------------------------------------------------------------------------- `ade --help` `ade install --help` `ade uninstall --help` --- # Using Runner with Execution Environments — Ansible Runner Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/runner/en/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Runner Documentation](https://docs.ansible.com/projects/runner/en/stable/) * [](https://docs.ansible.com/projects/runner/en/latest/) * Using Runner with Execution Environments * [View page source](https://docs.ansible.com/projects/runner/en/latest/_sources/execution_environments.rst.txt) * * * Using Runner with Execution Environments[](https://docs.ansible.com/projects/runner/en/latest/execution_environments/#using-runner-with-execution-environments "Link to this heading") ======================================================================================================================================================================================== Note For an Execution Environments general technology overview and to learn how get started using it in a few easy steps, see the [Getting started with Execution Environments guide](https://docs.ansible.com/projects/ansible/devel/getting_started_ee/index.html) . **Execution Environments** are meant to be a consistent, reproducible, portable, and shareable method to run Ansible Automation jobs in the exact same way on your laptop as they are executed in [Ansible AWX](https://github.com/ansible/awx/) . This aids in the development of automation jobs and Ansible Content that is meant to be run in **Ansible AWX**, or via [Red Hat Ansible Automation Platform](https://www.ansible.com/products/automation-platform) in a predictable way. More specifically, the term **Execution Environments** within the context of **Ansible Runner** refers to the container runtime execution of **Ansible** via **Ansible Runner** within an [OCI Compliant Container Runtime](https://github.com/opencontainers/runtime-spec) using an [OCI Compliant Container Image](https://github.com/opencontainers/image-spec/) that appropriately bundles [Ansible Base](https://github.com/ansible/ansible) , [Ansible Collection Content](https://github.com/ansible-collections/overview) , and the runtime dependencies required to support these contents. The build tooling provided by [Ansible Builder](https://github.com/ansible/ansible-builder) aids in the creation of these images. All aspects of running **Ansible Runner** in standalone mode (see: [Using Runner as a standalone command line tool](https://docs.ansible.com/projects/runner/en/latest/standalone/#standalone) ) are true here with the exception that the process isolation is inherently a container runtime ([podman](https://podman.io/) by default). Using Execution Environments from Protected Registries[](https://docs.ansible.com/projects/runner/en/latest/execution_environments/#using-execution-environments-from-protected-registries "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- When a job is run that uses an execution environment container image from a private/protected registry, you will first need to authenticate to the registry. If you are running the job manually via `ansible-runner run`, logging in on the command line via `podman login` first is a method of authentication. Alternatively, creating a `container_auth_data` dictionary with the keys `host`, `username`, and `password` and putting that in the job’s `env/settings` file is another way to ensure a successful pull of a protected execution environment container image. Note that this involves listing sensitive information in a file which will not automatically get cleaned up after the job run is complete. When running a job remotely via AWX, Ansible Runner can pick up the authentication information from the Container Registry Credential that was provided by the user. The `host`, `username`, `password`, and `verify_ssl` inputs from the credential are passed into Ansible Runner via the `container_auth_data` dictionary as key word arguments into a `json` file which gets deleted at the end of the job run (even if the job was cancelled/interrupted), enabling the bypassing of sensitive information from any potentially persistent job-related files. Notes and Considerations[](https://docs.ansible.com/projects/runner/en/latest/execution_environments/#notes-and-considerations "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------- There are some differences between using Ansible Runner and running Ansible directly from the command line that have to do with configuration, content locality, and secret data. ### Secrets[](https://docs.ansible.com/projects/runner/en/latest/execution_environments/#secrets "Link to this heading") Typically with Ansible you are able to provide secret data via a series of mechanisms, many of which are pluggable and configurable. When using Ansible Runner, however, certain considerations need to be made; these are analogous to how Ansible AWX manage this information. See [Runner Input Directory Hierarchy](https://docs.ansible.com/projects/runner/en/latest/intro/#inputdir) for more information ### Container Names[](https://docs.ansible.com/projects/runner/en/latest/execution_environments/#container-names "Link to this heading") Like all ansible-runner jobs, each job has an identifier associated with it which is also the name of the artifacts subfolder where results are saved to. When a container for job isolation is launched, it will be given a name of `ansible_runner_`. Some characters from the job identifier may be replaced with underscores for compatibility with names that Podman and Docker allow. This name is used internally if a command needs to be ran against the container at a later time (e.g., to stop the container when the job is canceled). ### ~/.ssh/ symlinks[](https://docs.ansible.com/projects/runner/en/latest/execution_environments/#ssh-symlinks "Link to this heading") When using the `run_command()` Python API method, Ansible Runner will automatically bind mount your local SSH agent UNIX-domain socket (`SSH_AUTH_SOCK`) into the container runtime. However, this does not work if files in your `~/.ssh/` directory happen to be symlinked to another directory that is also not mounted into the container runtime. To address this, or to manually mount your SSH directory, you may utilize the `--container-volume-mount` CLI option, or the `container_volume_mounts` API parameter for the `run_command()`, `run()`, or `run_async()` API methods. Here is an example of an ssh config file that is a symlink: $ $ ls -l ~/.ssh/config lrwxrwxrwx. 1 myuser myuser 34 Jul 15 19:27 /home/myuser/.ssh/config -> /home/myuser/dotfiles/ssh\_config $ ansible-runner run \\ --container-volume-mount /home/myuser/dotfiles/:/home/myuser/dotfiles/ \\ --process-isolation --process-isolation-executable podman \\ /tmp/private --playbook my\_playbook.yml -i my\_inventory.ini --- # Introduction - antsibull-nox – Antsibull Nox Helper [Skip to content](https://docs.ansible.com/projects/antsibull-nox/introduction/#why-antsibull-nox) Why antsibull-nox?[¶](https://docs.ansible.com/projects/antsibull-nox/introduction/#why-antsibull-nox "Permanent link") ======================================================================================================================== `antsibull-nox` is designed to simplify the process of testing Ansible collections through a common interface for various tools. Tool landscape[¶](https://docs.ansible.com/projects/antsibull-nox/introduction/#tool-landscape "Permanent link") ----------------------------------------------------------------------------------------------------------------- The CLI tool `ansible-test`, which is part of ansible-core, is the main way to [test collections](https://docs.ansible.com/ansible/devel/dev_guide/developing_collections_testing.html) . (Note that `ansible-test` is included in the `ansible-core` package, and unrelated to the PyPI package called `ansible-test`.) Many collections also run [`ansible-lint`](https://ansible.readthedocs.io/projects/lint/) to check roles and integration tests. [`molecule`](https://ansible.readthedocs.io/projects/molecule/) is another tool that collections run to test roles or even modules and plugins. In addition these tools, there are many other tools that can test collections. For example, [`antsibull-docs` includes a collection documentation linter](https://ansible.readthedocs.io/projects/antsibull-docs/collection-docs/#linting-collection-docs) . Many collections also have stricter Python linting than the `pylint` and `pep8` checks that `ansible-test` offers. Likewise, tools such as `black` are often used with collections to format code. Some other collections use [license checkers such as `reuse`](https://pypi.org/project/reuse/) or [spell checkers such as `codespell`](https://pypi.org/project/codespell/) . Running all these tools on collections can be non-trivial because collections do not contain Python packages directly. Instead, at runtime, Ansible dynamically makes collections available as a Python package named `ansible_collections` that is outside the root directory of each collection. Another factor that increases the complexity of testing collections with a combination of multiple tools is that every tool has its own set of dependencies that you need to install. Benefits of antsibull-nox[¶](https://docs.ansible.com/projects/antsibull-nox/introduction/#benefits-of-antsibull-nox "Permanent link") --------------------------------------------------------------------------------------------------------------------------------------- `antsibull-nox` is built specifically for the structure of Ansible collections unlike many other test runners, such as [tox](https://pypi.org/project/tox/) , [nox](https://pypi.org/project/nox/) , [pre-commit.com](https://pypi.org/project/pre-commit/) . The common interface that `antsibull-nox` provides also makes it easier for you and your contributors to run tests locally. There is no need to install several different tools and figure out how to run them correctly. You can simply run a single `nox` command to execute all tests after installing `antsibull-nox`. You don't even need to bother with installation; just run either `pipx run noxfile.py` or `uv run noxfile.py`. --- # Community - Ansible Navigator Documentation [Skip to content](https://docs.ansible.com/projects/navigator/contributing/community/#talk-to-us) [](https://github.com/ansible/ansible-navigator/blob/main/docs/contributing/community.md "Edit this page") Community[¶](https://docs.ansible.com/projects/navigator/contributing/community/#community "Permanent link") ============================================================================================================= Connect with the Ansible community! Talk to us[¶](https://docs.ansible.com/projects/navigator/contributing/community/#talk-to-us "Permanent link") --------------------------------------------------------------------------------------------------------------- Join the Ansible forum to ask questions, get help, and interact with the community. * [Get Help](https://forum.ansible.com/c/help/6) : get help or help others. Please add appropriate tags if you start new discussions, for example use the `ansible-navigator` or `devtools` tags. * [Social Spaces](https://forum.ansible.com/c/chat/4) : meet and interact with fellow enthusiasts. * [News & Announcements](https://forum.ansible.com/c/news/5) : track project-wide announcements including social events. To get release announcements and important changes from the community, see the [Bullhorn newsletter](https://docs.ansible.com/ansible/devel/community/communication.html#the-bullhorn) . If you encounter security-related concerns, report them via email to [security@ansible.com](mailto:security@ansible.com) . Code of Conduct[¶](https://docs.ansible.com/projects/navigator/contributing/community/#code-of-conduct "Permanent link") ------------------------------------------------------------------------------------------------------------------------- Please see the [Ansible Community Code of Conduct](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html) . --- # Security Policy - Ansible Navigator Documentation [Skip to content](https://docs.ansible.com/projects/navigator/contributing/security/#supported-versions) [](https://github.com/ansible/ansible-navigator/blob/main/docs/contributing/security.md "Edit this page") Security Policy[¶](https://docs.ansible.com/projects/navigator/contributing/security/#security-policy "Permanent link") ======================================================================================================================== Supported Versions[¶](https://docs.ansible.com/projects/navigator/contributing/security/#supported-versions "Permanent link") ------------------------------------------------------------------------------------------------------------------------------ Ansible Navigator does not backport security fixes only applying them to the main branch and making the next patch release in the stream. Reporting a Vulnerability[¶](https://docs.ansible.com/projects/navigator/contributing/security/#reporting-a-vulnerability "Permanent link") -------------------------------------------------------------------------------------------------------------------------------------------- We encourage responsible disclosure practices for security vulnerabilities. Please read our [policies for reporting bugs](https://docs.ansible.com/ansible/devel/community/reporting_bugs_and_features.html#reporting-a-bug) if you want to report a security issue that might affect Ansible. --- # Join the Ansible community | Ansible documentation Join us at [Red Hat Summit in Atlanta](https://www.redhat.com/en/summit?sc_id=RHCTE0250000464461) to learn about Ansible Automation Platform | May 11-14, 2026 Join the Ansible community -------------------------- Open-source and collaboration are at the heart of the Ansible community, helping more people experience the power of automation and work better and faster together. ### Collaborate with us [Read the code of conduct](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html) [Explore ways to contribute](https://docs.ansible.com/ansible/latest/community/how_can_I_help.html) [Find an Ansible project](https://docs.ansible.com/ecosystem.html) [Review the contributor path](https://docs.ansible.com/ansible/devel/community/contributor_path.html) ### Join the conversation [Join the Ansible Forum](https://docs.ansible.com/ansible/devel/community/communication.html#forum) [Find meetups and events](https://forum.ansible.com/c/events/8) [Check out the guide to community communication](https://docs.ansible.com/ansible/devel/community/communication.html) ### Participate in community discussions [Share your ideas and vote on topics](https://docs.ansible.com/ansible/devel/community/communication.html#ansible-community-topics) [Take part in a working group](https://docs.ansible.com/ansible/latest/community/communication.html#working-groups) ### Follow Ansible community news and announcements [Subscribe to the Bullhorn](https://docs.ansible.com/ansible/devel/community/communication.html#the-bullhorn) * [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) * [Privacy policy](https://www.redhat.com/en/about/privacy-policy) * [Code of conduct](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html) Sponsored by [![Red Hat logo.](https://docs.ansible.com/assets/images/redhat_reversed.svg)](https://www.redhat.com/en/technologies/management/ansible?sc_id=RHCTE0250000464439) --- # Ansible Runner — Ansible Runner Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/runner/en/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Runner Documentation](https://docs.ansible.com/projects/runner/en/stable/) * [](https://docs.ansible.com/projects/runner/en/latest/#) * Ansible Runner * [View page source](https://docs.ansible.com/projects/runner/en/latest/_sources/index.rst.txt) * * * Ansible Runner[](https://docs.ansible.com/projects/runner/en/latest/#ansible-runner "Link to this heading") ============================================================================================================= Ansible Runner is a tool and python library that helps when interfacing with Ansible directly or as part of another system whether that be through a container image interface, as a standalone tool, or as a Python module that can be imported. The goal is to provide a stable and consistent interface abstraction to Ansible. This allows **Ansible** to be embedded into other systems that don’t want to manage the complexities of the interface on their own (such as CI/CD platforms, Jenkins, or other automated tooling). **Ansible Runner** represents the modularization of the part of [Ansible AWX](https://github.com/ansible/awx) that is responsible for running `ansible` and `ansible-playbook` tasks and gathers the output from it. It does this by presenting a common interface that doesn’t change, even as **Ansible** itself grows and evolves. Part of what makes this tooling useful is that it can gather its inputs in a flexible way (See [Introduction to Ansible Runner](https://docs.ansible.com/projects/runner/en/latest/intro/#intro) :). It also has a system for storing the output (stdout) and artifacts (host-level event data, fact data, etc) of the playbook run. There are 3 primary ways of interacting with **Runner** * A standalone command line tool (`ansible-runner`) that can be started in the foreground or run in the background asynchronously * A python module - library interface **Ansible Runner** can also be configured to send status and event data to other systems using a plugin interface, see [Sending Runner Status and Events to External Systems](https://docs.ansible.com/projects/runner/en/latest/external_interface/#externalintf) . Examples of this could include: * Sending status to Ansible AWX * Sending events to an external logging service Contents: * [Introduction to Ansible Runner](https://docs.ansible.com/projects/runner/en/latest/intro/) * [Installing Ansible Runner](https://docs.ansible.com/projects/runner/en/latest/install/) * [Community](https://docs.ansible.com/projects/runner/en/latest/community/) * [Sending Runner Status and Events to External Systems](https://docs.ansible.com/projects/runner/en/latest/external_interface/) * [Using Runner as a standalone command line tool](https://docs.ansible.com/projects/runner/en/latest/standalone/) * [Using Runner as a Python Module Interface to Ansible](https://docs.ansible.com/projects/runner/en/latest/python_interface/) * [Using Runner with Execution Environments](https://docs.ansible.com/projects/runner/en/latest/execution_environments/) * [Remote job execution](https://docs.ansible.com/projects/runner/en/latest/remote_jobs/) * [Developer Documentation](https://docs.ansible.com/projects/runner/en/latest/modules/) Indices and tables[](https://docs.ansible.com/projects/runner/en/latest/#indices-and-tables "Link to this heading") ===================================================================================================================== * [Index](https://docs.ansible.com/projects/runner/en/latest/genindex/) * [Module Index](https://docs.ansible.com/projects/runner/en/latest/py-modindex/) * [Search Page](https://docs.ansible.com/projects/runner/en/latest/search/) --- # Using Runner as a standalone command line tool — Ansible Runner Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/runner/en/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Runner Documentation](https://docs.ansible.com/projects/runner/en/stable/) * [](https://docs.ansible.com/projects/runner/en/latest/) * Using Runner as a standalone command line tool * [View page source](https://docs.ansible.com/projects/runner/en/latest/_sources/standalone.rst.txt) * * * Using Runner as a standalone command line tool[](https://docs.ansible.com/projects/runner/en/latest/standalone/#using-runner-as-a-standalone-command-line-tool "Link to this heading") ======================================================================================================================================================================================== The **Ansible Runner** command line tool can be used as a standard command line interface to **Ansible** itself but is primarily intended to fit into automation and pipeline workflows. Because of this, it has a bit of a different workflow than **Ansible** itself because you can select between a few different modes to launch the command. While you can launch **Runner** and provide it all of the inputs as arguments to the command line (as you do with **Ansible** itself), there is another interface where inputs are gathered into a single location referred to in the command line parameters as `private_data_dir`. (see [Runner Input Directory Hierarchy](https://docs.ansible.com/projects/runner/en/latest/intro/#inputdir) ) To view the parameters accepted by `ansible-runner`: $ ansible-runner --help An example invocation of the standalone `ansible-runner` utility: $ ansible-runner run /tmp/private -p playbook.yml Where playbook.yml is the playbook from the `/tmp/private/projects` directory, and `run` is the command mode you want to invoke **Runner** with The different **commands** that runner accepts are: * `run` starts `ansible-runner` in the foreground and waits until the underlying **Ansible** process completes before returning * `start` starts `ansible-runner` as a background daemon process and generates a pid file * `stop` terminates an `ansible-runner` process that was launched in the background with `start` * `is-alive` checks the status of an `ansible-runner` process that was started in the background with `start` While **Runner** is running it creates an `artifacts` directory (see [Runner Artifacts Directory Hierarchy](https://docs.ansible.com/projects/runner/en/latest/intro/#artifactdir) ) regardless of what mode it was started in. The resulting output and status from **Ansible** will be located here. You can control the exact location underneath the `artifacts` directory with the `-i IDENT` argument to `ansible-runner`, otherwise a random UUID will be generated. Executing **Runner** in the foreground[](https://docs.ansible.com/projects/runner/en/latest/standalone/#executing-runner-in-the-foreground "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------- When launching **Runner** with the `run` command, as above, the program will stay in the foreground and you’ll see output just as you expect from a normal **Ansible** process. **Runner** will still populate the `artifacts` directory, as mentioned in the previous section, to preserve the output and allow processing of the artifacts after exit. Executing **Runner** in the background[](https://docs.ansible.com/projects/runner/en/latest/standalone/#executing-runner-in-the-background "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------- When launching **Runner** with the `start` command, the program will generate a pid file and move to the background. You can check its status with the `is-alive` command, or terminate it with the `stop` command. You can find the stdout, status, and return code in the `artifacts` directory. Running Playbooks[](https://docs.ansible.com/projects/runner/en/latest/standalone/#running-playbooks "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------ An example invocation using `demo` as private directory: $ ansible-runner run demo --playbook test.yml Running Modules Directly[](https://docs.ansible.com/projects/runner/en/latest/standalone/#running-modules-directly "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------- An example invocating the `debug` module with `demo` as a private directory: $ ansible-runner run demo -m debug --hosts localhost -a msg=hello Running Roles Directly[](https://docs.ansible.com/projects/runner/en/latest/standalone/#running-roles-directly "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------- An example invocation using `demo` as private directory and `localhost` as target: $ ansible-runner run demo --role testrole --hosts localhost Ansible roles directory can be provided with `--roles-path` option. Role variables can be passed with `--role-vars` at runtime. Running with Process Isolation[](https://docs.ansible.com/projects/runner/en/latest/standalone/#running-with-process-isolation "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------- **Runner** supports process isolation. Process isolation creates a new mount namespace where the root is on a tmpfs that is invisible from the host and is automatically cleaned up when the last process exits. You can enable process isolation by providing the `--process-isolation` argument on the command line. **Runner** as of version 2.0 defaults to using `podman` as the process isolation executable, but supports using any executable that is compatible with the `bubblewrap` CLI arguments by passing in the `--process-isolation-executable` argument: $ ansible-runner --process-isolation ... **Runner** supports various process isolation arguments that allow you to provide configuration details to the process isolation executable. To view the complete list of arguments accepted by `ansible-runner`: $ ansible-runner --help Running with Directory Isolation[](https://docs.ansible.com/projects/runner/en/latest/standalone/#running-with-directory-isolation "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------ If you need to be able to execute multiple tasks in parallel that might conflict with each other or if you want to make sure a single invocation of Ansible/Runner doesn’t pollute or overwrite the playbook content you can give a base path: $ ansible-runner --directory-isolation-base-path /tmp/runner **Runner** will copy the project directory to a temporary directory created under that path, set it as the working directory, and execute from that location. After running that temp directory will be cleaned up and removed. Specifying an Alternate Inventory[](https://docs.ansible.com/projects/runner/en/latest/standalone/#specifying-an-alternate-inventory "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------- The default inventory, if not specified, will be `/inventory/`. All files within this subdirectory of the private data directory will be processed as potential inventory host files. You may specify a different inventory using the `--inventory` option. This value may be one of: > * A file name located within `/inventory/`. > > * An absolute or relative path to an alternate inventory file or directory. This path is not required to be inside of the private data directory. > Examples: \# Use inventory /inventory/hosts.backup $ ansible-runner run demo -p test.yml --inventory hosts.backup # Use inventory in the /path/to/alternate-inventory directory (outside of ) $ ansible-runner run demo -p test.yml --inventory /path/to/alternate-inventory # Use inventory in the inventory2 subdirectory, relative to current directory $ ansible-runner run demo -p test.yml --inventory inventory2 Note This option has no effect when using process isolation. Outputting json (raw event data) to the console instead of normal output[](https://docs.ansible.com/projects/runner/en/latest/standalone/#outputting-json-raw-event-data-to-the-console-instead-of-normal-output "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ **Runner** supports outputting json event data structure directly to the console (and stdout file) instead of the standard **Ansible** output, thus mimicking the behavior of the `json` output plugin. This is in addition to the event data that’s already present in the artifact directory. All that is needed is to supply the `-j` argument on the command line: $ ansible-runner ... -j ... Cleaning up artifact directories[](https://docs.ansible.com/projects/runner/en/latest/standalone/#cleaning-up-artifact-directories "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------ Using the command line argument `--rotate-artifacts` allows you to control the number of artifact directories that are present. Given a number as the parameter for this argument will cause **Runner** to clean up old artifact directories. The default value of `0` disables artifact directory cleanup. --- # Remote job execution — Ansible Runner Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/runner/en/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Runner Documentation](https://docs.ansible.com/projects/runner/en/stable/) * [](https://docs.ansible.com/projects/runner/en/latest/) * Remote job execution * [View page source](https://docs.ansible.com/projects/runner/en/latest/_sources/remote_jobs.rst.txt) * * * Remote job execution[](https://docs.ansible.com/projects/runner/en/latest/remote_jobs/#remote-job-execution "Link to this heading") ===================================================================================================================================== Ansible Runner supports the concept that a job run may be requested on one host but executed on another. This capability is primarily intended to be used by [Receptor](http://www.github.com/project-receptor/receptor) . Support for this in Runner involves a three phase process. * **Transmit**: Convert the job to a binary format that can be sent to the worker node. * **Worker**: Actually execute the job. * **Process**: Receive job results and process them. The following command illustrates how the three phases work together: $ ansible-runner transmit ./demo -p test.yml | ansible-runner worker | ansible-runner process ./demo In this example, the `ansible-runner transmit` command is given a private data directory of `./demo` and told to select the `test.yml` playbook from it. Instead of executing the playbook as `ansible-runner run` would do, the data dir and command line parameters are converted to a compressed binary stream that is emitted as stdout. The `transmit` command generally takes the same command line parameters as the `run` command. The `ansible-runner worker` command accepts this stream, runs the playbook, and generates a new compressed binary stream of the resulting job events and artifacts. This command optionally accepts the `--private-data-dir` option. If provided, it will extract the contents sent from `ansible-runner transmit` into that directory. The `ansible-runner process` command accepts the result stream from the worker, and fires all the normal callbacks and does job event processing. In the command above, this results in printing the playbook output and saving artifacts to the data dir. The `process` command takes a data dir as a parameter, to know where to save artifacts. Using Receptor as the remote executor[](https://docs.ansible.com/projects/runner/en/latest/remote_jobs/#using-receptor-as-the-remote-executor "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- A full expansion on how Receptor works is out of the scope of this document. We can set up a basic receptor node with a simple configuration file: \--- \- node: id: primary \- log\-level: level: Debug \- local\-only: \- control\-service: service: control filename: ./control.sock \- work\-command: worktype: ansible\-runner command: ansible\-runner params: worker allowruntimeparams: true We can then start that local receptor node: $ receptor --config ./receptor.yml Now we can repeat the `transmit`/`worker`/`process` example above, but instead of piping the output of `transmit` to `worker`, we can use the `receptorctl` command to send it to the receptor node we just started: $ ansible-runner transmit ./demo -p test.yml | receptorctl --socket ./control.sock work submit -f --node primary -p - ansible-runner | ansible-runner process ./demo Cleanup of Resources Used by Jobs[](https://docs.ansible.com/projects/runner/en/latest/remote_jobs/#cleanup-of-resources-used-by-jobs "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------- The transmit and process commands do not offer any automatic deletion of the private data directory or artifacts, because these are how the user interacts with runner. When running `ansible-runner worker`, if no `--private-data-dir` is given, it will extract the contents to a temporary directory which is deleted at the end of execution. If the `--private-data-dir` option is given, then the directory will persist after the run finishes unless the `--delete` flag is also set. In that case, the private data directory will be deleted before execution if it exists and also removed after execution. The following command offers out-of-band cleanup $ ansible-runner worker cleanup --file-pattern=/tmp/foo\_\* This would assure that old directories that fit the file glob `/tmp/foo_*` are deleted, which would could be used to assure cleanup of paths created by commands like `ansible-runner worker --private_data_dir=/tmp/foo_3`, for example. NOTE: see the `--grace-period` option, which sets the time window. This command also takes a `--remove-images` option to run the podman or docker `rmi` command. There is otherwise no automatic cleanup of images used by a run, even if `container_auth_data` is used to pull from a private container registry. To be sure that layers are deleted as well, the `--image-prune` flag is necessary. Artifact Directory Specification[](https://docs.ansible.com/projects/runner/en/latest/remote_jobs/#artifact-directory-specification "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------- The `worker` command does not write artifacts, these are streamed instead, and the `process` command is what ultimately writes the artifacts folder contents. With the default behavior, `ansible-runner process ./demo` would write artifacts to `./demo/artifacts`. If you wish to better align with normal ansible-runner use, you can pass the `--ident` option to save to a subfolder, so `ansible-runner process ./demo --ident=43` would extract artifacts to the folder `./demo/artifacts/43`. Python API[](https://docs.ansible.com/projects/runner/en/latest/remote_jobs/#python-api "Link to this heading") ----------------------------------------------------------------------------------------------------------------- Python code importing Ansible Runner can make use of these facilities by setting the `streamer` parameter to `ansible_runner.interface.run`. This parameter can be set to `transmit`, `worker` or `process` to invoke each of the three stages. Other parameters are as normal in the CLI. --- # Ansible community documentation archive | Ansible documentation Join us at [Red Hat Summit in Atlanta](https://www.redhat.com/en/summit?sc_id=RHCTE0250000464461) to learn about Ansible Automation Platform | May 11-14, 2026 Ansible community documentation archive --------------------------------------- Archive page where you can find older versions of documentation. ##### Ansible community documentation for version 2.8 [Visit the documentation](https://docs.ansible.com/projects/ansible/2.8-archive/) ##### Ansible community documentation for version 2.7 [Visit the documentation](https://docs.ansible.com/projects/ansible/2.7-archive/) ##### Ansible community documentation for version 2.6 [Visit the documentation](https://docs.ansible.com/projects/ansible/2.6-archive/) ##### Ansible community documentation for version 2.5 [Visit the documentation](https://docs.ansible.com/projects/ansible/2.5-archive/) ##### Ansible community documentation for version 2.4 [Visit the documentation](https://docs.ansible.com/projects/ansible/2.4-archive/) ##### Ansible community documentation for version 2.3 [Visit the documentation](https://docs.ansible.com/projects/ansible/2.3-archive/) * [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) * [Privacy policy](https://www.redhat.com/en/about/privacy-policy) * [Code of conduct](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html) Sponsored by [![Red Hat logo.](https://docs.ansible.com/assets/images/redhat_reversed.svg)](https://www.redhat.com/en/technologies/management/ansible?sc_id=RHCTE0250000464439) --- # Other projects - antsibull-changelog – Ansible Changelog Tool [Skip to content](https://docs.ansible.com/projects/antsibull-changelog/other-projects/#changelogs-for-other-projects) Changelogs for other projects[¶](https://docs.ansible.com/projects/antsibull-changelog/other-projects/#changelogs-for-other-projects "Permanent link") ======================================================================================================================================================= The `antsibull-changelog` tool allows you to create and update changelogs for arbitrary projects, similar to the changelog of ansible-core or many Ansible collections which rely on antsibull-changelog. The following instructions assume that antsibull has been properly installed, for example via `pip install antsibull-changelog`. This is the preferred way to install `antsibull-changelog`. If you want to get the current `main` branch with not yet released changes, run `pip install https://github.com/ansible-community/antsibull-changelog/archive/main.tar.gz`. If you cloned the git repository and want to run it from there with `poetry`, `antsibull-changelog` has to be substituted with `poetry run antsibull-changelog`. Bootstrapping changelogs for projects[¶](https://docs.ansible.com/projects/antsibull-changelog/other-projects/#bootstrapping-changelogs-for-projects "Permanent link") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- To set up `antsibull-changelog`, run: `[](https://docs.ansible.com/projects/antsibull-changelog/other-projects/#__codelineno-0-1) antsibull-changelog init --is-other-project /path/to/your/project` This creates subdirectories `changelogs/` and `changelogs/fragments/`, and a configuration file `changelogs/config.yaml`. Adjust the configuration file to your needs. The settings of highest interest are: 1. `title`: This is by default `Project`. Please replace this with the name of your project. 2. `output_formats`: This is by default `[rst]`. Change this to `[rst, md]` to output both a RST and MarkDown version of the changelog, or to `[md]` to only output a MarkDown version. 3. `use_semantic_versioning`: The default value `true` assumes that version numbers follow the [semantic versioning spec](https://semver.org/) . This mostly affects prerelease detection and version ordering. 4. `keep_fragments`: The default value `false` removes the fragment files after a release is done. If you prefer to keep fragment files for older releases, set this to `true`. If you want to remove fragments after a release, but archive them in another directory, you can use the `archive_path_template` option in combination with `keep_fragments: no`. See further below in the list for its usage. 5. `changelog_filename_template`: The default value `../CHANGELOG.rst` is relative to the `changelogs/` directory. 6. `always_refresh`: See ["Updating/Refreshing changelog.yaml"](https://docs.ansible.com/projects/antsibull-changelog/other-projects/#updatingrefreshing-changelogyaml) on refreshing changelog fragments and/or plugin descriptions. 7. `archive_path_template`: If `keep_fragments` is set to `false`, and `archive_path_template` is set, fragments will be copied into the directory denoted by `archive_path_template` instead of being deleted. The directory is created if it does not exist. The placeholder `{version}` can be used for the current project version into which the fragment was included. For a description of all configuration settings, see the separate document [Configuration Settings for antsibull-changelog](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/) . Validating changelog fragments[¶](https://docs.ansible.com/projects/antsibull-changelog/other-projects/#validating-changelog-fragments "Permanent link") --------------------------------------------------------------------------------------------------------------------------------------------------------- If you want to do a basic syntax check of changelog fragments, you can run: `[](https://docs.ansible.com/projects/antsibull-changelog/other-projects/#__codelineno-1-1) antsibull-changelog lint` If you want to check a specific fragment, you can provide a path to it; otherwise, all fragments in `changelogs/fragments/` are checked. This can be used in CI to avoid contributors to check in invalid changelog fragments, or introduce new sections (by mistyping existing ones, or simply guessing wrong names). If `antsibull-changelog lint` produces no output on stdout, and exits with exit code 0, the changelog fragments are OK. If errors are found, they are reported by one line in stdout for each error in the format `path/to/fragment:line:column:message`, and the program exits with exit code 3. Other exit codes indicate problems with the command line or during the execution of the linter. Releasing a new version of your project[¶](https://docs.ansible.com/projects/antsibull-changelog/other-projects/#releasing-a-new-version-of-your-project "Permanent link") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- To release a new version of your project, you need to run: `[](https://docs.ansible.com/projects/antsibull-changelog/other-projects/#__codelineno-2-1) antsibull-changelog release --version ` inside your project's tree. You can also specify a release date with `--date 2020-12-31`, if the default (today) is not what you want. When doing a release, the changelog generator will read all changelog fragments which are not already mentioned in the changelog, and include them in a new entry in `changelogs/changelog.yaml`. After running `antsibull-changelog release`, you should check `changelogs/changelog.yaml` and the generated reStructuredText file (by default `CHANGELOG.rst`) in. Updating/Refreshing changelog.yaml[¶](https://docs.ansible.com/projects/antsibull-changelog/other-projects/#updatingrefreshing-changelogyaml "Permanent link") --------------------------------------------------------------------------------------------------------------------------------------------------------------- By default, the `changelogs/changelog.yaml` file is the main source of truth for antsibull-changelog. It is only modified when a new release is done, and in that case existing entries for other versions than the current one are not touched. If the main source of truth should be the fragments, the refreshing options or config has to be used. 1. The `always_refresh` configuration is a string with one of the following values: 2. `none` (default): equivalent to `--refresh-fragments` and `--refresh` not specified; 3. `full`: equivalent to `--refresh-fragments with-archives` specified, or alternatively `--refresh`; 4. a comma-separated list, where the following entries are supported: * `fragments`: equivalent to `--refresh-fragments with-archives` specified; * `fragments-without-archives`: equivalent to `--refresh-fragments without-archives` specified. 5. The `--refresh` command line parameter is equivalent to `--refresh-fragments with-archives`. 6. `--refresh-fragments`: if specified, the fragments for all versions will be recreated from the changelog fragment files. This is only possible if `keep_fragments` is `true`, or fragment archives exist (see the `archive_path_template` option). Note that if not all fragments were archived or kept in the fragments directory, they will be **removed** from the changelog. 7. `with-archives` (default): Uses both the archives and the current fragment directory to update the fragments. 8. `without-archives`: Uses only the current fragment directory to update the fragments. Fragments that have been moved to the archive and no longer exist in the fragment directory will vanish from the changelog. Changelog Fragment Categories[¶](https://docs.ansible.com/projects/antsibull-changelog/other-projects/#changelog-fragment-categories "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------------------- This section describes the section categories created in the default config. If you really want, you can change them. The categories are the same as the ones in the [Ansible-case changelog fragments](https://docs.ansible.com/projects/ansible/devel/community/development_process.html#changelogs-how-to) . The full list of categories is: **release\_summary** This is a special section: as opposed to a list of strings, it accepts one string. This string will be inserted at the top of the changelog entry for the current version, before any section. There can only be one fragment with a `release_summary` section. In ansible-core, this is used for stating the release date and for linking to the porting guide ([example](https://github.com/ansible/ansible/blob/stable-2.9/changelogs/fragments/v2.9.0_summary.yaml) , [result](https://github.com/ansible/ansible/blob/stable-2.9/changelogs/CHANGELOG-v2.9.rst#id23) ). **breaking\_changes** This (new) category should list all changes to features which absolutely require attention from users when upgrading, because an existing behavior is changed. This is mostly what Ansible's Porting Guide used to describe. This section should only appear in a initial major release (`x.0.0`) according to semantic versioning. **major\_changes** This category contains major changes to the project. It should only contain a few items per major version, describing high-level changes. This section should not appear in patch releases according to semantic versioning. **minor\_changes** This category should mention all new features, like plugin or module options. This section should not appear in patch releases according to semantic versioning. **removed\_features** This category should mention all modules, plugins and features that have been removed in this release. This section should only appear in a initial major release (`x.0.0`) according to semantic versioning. **deprecated\_features** This category should contain all modules, plugins and features which have been deprecated and will be removed in a future release. This section should not appear in patch releases according to semantic versioning. **security\_fixes** This category should mention all security relevant fixes, including CVEs if available. **bugfixes** This category should be a list of all bug fixes which fix a bug that was present in a previous version. **known\_issues** This category should mention known issues that are currently not fixed or will not be fixed. **trivial** This category will **not be shown** in the changelog. It can be used to describe changes that are not touching user-facing code, like changes in tests. This is useful if every PR is required to have a changelog fragment. ### Examples[¶](https://docs.ansible.com/projects/antsibull-changelog/other-projects/#examples "Permanent link") A guide on how to write changelog fragments can be found in the [Ansible docs](https://docs.ansible.com/projects/ansible/devel/community/development_process.html#changelogs-how-to) . Example of a regular changelog fragment: `[](https://docs.ansible.com/projects/antsibull-changelog/other-projects/#__codelineno-3-1) bugfixes: [](https://docs.ansible.com/projects/antsibull-changelog/other-projects/#__codelineno-3-2) - docker_container - wait for removal of container if docker API returns early [](https://docs.ansible.com/projects/antsibull-changelog/other-projects/#__codelineno-3-3) (https://github.com/ansible/ansible/issues/65811).` The filename in this case was `changelogs/fragments/65854-docker_container-wait-for-removal.yml`, because this was implemented in [PR #65854 in ansible/ansible](https://github.com/ansible/ansible/pull/65854) . A fragment can also contain multiple sections, or multiple entries in one section: `[](https://docs.ansible.com/projects/antsibull-changelog/other-projects/#__codelineno-4-1) deprecated_features: [](https://docs.ansible.com/projects/antsibull-changelog/other-projects/#__codelineno-4-2) - docker_container - the ``trust_image_content`` option will be removed. It has always been ignored by the module. [](https://docs.ansible.com/projects/antsibull-changelog/other-projects/#__codelineno-4-3) - docker_stack - the return values ``err`` and ``out`` have been deprecated. Use ``stdout`` and ``stderr`` from now on instead. [](https://docs.ansible.com/projects/antsibull-changelog/other-projects/#__codelineno-4-4) [](https://docs.ansible.com/projects/antsibull-changelog/other-projects/#__codelineno-4-5) breaking_changes: [](https://docs.ansible.com/projects/antsibull-changelog/other-projects/#__codelineno-4-6) - "docker_container - no longer passes information on non-anonymous volumes or binds as ``Volumes`` to the Docker daemon. This increases compatibility with the ``docker`` CLI program. Note that if you specify ``volumes: strict`` in ``comparisons``, this could cause existing containers created with docker_container from Ansible 2.9 or earlier to restart."` The `release_summary` section is special, in that it doesn't contain a list of strings, but a string, and that only one such entry can be shown in the changelog of a release. Usually for every release (pre-release or regular release), at most one fragment is added which contains a `release_summary`, and this is only done by the person doing the release. The `release_summary` should include some global information on the release; for example, in [Ansible's changelog](https://github.com/ansible/ansible/blob/stable-2.9/changelogs/CHANGELOG-v2.9.rst#release-summary) , it always mentions the release date and links to the porting guide. An example of how a fragment with `release_summary` could look like: `[](https://docs.ansible.com/projects/antsibull-changelog/other-projects/#__codelineno-5-1) release_summary: | [](https://docs.ansible.com/projects/antsibull-changelog/other-projects/#__codelineno-5-2) This is the first proper release of ``antsibull-changelog`` on 2020-06-20.` --- # User Guide - Tox Ansible Documentation [Skip to content](https://docs.ansible.com/projects/tox-ansible/user_guide/#usage-of-tox-ansible) [](https://github.com/ansible/tox-ansible/blob/main/docs/user_guide.md "Edit this page") Usage of tox-ansible[¶](https://docs.ansible.com/projects/tox-ansible/user_guide/#usage-of-tox-ansible "Permanent link") ========================================================================================================================= > Need help or want to discuss the project? See our [Contributor guide](https://ansible.readthedocs.io/projects/tox-ansible/contributor_guide/#talk-to-us) > to learn how to join the conversation! From the root of your collection, create an empty `tox-ansible.ini` file and list the available environments: `[](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-0-1) touch tox-ansible.ini [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-0-2) tox list --ansible --conf tox-ansible.ini` A list of dynamically generated Ansible environments will be displayed: `[](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-1-1) default environments: [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-1-2) ... [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-1-3) integration-py3.11-2.14 -> Integration tests for ansible.scm using ansible-core 2.14 and python 3.11 [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-1-4) integration-py3.12-devel -> Integration tests for ansible.scm using ansible-core devel and python 3.11 [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-1-5) ... [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-1-6) sanity-py3.11-2.14 -> Sanity tests for ansible.scm using ansible-core 2.14 and python 3.11 [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-1-7) sanity-py3.12-devel -> Sanity tests for ansible.scm using ansible-core devel and python 3.11 [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-1-8) ... [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-1-9) unit-py3.11-2.14 -> Unit tests for ansible.scm using ansible-core 2.14 and python 3.11 [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-1-10) unit-py3.12-devel -> Unit tests for ansible.scm using ansible-core devel and python 3.11` These represent the available testing environments. Each denotes the type of tests that will be run, the Python interpreter used to run the tests, and the Ansible version used to run the tests. To run tests with a single environment, simply run the following command: `[](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-2-1) tox -e sanity-py3.11-2.14 --ansible --conf tox-ansible.ini` To run tests with multiple environments, simply add the environment names to the command: `[](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-3-1) tox -e sanity-py3.11-2.14,unit-py3.11-2.14 --ansible --conf tox-ansible.ini` To run all tests of a specific type in all available environments, use the factor `-f` flag: `[](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-4-1) tox -f unit --ansible -p auto --conf tox-ansible.ini` To run all tests across all available environments: `[](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-5-1) tox --ansible -p auto --conf tox-ansible.ini` Note: The `-p auto` flag will run multiple tests in parallel. Note: The specific Python interpreter will need to be pre-installed on your system, e.g.: `[](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-6-1) sudo dnf install python3.9` To review the specific commands and configuration for each of the integration, sanity, and unit factors: `[](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-7-1) tox config --ansible --conf tox-ansible.ini` Generate specific GitHub action matrix as per scope mentioned with `--matrix-scope`: `[](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-8-1) tox --ansible --gh-matrix --matrix-scope unit --conf tox-ansible.ini` A list of dynamically generated Ansible environments will be displayed specifically for unit tests: `[](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-9-1) [ [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-9-2) { [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-9-3) "description": "Unit tests using ansible 2.9 and python 3.8", [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-9-4) "factors": [ [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-9-5) "unit", [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-9-6) "py3.8", [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-9-7) "2.9" [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-9-8) ], [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-9-9) "name": "unit-py3.8-2.9", [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-9-10) "python": "3.8" [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-9-11) }, [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-9-12) ... [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-9-13) { [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-9-14) "description": "Unit tests using ansible-core milestone and python 3.12", [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-9-15) "factors": [ [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-9-16) "unit", [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-9-17) "py3.12", [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-9-18) "milestone" [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-9-19) ], [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-9-20) "name": "unit-py3.12-milestone", [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-9-21) "python": "3.12" [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-9-22) } [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-9-23) ]` Passing command line arguments to ansible-test / pytest[¶](https://docs.ansible.com/projects/tox-ansible/user_guide/#passing-command-line-arguments-to-ansible-test-pytest "Permanent link") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The behavior of the `ansible-test` (for `sanity-*` environments) or `pytest` (for `unit-*` and `integration-*` environments) commands can be customized by passing further command line arguments to it, e.g., by invoking `tox` like this: `[](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-10-1) tox -f sanity --ansible --conf tox-ansible.ini -- --test validate-modules -vvv` The arguments after the `--` will be passed to the `ansible-test` command. Thus in this example, only the `validate-modules` sanity test will run, but with an increased verbosity. Same can be done to pass arguments to the `pytest` commands for the `unit-*` and `integration-*` environments: `[](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-11-1) tox -e unit-py3.13-2.19 --ansible --conf tox-ansible.ini -- --junit-xml=tests/output/junit/unit.xml` Usage in a CI/CD pipeline[¶](https://docs.ansible.com/projects/tox-ansible/user_guide/#usage-in-a-cicd-pipeline "Permanent link") ---------------------------------------------------------------------------------------------------------------------------------- The repo contains a GitHub workflow that can be used in a GitHub actions CI/CD pipeline. The workflow will run all tests across all available environments unless limited by the `skip` option in the `tox-ansible.ini` file. Each environment will be run in a separate job. The workflow will run all jobs in parallel. The GitHub matrix is dynamically created by `tox-ansible` using the `--gh-matrix` and `--ansible` flags. The list of environments is converted to a list of entries in json format and added to the file specified by the "GITHUB\_OUTPUT" environment variable. The workflow will read this file and use it to create the matrix. A sample use of the GitHub workflow might look like this: `[](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-12-1) name: Test collection [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-12-2) [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-12-3) concurrency: [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-12-4) group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }} [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-12-5) cancel-in-progress: true [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-12-6) [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-12-7) on: [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-12-8) pull_request: [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-12-9) branches: [main] [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-12-10) workflow_dispatch: [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-12-11) [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-12-12) jobs: [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-12-13) tox-ansible: [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-12-14) uses: ansible/tox-ansible/.github/workflows/run.yml@main` Sample `json` `[](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-13-1) [ [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-13-2) // ... [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-13-3) { [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-13-4) "description": "Integration tests using ansible-core devel and python 3.11", [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-13-5) "factors": ["integration", "py3.11", "devel"], [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-13-6) "name": "integration-py3.12-devel", [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-13-7) "python": "3.11" [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-13-8) } [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-13-9) // ... [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-13-10) ]` Testing molecule scenarios[¶](https://docs.ansible.com/projects/tox-ansible/user_guide/#testing-molecule-scenarios "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------- Although the `tox-ansible` plugin does not have functionality specific to molecule, it can be a powerful tool to run `molecule` scenarios across a matrix of Ansible and Python versions. This can be accomplished by presenting molecule scenarios as integration tests available through `pytest` using the [pytest-ansible](https://github.com/ansible-community/pytest-ansible) plugin, which is installed when `tox-ansible` is installed. Assuming the following collection directory structure: `[](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-14-1) namespace.name [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-14-2) ├── extensions [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-14-3) │ ├── molecule [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-14-4) │ │ ├── playbook [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-14-5) │ │ │ ├── create.yml [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-14-6) │ │ │ ├── converge.yml [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-14-7) │ │ │ ├── molecule.yml [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-14-8) │ │ │ └── verify.yml [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-14-9) │ │ ├── plugins [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-14-10) │ │ │ ├── create.yml [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-14-11) │ │ │ ├── converge.yml [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-14-12) │ │ │ ├── molecule.yml [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-14-13) │ │ │ └── verify.yml [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-14-14) │ │ ├── targets [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-14-15) │ │ │ ├── create.yml [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-14-16) │ │ │ ├── converge.yml [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-14-17) │ │ │ ├── molecule.yml [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-14-18) │ │ │ └── verify.yml [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-14-19) ├── playbooks [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-14-20) │ └── site.yaml [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-14-21) ├── plugins [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-14-22) │ ├── action [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-14-23) │ │ └── action_plugin.py [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-14-24) │ ├── modules [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-14-25) │ │ └── module.py [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-14-26) ├── tests [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-14-27) │ ├── integration [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-14-28) │ │ │── targets [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-14-29) │ │ │ ├── success [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-14-30) │ │ │ │ └── tasks [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-14-31) │ │ │ │ └── main.yaml [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-14-32) │ │ └── test_integration.py [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-14-33) ├── tox-ansible.ini [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-14-34) └── tox.ini` Individual `molecule` scenarios can be added to the collection's extension directory to test playbooks, roles, and integration targets. In order to present each `molecule` scenario as an individual `pytest` test a new `helper` file is added. `[](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-15-1) # tests/integration/test_integration.py [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-15-2) [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-15-3) """Tests for molecule scenarios.""" [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-15-4) from __future__ import absolute_import, division, print_function [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-15-5) [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-15-6) from pytest_ansible.molecule import MoleculeScenario [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-15-7) [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-15-8) [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-15-9) def test_integration(molecule_scenario: MoleculeScenario) -> None: [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-15-10) """Run molecule for each scenario. [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-15-11) [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-15-12) :param molecule_scenario: The molecule scenario object [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-15-13) """ [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-15-14) proc = molecule_scenario.test() [](https://docs.ansible.com/projects/tox-ansible/user_guide/#__codelineno-15-15) assert proc.returncode == 0` The `molecule_scenario` fixture parametrizes the `molecule` scenarios found within the collection and creates an individual `pytest` test for each which will be run during any `integration-*` environment. This approach provides the flexibility of running the `molecule` scenarios directly with `molecule`, `pytest` or `tox`. Additionally, presented as native `pytest` tests, the `molecule` scenarios should show in the `pytest` test tree in the user's IDE. --- # home - Ansible Lint Documentation [Skip to content](https://docs.ansible.com/projects/lint/#ansible-lint-documentation) [](https://github.com/ansible/ansible-lint/blob/main/docs/index.md "Edit this page") [](https://github.com/ansible/ansible-lint/raw/main/docs/index.md "View source of this page") Ansible Lint Documentation[¶](https://docs.ansible.com/projects/lint/#ansible-lint-documentation "Permanent link") =================================================================================================================== About Ansible Lint[¶](https://docs.ansible.com/projects/lint/#about-ansible-lint "Permanent link") --------------------------------------------------------------------------------------------------- Ansible Lint is a command-line tool for linting **playbooks, roles and collections** aimed toward any Ansible users. Its main goal is to promote proven practices, patterns and behaviors while avoiding common pitfalls that can easily lead to bugs or make code harder to maintain. Ansible lint is also supposed to help users upgrade their code to work with newer versions of Ansible. Due to this reason we recommend using it with the newest version of Ansible, even if the version used in production may be older. As any other linter, it is opinionated. Still, its rules are the result of community contributions and they can always be disabled based individually or by category by each user. [Ansible Galaxy project](https://github.com/ansible/galaxy/) makes use of this linter to compute quality scores for [Galaxy Hub](https://galaxy.ansible.com/) contributed content. This does not mean this tool only targets those that want to share their code. Files like `galaxy.yml`, or sections like `galaxy_info` inside `meta.yml` help with documentation and maintenance, even for unpublished roles or collections. The project was originally started by [@willthames](https://github.com/willthames/) and has since been adopted by the Ansible Community team. Its development is purely community driven while keeping permanent communications with other Ansible teams. Back to top --- # Ansible Package Release Management [Skip to content](https://docs.ansible.com/projects/ansible-build-data/#ansible-build-data) ansible-build-data[¶](https://docs.ansible.com/projects/ansible-build-data/#ansible-build-data "Permanent link") ================================================================================================================= [![Documentation](https://img.shields.io/badge/docs-brightgreen.svg)](https://docs.ansible.com/projects/ansible-build-data/) [![Discuss on Matrix at #community:ansible.com](https://img.shields.io/matrix/community:ansible.com.svg?server_fqdn=ansible-accounts.ems.host&label=Discuss%20on%20Matrix%20at%20%23community:ansible.com&logo=matrix)](https://matrix.to/#/#community:ansible.com) Holds generated but persistent results from building the `ansible` community package. This information may be referred to by other projects and scripts. Issue tracker[¶](https://docs.ansible.com/projects/ansible-build-data/#issue-tracker "Permanent link") ------------------------------------------------------------------------------------------------------- [This repository's issue tracker](https://github.com/ansible-community/ansible-build-data/issues) handles various aspects of the `ansible` build, including: 1. Tracking release dates, 2. Tracking blockers for a release, 3. Tracking adding, renaming, and removing collections, 4. Tracking problems with a release related to the build process: 5. This includes problems that prevent the package to be installed or system packages to be built from the PyPI release; 6. Tracking and discussing other problems with the `ansible` community package: 7. This includes important problems with the included collections that are not acted on by the collection maintainers, for example largescale incompatibilities with the current ansible-core version, violations of semantic versioning, and general violations of the [Ansible inclusion requirements](https://docs.ansible.com/projects/ansible/devel/community/collection_contributors/collection_requirements.html) ; 8. This includes major or security bugs in collections with wide-reaching consequences that are not addressed by the collection maintainers, or cannot be addressed on the collection level for some reason. This issue tracker is **not** for tracking regular bugs or feature requests for `ansible-core` or the collections included in the `ansible` package or for user support. **Such issues will be closed.** Instead, check out the [`ansible-core` issue tracker](https://github.com/ansible/ansible) , issue trackers of the respective collections, or consider [asking for help in the Ansible forum](https://forum.ansible.com/) . Milestones[¶](https://docs.ansible.com/projects/ansible-build-data/#milestones "Permanent link") ------------------------------------------------------------------------------------------------- Release engineers check the [milestones](https://github.com/ansible-community/ansible-build-data/milestones) for corresponding releases some time before releasing the package sufficient to solve all related issues. Blockers[¶](https://docs.ansible.com/projects/ansible-build-data/#blockers "Permanent link") --------------------------------------------------------------------------------------------- In the context of the Ansible Community package release workflow, a **release blocker** is a situation which does not allow the package to be released. It might come with a new `ansible-core` release and affect many of the included collections or in any other way might severely affect consistent work with the `ansible` package. Severity of the impact is determined by the [Steering Committee](https://docs.ansible.com/projects/ansible/devel/community/steering/community_steering_committee.html) in each particular case. The release blocker must be resolved before the release can proceed. In case of a potential release blocker, the following actions need to be done: * Create a [community topic](https://github.com/ansible-community/community-topics/issues) describing the potential blocker. * If the [Steering Committee](https://docs.ansible.com/projects/ansible/devel/community/steering/community_steering_committee.html) considers the circumstances a release blocker, create an [issue](https://github.com/ansible-community/ansible-build-data/issues/new) in this repository. * Put the `blocker` label on the issue. * Add the issue to a milestone for the [affected release](https://github.com/ansible-community/ansible-build-data/milestones) . Structure of data[¶](https://docs.ansible.com/projects/ansible-build-data/#structure-of-data "Permanent link") --------------------------------------------------------------------------------------------------------------- :: `ansible-build-data └── 3 ├── ansible-3.0.0.deps ├── ansible-3.1.0.deps ├── ansible-3.build └── ansible.in` * Each major release of Ansible gets a subdirectory of the repository named according to the X.Y version number of Ansible. (ex: `3`) * Within each version directory, there is an `ansible.in` file which lists the collections that are in this release of Ansible. The file consists of one `namespace.collection` per line. This file is constructed by the person building Ansible for that release. * There will also be a file, `ansible-X.build`. This file contains lines which consist of `namespace.collection` followed by a version range like:: awx.awx: >=11.0.0,<12.0.0 The version range specifies potential versions of the collection that are backwards compatible with what was available when the initial Ansible-X.Y.0 release was frozen. Only versions of the collections within those ranges will be considered for Ansible minor releases. This file will be created by the `antsibull-build new-ansible` command. * Lastly, there will be multiple, `ansible-X.Y.Z.deps` files. Those files contain lines which consist of `namespace.collection` followed by a single version like:: awx.awx: 11.2.5 The version specifies the exact version of the collection that appeared in that release of Ansible. This file will be created by the `antsibull-build single` command. Linting[¶](https://docs.ansible.com/projects/ansible-build-data/#linting "Permanent link") ------------------------------------------------------------------------------------------- To lint the files in this repository, run `nox -e lint`. This assumes you have `nox` installed. Adding a new collection[¶](https://docs.ansible.com/projects/ansible-build-data/#adding-a-new-collection "Permanent link") --------------------------------------------------------------------------------------------------------------------------- ### Next Ansible major release[¶](https://docs.ansible.com/projects/ansible-build-data/#next-ansible-major-release "Permanent link") To add a collection to the next Ansible major release that has not reached feature freeze: * Add the collection to the `ansible.in` file in a sub-directory named with a corresponding number. * In the same sub-directory, add the collection to the `collection-meta.yaml` file, as shown below. * `maintainers` (list): The Github usernames of the collection's maintainers. * `repository` (string): The URL of the collection's git repository. * `collection-directory` (string): The collection's top level directory relative to the Git repository root. The top level directory is where `galaxy.yml` is located. For most collections, this should be set to `.`. However, some collections, such as `awx.awx`, store the collection in a subdirectory. In that case, `collection-directory` should be set to `./SUBDIRECTORY` (`SUBDIRECTORY` is a placeholder for the actual directory). * `changelog-url` (string): If the collection does not provide a changelog in `changelogs/changelog.yaml`, the URL to the actual changelog needs to be added. Otherwise, this field should be omitted. `[](https://docs.ansible.com/projects/ansible-build-data/#__codelineno-0-1) collections: [](https://docs.ansible.com/projects/ansible-build-data/#__codelineno-0-2) # NAMESPACE.NAME [](https://docs.ansible.com/projects/ansible-build-data/#__codelineno-0-3) community.example: [](https://docs.ansible.com/projects/ansible-build-data/#__codelineno-0-4) # The Github usernames of this collection's maintainers [](https://docs.ansible.com/projects/ansible-build-data/#__codelineno-0-5) maintainers: [](https://docs.ansible.com/projects/ansible-build-data/#__codelineno-0-6) - person1 [](https://docs.ansible.com/projects/ansible-build-data/#__codelineno-0-7) - person2 [](https://docs.ansible.com/projects/ansible-build-data/#__codelineno-0-8) # The URL to the collection's SCM repository. [](https://docs.ansible.com/projects/ansible-build-data/#__codelineno-0-9) repository: https://github.com/ansible-collections/community.example [](https://docs.ansible.com/projects/ansible-build-data/#__codelineno-0-10) # This is the directory where galaxy.yml is stored relative to the [](https://docs.ansible.com/projects/ansible-build-data/#__codelineno-0-11) # repository root. [](https://docs.ansible.com/projects/ansible-build-data/#__codelineno-0-12) # [](https://docs.ansible.com/projects/ansible-build-data/#__codelineno-0-13) # For collections stored in the repository root: [](https://docs.ansible.com/projects/ansible-build-data/#__codelineno-0-14) collection-directory: "." [](https://docs.ansible.com/projects/ansible-build-data/#__codelineno-0-15) # For collections stored in a subdirectory: [](https://docs.ansible.com/projects/ansible-build-data/#__codelineno-0-16) collection-directory: "./SUBDIRECTORY" [](https://docs.ansible.com/projects/ansible-build-data/#__codelineno-0-17) # This is an optional field that should only be populated if the collection [](https://docs.ansible.com/projects/ansible-build-data/#__codelineno-0-18) # doesn't include a changelogs/changelog.yaml file. [](https://docs.ansible.com/projects/ansible-build-data/#__codelineno-0-19) # changelog-url: ...` ### The current Ansible major release[¶](https://docs.ansible.com/projects/ansible-build-data/#the-current-ansible-major-release "Permanent link") To add a collection to the next minor release of the current Ansible major version: * Add the collection to the `ansible.in` file in a sub-directory named with a corresponding number. * In the same sub-directory, add the collection and its version range to the `ansible-X.build` file. * In the same sub-directory, add the collection to the `collection-meta.yaml` file. * The maintainer's GitHub user names need to be listed there. * If the collection does not provide a changelog in `changelogs/changelog.yaml`, the URL to the actual changelog needs to be added. Renaming a collection[¶](https://docs.ansible.com/projects/ansible-build-data/#renaming-a-collection "Permanent link") ----------------------------------------------------------------------------------------------------------------------- In some situations, a collection included in Ansible is renamed with its content basically unchanged (up to renaming, adjusting documentation, and potentially other very small changes). In that case, the new collection can be included and the old collection removed if the following procedure is followed. For simplicity, assume that the next minor Ansible release is X.Y.0, and that collection `foo.bar` with latest release a.b.c has been renamed to `baz.bam` with latest release A.B.C. 1. `baz.bam` A.B.C must be compatible to `foo.bar` a.b.c up to renaming plugins. No options must be renamed without backwards compatible aliases, and no defaults or semantics changed. 2. `baz.bam` A.B.C can be added to Ansible X.Y.0. 3. A deprecation warning is added to Ansible X.Y.0's changelog (`deprecated_features`) that `foo.bar` has been renamed to `baz.bam`, that Ansible (X+1).0.0 will start having deprecated redirects from `foo.bar` to `baz.bam`, and that `foo.bar` will be removed from a later major release of Ansible. 4. A new release `foo.bar` (a+1).0.0 is made which contains no more content, but only deprecated redirects to `baz.bam`. Ideally it will have a dependency on `baz.bam` so that users that install `foo.bar` will have working deprecated redirects. 5. Ansible (X+1).0.0 contains both `foo.bar` (a+1).0.0, and either a `baz.bam` A.B'.C' release or a later major release that is still compatible with `foo.bar` a.b.c as specified in 1. 6. `foo.bar` will be dropped from Ansible (X+2).0.0 (needs to be announced in its changelog as `removed_features`). --- # Sending Runner Status and Events to External Systems — Ansible Runner Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/runner/en/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Runner Documentation](https://docs.ansible.com/projects/runner/en/stable/) * [](https://docs.ansible.com/projects/runner/en/latest/) * Sending Runner Status and Events to External Systems * [View page source](https://docs.ansible.com/projects/runner/en/latest/_sources/external_interface.rst.txt) * * * Sending Runner Status and Events to External Systems[](https://docs.ansible.com/projects/runner/en/latest/external_interface/#sending-runner-status-and-events-to-external-systems "Link to this heading") ============================================================================================================================================================================================================ **Runner** can store event and status data locally for retrieval, it can also emit this information via callbacks provided to the module interface. Alternatively **Runner** can be configured to send events to an external system via installable plugins. Currently, there are two example plugins are available. * HTTP Status/Event Emitter Plugin - [ansible-runner-http GitHub repo](https://github.com/ansible/ansible-runner-http) * ZeroMQ Status/Event Emitter Plugin - [ansible-runner-zeromq GitHub repo](https://github.com/ansible/ansible-runner-zeromq) Please refer to respective repos to configure these plugins. Event Structure[](https://docs.ansible.com/projects/runner/en/latest/external_interface/#event-structure "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------- There are two types of events that are emitted via plugins: * status events: These are sent whenever Runner’s status changes (see [Runner.status\_handler](https://docs.ansible.com/projects/runner/en/latest/python_interface/#runnerstatushandler) ) for example: {"status": "running", "runner\_ident": "XXXX" } * ansible events: These are sent during playbook execution for every event received from **Ansible** (see [Playbook and Host Events](https://docs.ansible.com/projects/runner/en/latest/intro/#artifactevents) ) for example: {"runner\_ident": "XXXX", } Writing your own Plugin[](https://docs.ansible.com/projects/runner/en/latest/external_interface/#writing-your-own-plugin "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------- In order to write your own plugin interface and have it be picked up and used by **Runner** there are a few things that you’ll need to do. * Declare the module as a Runner entrypoint in your setup file ([ansible-runner-http has a good example of this](https://github.com/ansible/ansible-runner-http/blob/master/setup.py) ): entry\_points\=('ansible\_runner.plugins': 'modname = your\_python\_package\_name'), * Implement the `status_handler()` and `event_handler()` functions at the top of your package, for example see [ansible-runner-http events.py](https://github.com/ansible/ansible-runner-http/blob/master/ansible_runner_http/events.py) and the `__init__` import [at the top of the module package](https://github.com/ansible/ansible-runner-http/blob/master/ansible_runner_http/__init__.py) After installing this, **Runner** will see the plugin and invoke the functions when status and events are sent. If there are any errors in your plugin they will be raised immediately and **Runner** will fail. --- # Ansible Molecule [Skip to content](https://docs.ansible.com/projects/molecule/#about-ansible-molecule) [](https://github.com/ansible/molecule/blob/main/docs/index.md "Edit this page") [](https://github.com/ansible/molecule/raw/main/docs/index.md "View source of this page") About Ansible Molecule[¶](https://docs.ansible.com/projects/molecule/#about-ansible-molecule "Permanent link") =============================================================================================================== Molecule is an Ansible testing framework designed for developing and testing [Ansible](https://ansible.com/) collections, playbooks, and roles. Molecule leverages standard Ansible features including inventory, playbooks, and collections to provide flexible testing workflows. Test scenarios can target any system or service reachable from Ansible, from containers and virtual machines to cloud infrastructure, hyperscaler services, APIs, databases, and network devices. Molecule can also validate inventory configurations and dynamic inventory sources. Molecule encourages an approach that results in consistently developed Ansible content that is well-written, easily understood and maintained. Molecule supports only the latest two major versions of Ansible (N/N-1). Once installed, the command line can be called using any of the methods below: `[](https://docs.ansible.com/projects/molecule/#__codelineno-0-1) molecule ... [](https://docs.ansible.com/projects/molecule/#__codelineno-0-2) python3 -m molecule ... # python module calling method` Molecule projects also hosts the \[community.molecule\] collection, which contains some filters, plugins, roles and playbooks that can be used by molecule test writers to ease writing tests. Back to top --- # Change detection - antsibull-nox – Antsibull Nox Helper [Skip to content](https://docs.ansible.com/projects/antsibull-nox/change-detection/#change-detection) Change detection[¶](https://docs.ansible.com/projects/antsibull-nox/change-detection/#change-detection "Permanent link") ========================================================================================================================= Antsibull-nox allows to use change detection to run only necessary tests. Change detection requires that you [configure the Version Control System in antsibull-nox.toml](https://docs.ansible.com/projects/antsibull-nox/config-file/#version-control-system-configuration) . You can enable change detection by setting the environment variable `ANTSIBULL_CHANGE_DETECTION` to `true`. Note Not all tests support this. Tests not supporting change detection will simply run completely. Warning Coverage information gathered when change detection is enabled is incomplete. Do not enable change detection if you plan to determine coverages of PRs! Note A quick way to see what is happening is running `antsibull-nox show-changes`. This will show the list of changed files that will be used to determine which tests to run on which files. To run `antsibull-nox show-changes`, you do not need to set `ANTSIBULL_CHANGE_DETECTION`. Detecting which files have been changed, and the base branch[¶](https://docs.ansible.com/projects/antsibull-nox/change-detection/#detecting-which-files-have-been-changed-and-the-base-branch "Permanent link") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- To detect which files have been changed, antsibull-nox asks the configured VCS. It first figures out the differences from the current branch to the configured base branch, and then figures out the local changes that have not yet been committed, and considers untracked files that are not ignored by the VCS. By default, the base branch considered is the main development branch. If that is wrong, you can explicitly configure the base branch by setting the environment variable `ANTSIBULL_BASE_BRANCH`. Note If you invoke antsibull-nox in CI from a Pull/Merge Request and want to use change detection, you should set `ANTSIBULL_BASE_BRANCH` to the base branch of the MR/PR. All common CI systems provide ways to set `ANTSIBULL_BASE_BRANCH` accordingly. Supported tests[¶](https://docs.ansible.com/projects/antsibull-nox/change-detection/#supported-tests "Permanent link") ----------------------------------------------------------------------------------------------------------------------- Right now, the following tests are supported: * All ansible-test tests supported through `antsibull-nox.toml`. * All ansible-test tests supported through `noxfile.py` that explicitly state that they allow change detection. Note Ansible-test only works with git. Additionally the collection's root directory (the directory containing `galaxy.yml` and `antsibull-nox.toml`) must be the repository's root (the directory containing the `.git` subdirectory). The latter restriction is necessary since antsibull-nox copies the repository into a temporary place and cannot consider directories further up. * All `lint` sessions (`formatters`, `codeqa`, `yamllint`, `typing`). * The `extra-checks` session and all its tests. * All tests but `reuse` from the `license-check` session. * The `docs-check` sessions are restricted to changed files (for code-block tests), or skipped if there are no appropriate changed files. --- # Troubleshooting - antsibull-nox – Antsibull Nox Helper [Skip to content](https://docs.ansible.com/projects/antsibull-nox/troubleshooting/#troubleshooting) Troubleshooting[¶](https://docs.ansible.com/projects/antsibull-nox/troubleshooting/#troubleshooting "Permanent link") ====================================================================================================================== Find tips and tricks for common issues. General problems[¶](https://docs.ansible.com/projects/antsibull-nox/troubleshooting/#general-problems "Permanent link") ------------------------------------------------------------------------------------------------------------------------ If you get strange errors when running a session with re-used virtual environment, it could be that your Python version changed or something else broke. It is often a good idea to first try to re-create the virtual environment by simply running the session without `-R` or `-r`: `[](https://docs.ansible.com/projects/antsibull-nox/troubleshooting/#__codelineno-0-1) # Run the lint session and re-create all virtual environments for it [](https://docs.ansible.com/projects/antsibull-nox/troubleshooting/#__codelineno-0-2) nox -e lint [](https://docs.ansible.com/projects/antsibull-nox/troubleshooting/#__codelineno-0-3) pipx run noxfile.py -e lint [](https://docs.ansible.com/projects/antsibull-nox/troubleshooting/#__codelineno-0-4) uv run noxfile.py -e lint` This often resolves the problems. The wrong container engine is used for certain sessions[¶](https://docs.ansible.com/projects/antsibull-nox/troubleshooting/#the-wrong-container-engine-is-used-for-certain-sessions "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ For sessions that require a container engine, antsibull-nox tries to detect the appropriate one: 1. For execution environment sessions (`ee-check`), one of Podman or Docker is determined when the session is started. The behavior can be configured by the environment variable `ANTSIBULL_NOX_CONTAINER_ENGINE`. If set to `podman` or `docker`, that container engine will be used. If set to `auto`, `auto-prefer-docker`, or `auto-prefer-podman`, antsibull-nox will try to find the `podman` or `docker` CLI tools in the execution path and use that information to select the container engine to use. The default value is `auto`. 2. For ansible-test sessions, ansible-test itself detects whether to use Podman or Docker. By default it prefers `docker` if both `docker` and `podman` are available. If the environment variable `ANSIBLE_TEST_PREFER_PODMAN` is set to a non-empty value, it will prefer `podman` over `docker`. If `ANSIBLE_TEST_PREFER_PODMAN` is not set, but `ANTSIBULL_NOX_CONTAINER_ENGINE` is set to something other than `auto`, `ANSIBLE_TEST_PREFER_PODMAN` will be set to `""` (that is, prefer Docker) or `1` (that is, prefer Podman) accordingly. Differences between CI and local runs[¶](https://docs.ansible.com/projects/antsibull-nox/troubleshooting/#differences-between-ci-and-local-runs "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------------------------------ If you notice that your local tests report different results than CI, re-creating the virtual environments can also help. Sometimes linters have newer versions with more checks that are running in CI, while your local virtual environments are still using an older version. Avoid sudden CI breakages due to new versions[¶](https://docs.ansible.com/projects/antsibull-nox/troubleshooting/#avoid-sudden-ci-breakages-due-to-new-versions "Permanent link") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- As a collection maintainer, if you prefer that new tests do not suddenly appear, you should use the `*_package` parameters to the various `antsibull.add_*()` function calls to pin specific versions of the linters. Note If you pin specific versions, you yourself are responsible for bumping these versions from time to time. Change detection does not work[¶](https://docs.ansible.com/projects/antsibull-nox/troubleshooting/#change-detection-does-not-work "Permanent link") ---------------------------------------------------------------------------------------------------------------------------------------------------- 1. Did you configure [the Version Control System in antsibull-nox.toml](https://docs.ansible.com/projects/antsibull-nox/config-file/#version-control-system-configuration) ? 2. Did you set the environment variable `ANTSIBULL_CHANGE_DETECTION` to `true`? 3. Did you set `ANTSIBULL_BASE_BRANCH` to the base branch, if it is not the main development branch of your collection? 4. Try to run `antsibull-nox show-changes` to see what change detection finds. 5. Does the test you run actually [support change detection](https://docs.ansible.com/projects/antsibull-nox/change-detection/#supported-tests) ? --- # Community - antsibull-nox – Antsibull Nox Helper [Skip to content](https://docs.ansible.com/projects/antsibull-nox/community/#community) Community[¶](https://docs.ansible.com/projects/antsibull-nox/community/#community "Permanent link") ==================================================================================================== We welcome your feedback, questions and ideas. Here's how to reach the community. Forum[¶](https://docs.ansible.com/projects/antsibull-nox/community/#forum "Permanent link") -------------------------------------------------------------------------------------------- Join the [Ansible Forum](https://forum.ansible.com/) as a single starting point and our default communication platform for questions and help, development discussions, events, and much more. [Register on the Forum](https://forum.ansible.com/signup?) to join the community. Search by categories and tags to find interesting topics or start a new one; subscribe only to topics you need! * [Posts tagged with 'antsibull'](https://forum.ansible.com/tag/antsibull) : subscribe to participate in project-related conversations. * [Social Spaces](https://forum.ansible.com/c/chat/4) : gather and interact with fellow enthusiasts. * [News & Announcements](https://forum.ansible.com/c/news/5) : track project-wide announcements including social events. The [Bullhorn newsletter](https://docs.ansible.com/ansible/devel/community/communication.html#the-bullhorn) , which is used to announce releases and important changes, can also be found here. For more information on the forum navigation, see the [Navigating the Ansible forum](https://forum.ansible.com/t/navigating-the-ansible-forum-tags-categories-and-concepts/39) post. Matrix[¶](https://docs.ansible.com/projects/antsibull-nox/community/#matrix "Permanent link") ---------------------------------------------------------------------------------------------- For real-time interactions, join the [#antsibull:ansible.com Matrix room](https://matrix.to/#/#antsibull:ansible.com) . See the [Ansible communication guide](https://docs.ansible.com/ansible/devel/community/communication.html#real-time-chat) for more information on Matrix. --- # Installation - Ansible Navigator Documentation [Skip to content](https://docs.ansible.com/projects/navigator/installation/#linux) [](https://github.com/ansible/ansible-navigator/blob/main/docs/installation.md "Edit this page") Installing ansible-navigator with execution environment support[¶](https://docs.ansible.com/projects/navigator/installation/#installing-ansible-navigator-with-execution-environment-support "Permanent link") =============================================================================================================================================================================================================== * [Linux](https://docs.ansible.com/projects/navigator/installation/#linux) * [Requirements](https://docs.ansible.com/projects/navigator/installation/#requirements) * [Install the desired container engine for execution environment support](https://docs.ansible.com/projects/navigator/installation/#install-the-desired-container-engine-for-execution-environment-support) * [Install ansible-navigator](https://docs.ansible.com/projects/navigator/installation/#install-ansible-navigator) * [macOS](https://docs.ansible.com/projects/navigator/installation/#macos) * [Requirements (macos)](https://docs.ansible.com/projects/navigator/installation/#requirements-macos) * [Install the desired container engine for execution environment support (macos)](https://docs.ansible.com/projects/navigator/installation/#install-the-desired-container-engine-for-execution-environment-support-macos) * [Install ansible-navigator (macos)](https://docs.ansible.com/projects/navigator/installation/#install-ansible-navigator-macos) * [Windows with WSL2](https://docs.ansible.com/projects/navigator/installation/#windows-with-wsl2) * [Requirements (windows)](https://docs.ansible.com/projects/navigator/installation/#requirements-windows) * [Setup Windows Subsystem for Linux 2 with Ubuntu](https://docs.ansible.com/projects/navigator/installation/#setup-windows-subsystem-for-linux-2-with-ubuntu) * [Install the desired container engine for execution environment support (windows)](https://docs.ansible.com/projects/navigator/installation/#install-the-desired-container-engine-for-execution-environment-support-windows) * [Install ansible-navigator (windows)](https://docs.ansible.com/projects/navigator/installation/#install-ansible-navigator-windows) Recommendation The **recommended** approach to install `ansible-navigator` is using the `ansible-dev-tools` package. [Ansible Development Tools](https://ansible.readthedocs.io/projects/dev-tools/) aims to streamline the setup and usage of several tools needed in order to create [Ansible](https://www.ansible.com/) content. It combines critical Ansible development packages into a unified Python package. `[](https://docs.ansible.com/projects/navigator/installation/#__codelineno-0-1) # This also installs ansible-core if it is not already installed [](https://docs.ansible.com/projects/navigator/installation/#__codelineno-0-2) pip3 install ansible-dev-tools` Linux[¶](https://docs.ansible.com/projects/navigator/installation/#linux "Permanent link") ------------------------------------------------------------------------------------------- ### Requirements[¶](https://docs.ansible.com/projects/navigator/installation/#requirements "Permanent link") * Either [podman](https://podman.io/) or [Docker for Linux](https://docs.docker.com/engine/install/) * Internet access (during initial installation) ### Install the desired container engine for execution environment support[¶](https://docs.ansible.com/projects/navigator/installation/#install-the-desired-container-engine-for-execution-environment-support "Permanent link") * Follow the [podman installation instructions](https://podman.io/getting-started/installation) for the appropriate distribution. * Follow the [Docker for Linux installation instructions](https://docs.docker.com/engine/install/) for the appropriate distribution. ### Install ansible-navigator[¶](https://docs.ansible.com/projects/navigator/installation/#install-ansible-navigator "Permanent link") 1. Install the python package manager using the system package installer (e.g.): `[](https://docs.ansible.com/projects/navigator/installation/#__codelineno-1-1) sudo dnf install python3-pip` 2. Install ansible-navigator: `[](https://docs.ansible.com/projects/navigator/installation/#__codelineno-2-1) python3 -m pip install ansible-navigator --user` 3. Add the installation path to the user shell initialization file (e.g.): `[](https://docs.ansible.com/projects/navigator/installation/#__codelineno-3-1) echo 'export PATH=$HOME/.local/bin:$PATH' >> ~/.profile` 4. Refresh the PATH (e.g.): `[](https://docs.ansible.com/projects/navigator/installation/#__codelineno-4-1) source ~/.profile` 5. Launch ansible-navigator: `[](https://docs.ansible.com/projects/navigator/installation/#__codelineno-5-1) ansible-navigator` 6. `ansible-navigator` triggers a one-time download of the demo execution-environment image. macOS[¶](https://docs.ansible.com/projects/navigator/installation/#macos "Permanent link") ------------------------------------------------------------------------------------------- ### Requirements (macos)[¶](https://docs.ansible.com/projects/navigator/installation/#requirements-macos "Permanent link") * [Docker Desktop for Mac](https://hub.docker.com/editions/community/docker-ce-desktop-mac) or [Podman on macOS](https://podman.io/docs/installation#macos) * macOS command line developer tools * Internet access (during initial installation) ### Install the desired container engine for execution environment support (macos)[¶](https://docs.ansible.com/projects/navigator/installation/#install-the-desired-container-engine-for-execution-environment-support-macos "Permanent link") * [Docker Desktop for Mac](https://hub.docker.com/editions/community/docker-ce-desktop-mac) installation instructions * [Podman on MacOS](https://podman.io/docs/installation#macos) installation instructions ### Install ansible-navigator (macos)[¶](https://docs.ansible.com/projects/navigator/installation/#install-ansible-navigator-macos "Permanent link") 1. Install the command line developer tools and proceed with the installation if prompted. `[](https://docs.ansible.com/projects/navigator/installation/#__codelineno-6-1) xcode-select --install` 2. Install ansible-navigator: `[](https://docs.ansible.com/projects/navigator/installation/#__codelineno-7-1) pip3 install ansible-navigator --user` 3. Add the installation path to the PATH, using the installed Python version: `[](https://docs.ansible.com/projects/navigator/installation/#__codelineno-8-1) echo 'export PATH=$HOME/Library/Python/3.10/bin:$PATH' >> ~/.zprofile` 4. Refresh the PATH: `[](https://docs.ansible.com/projects/navigator/installation/#__codelineno-9-1) source ~/.zprofile` 5. Launch ansible-navigator: `[](https://docs.ansible.com/projects/navigator/installation/#__codelineno-10-1) ansible-navigator` 6. `ansible-navigator` triggers a one-time download of the demo execution-environment image. Windows with WSL2[¶](https://docs.ansible.com/projects/navigator/installation/#windows-with-wsl2 "Permanent link") ------------------------------------------------------------------------------------------------------------------- ### Requirements (windows)[¶](https://docs.ansible.com/projects/navigator/installation/#requirements-windows "Permanent link") * [Windows Subsystem for Linux 2](https://docs.microsoft.com/en-us/windows/wsl/install-win10) * Either [podman](https://podman.io/) or [Docker Desktop for Windows](https://hub.docker.com/editions/community/docker-ce-desktop-windows) * Internet access (during initial installation) ### Setup Windows Subsystem for Linux 2 with Ubuntu[¶](https://docs.ansible.com/projects/navigator/installation/#setup-windows-subsystem-for-linux-2-with-ubuntu "Permanent link") 1. Install [Windows Subsystem for Linux 2](https://docs.microsoft.com/en-us/windows/wsl/install-win10) . 2. Install the latest [Ubuntu](https://ubuntu.com/) LTS Linux distribution from the Microsoft store. 3. Open PowerShell and set the default WSL 2 distribution: `[](https://docs.ansible.com/projects/navigator/installation/#__codelineno-11-1) wsl --set-default ubuntu` 4. Launch the Ubuntu\] virtual machine from the Windows menu and complete the initial set-up. 5. From the Ubuntu terminal, create the `/dev/mqueue` directory: `[](https://docs.ansible.com/projects/navigator/installation/#__codelineno-12-1) sudo mkdir /dev/mqueue` ### Install the desired container engine for execution environment support (windows)[¶](https://docs.ansible.com/projects/navigator/installation/#install-the-desired-container-engine-for-execution-environment-support-windows "Permanent link") * Installation instructions for [podman](https://podman.io/) on Ubuntu LTS. !!! notice `The podman package is available in the official repositories for Ubuntu 20.10 and newer. Since interim releases of Ubuntu are not available on the Microsoft Store for WSL the [Kubic project] package can be used.` 1. Update the ubuntu package index: `[](https://docs.ansible.com/projects/navigator/installation/#__codelineno-13-1) sudo apt update` 2. Install system dependencies for [podman](https://podman.io/) : `[](https://docs.ansible.com/projects/navigator/installation/#__codelineno-14-1) apt-get install curl wget gnupg2` 3. Source the Ubuntu release: `[](https://docs.ansible.com/projects/navigator/installation/#__codelineno-15-1) source /etc/os-release` 4. Add the podman repository: `[](https://docs.ansible.com/projects/navigator/installation/#__codelineno-16-1) sudo sh -c "echo 'deb http://download.opensuse.org/repositories/devel:/kubic:/libcontainers:/stable/xUbuntu_${VERSION_ID}/ /' > /etc/apt/sources.list.d/devel:kubic:libcontainers:stable.list"` 5. Download the GPG key: `[](https://docs.ansible.com/projects/navigator/installation/#__codelineno-17-1) wget -nv https://download.opensuse.org/repositories/devel:kubic:libcontainers:stable/xUbuntu_${VERSION_ID}/Release.key -O- | sudo apt-key add -` 6. Update using the new repository: `[](https://docs.ansible.com/projects/navigator/installation/#__codelineno-18-1) sudo apt-get update` 7. Install podman: `[](https://docs.ansible.com/projects/navigator/installation/#__codelineno-19-1) sudo apt-get install podman` 8. Follow the [Docker Desktop for Windows](https://hub.docker.com/editions/community/docker-ce-desktop-windows) installation instructions (if podman was not installed above) 9. Be sure to complete the [Manage Docker as a non-root user](https://docs.docker.com/engine/install/linux-postinstall/) steps. ### Install ansible-navigator (windows)[¶](https://docs.ansible.com/projects/navigator/installation/#install-ansible-navigator-windows "Permanent link") From the Ubuntu terminal: 1. Ensure the `/dev/mqueue` directory exists: `[](https://docs.ansible.com/projects/navigator/installation/#__codelineno-20-1) sudo mkdir /dev/mqueue` 2. Install the python package manager: `[](https://docs.ansible.com/projects/navigator/installation/#__codelineno-21-1) sudo apt install python3-pip` 3. Install ansible-navigator: `[](https://docs.ansible.com/projects/navigator/installation/#__codelineno-22-1) python3 -m pip install ansible-navigator --user` 4. Add the installation path to the user shell initialization file: `[](https://docs.ansible.com/projects/navigator/installation/#__codelineno-23-1) echo 'export PATH=$HOME/.local/bin:$PATH' >> ~/.profile` 5. Refresh the PATH: `[](https://docs.ansible.com/projects/navigator/installation/#__codelineno-24-1) source ~/.profile` 6. Launch ansible-navigator: `[](https://docs.ansible.com/projects/navigator/installation/#__codelineno-25-1) ansible-navigator` 7. `ansible-navigator` triggers a one-time download of the demo execution-environment image. --- # Ansible Development Tools Documentation [Skip to content](https://docs.ansible.com/projects/dev-tools/#ansible-development-tools-adt) [](https://github.com/ansible/ansible-dev-tools/blob/main/docs/index.md "Edit this page") [](https://github.com/ansible/ansible-dev-tools/raw/main/docs/index.md "View source of this page") Ansible Development Tools (ADT)[¶](https://docs.ansible.com/projects/dev-tools/#ansible-development-tools-adt "Permanent link") ================================================================================================================================ Introduction[¶](https://docs.ansible.com/projects/dev-tools/#introduction "Permanent link") -------------------------------------------------------------------------------------------- Ansible Development Tools or ADT for short, aims to streamline the setup and usage of several tools needed to create [Ansible](https://www.ansible.com/) content. When it comes to creating automation content using Ansible, there are several packages available that can help users in different parts of the content-creating journey. From bootstrapping new projects, all the way to ensuring content follows best practices and verifying it behaves as intended via well-established test frameworks. Key Features[¶](https://docs.ansible.com/projects/dev-tools/#key-features "Permanent link") -------------------------------------------------------------------------------------------- * All-in-One Ansible Toolkit: ansible-dev-tools combines critical Ansible development packages into a unified Python package called [ansible-dev-tools](https://pypi.org/project/ansible-dev-tools/) . * Simplified Ansible Automation: ansible-dev-tools focuses on crafting your automation scenarios and workflows with speed by reducing boilerplate code without dealing with the intricacies of managing and integrating different Ansible libraries. * Promote and provide \[test isolation\] from system and user environments. For those looking for an IDE-based experience, we also recommend you get familiar with the [Ansible extension for VSCode](https://marketplace.visualstudio.com/items?itemName=redhat.ansible) . Included Packages[¶](https://docs.ansible.com/projects/dev-tools/#included-packages "Permanent link") ------------------------------------------------------------------------------------------------------ The curated list of tools installed as part of the Ansible Development Tools includes: * [ansible-builder](https://ansible.readthedocs.io/projects/builder/) : Ansible Builder automates the process of building execution environments using the schemas and tooling defined in various Ansible Collections and by the user. * [ansible-core](https://ansible.readthedocs.io/projects/ansible/) : Ansible is a radically simple IT automation platform that makes your applications and systems easier to deploy and maintain. Automate everything from code deployment to network configuration to cloud management, in a language that approaches plain English, using SSH, with no agents to install on remote systems. * [ansible-creator](https://ansible.readthedocs.io/projects/creator/) : The fastest way to generate all your ansible content! * [ansible-dev-environment](https://ansible.readthedocs.io/projects/dev-environment/) : A pip-like install for Ansible collections. * [ansible-lint](https://ansible.readthedocs.io/projects/lint/) : Checks playbooks for practices and behavior that could potentially be improved. * [ansible-navigator](https://ansible.readthedocs.io/projects/navigator/) A text-based user interface (TUI) for Ansible. * [ansible-sign](https://ansible.readthedocs.io/projects/sign/) : Utility for signing and verifying Ansible project directory contents. * [molecule](https://ansible.readthedocs.io/projects/molecule/) : Molecule aids in the development and testing of Ansible content: collections, playbooks and roles * [pytest-ansible](https://ansible.readthedocs.io/projects/pytest-ansible/) : A pytest plugin that enables the use of ansible in tests, enables the use of pytest as a collection unit test runner, and exposes molecule scenarios using a pytest fixture. * [tox-ansible](https://ansible.readthedocs.io/projects/tox-ansible/) : The tox-ansible plugin dynamically creates a full matrix of python interpreter and ansible-core version environments for running integration, sanity, and unit for an ansible collection both locally and in a Github action. tox virtual environments are leveraged for collection building, collection installation, dependency installation, and testing. Getting started[¶](https://docs.ansible.com/projects/dev-tools/#getting-started "Permanent link") -------------------------------------------------------------------------------------------------- To get started, follow the [installation](https://docs.ansible.com/projects/dev-tools/installation/) steps to get ansible-dev-tools setup and check [User Guide](https://docs.ansible.com/projects/dev-tools/user-guide/) for more details. Community[¶](https://docs.ansible.com/projects/dev-tools/#community "Permanent link") -------------------------------------------------------------------------------------- Questions, feedback, or contributions? Join the Ansible community on [Matrix](https://matrix.to/#/#devtools:ansible.com) or [open an issue](https://github.com/ansible/ansible-dev-tools/issues/new) . We're dedicated to supporting your Ansible automation journey! For more details on how to interact with our community, please visit the [Ansible Communication](https://docs.ansible.com/ansible/latest/community/communication.html) page. Back to top --- # Philosophy - Ansible Lint Documentation [Skip to content](https://docs.ansible.com/projects/lint/philosophy/#philosophy-of-ansible-lint) [](https://github.com/ansible/ansible-lint/blob/main/docs/philosophy.md "Edit this page") [](https://github.com/ansible/ansible-lint/raw/main/docs/philosophy.md "View source of this page") Philosophy of ansible-lint[¶](https://docs.ansible.com/projects/lint/philosophy/#philosophy-of-ansible-lint "Permanent link") ============================================================================================================================== Ansible **playbooks, roles, and collections** should read like documentation, be production ready, unambiguous, and provide consistent results. `Ansible-lint` should be considered a trusted advisor, helping ansible content creators write and package high-quality Ansible content. While not all rules may be applicable in all situations, they should be followed whenever possible. The goal of `ansible-lint` is to ensure that content created by different people has a similar look and feel. This makes the adoption and use of Ansible content easier in the community and enterprise. By keeping the number of configurable features at a minimum, consistent outcomes between authors can be achieved. History and the future[¶](https://docs.ansible.com/projects/lint/philosophy/#history-and-the-future "Permanent link") ---------------------------------------------------------------------------------------------------------------------- `ansible-lint` is almost a decade old, and its current list of rules is the result of a collaboration between many people. The tool originated as a community project and is currently part of the Ansible Galaxy submission and validation process. In the future, it will be an official component of the Red Hat Ansible Automation Platform, used during the collections certification process and the recommended Ansible content linter for Red Hat customers. Starting in 2022, additional rules will be added that help content creators ready their content for production use. It will be through the use of ansible-lint and these rules, developers can have confidence their playbooks, roles, and task files are easy to understand and produce consistent results when run against anything, from servers in a home lab to mission-critical systems in the cloud. Style and formatting[¶](https://docs.ansible.com/projects/lint/philosophy/#style-and-formatting "Permanent link") ------------------------------------------------------------------------------------------------------------------ The focus of Ansible content creators should be on automation, outcomes and readability, rather than style or formatting. This is why we follow the same concepts as other code formatting tools like [black](https://github.com/psf/black) and [prettier](https://prettier.io/) . Adoption of `ansible-lint` will save time by keeping reviews focused on the quality of the content and less so on the nuances of formatting and style. As code formatting is not an art, we can save your project time and effort by applying a standardized code style and formatting. Q&A[¶](https://docs.ansible.com/projects/lint/philosophy/#qa "Permanent link") ------------------------------------------------------------------------------- ### Why does ansible-lint not accept all valid ansible syntax?[¶](https://docs.ansible.com/projects/lint/philosophy/#why-does-ansible-lint-not-accept-all-valid-ansible-syntax "Permanent link") `ansible-core` continues to mature while maintaining backward compatibility with early versions. `ansible-lint` has never intended to support the whole historical Ansible language syntax variations, but instead only the best of it. It supports a broad vocabulary of keywords and styles. Over time, changes in the language have led to an improved experience for authors and consumers of Ansible content. The rules in `ansible-lint` suggest the use of these patterns. It is these usage patterns that are written as rules in `ansible-lint`, leading to improved readability of **playbooks, roles**, and **collections**. The linter will always be more restrictive and opinionated regarding what it accepts. It is part of its design. We are not forced to keep the same backward compatibility level as Ansible, so we can tell people to avoid specific syntax for various reasons, such as being deprecated, unsafe, or hard to maintain. Based on the extensive history of `ansible-lint` and user feedback, it notifies you about discouraged practices, sometimes before `ansible-core` starts doing so. ### What if I do not agree with a specific rule?[¶](https://docs.ansible.com/projects/lint/philosophy/#what-if-i-do-not-agree-with-a-specific-rule "Permanent link") We recognize that some projects will find at least one rule that might not suit their needs. Use the `skip_list` feature to temporarily bypass that rule until you have time to update your Ansible content. ### Who decides which best practices get adopted in ansible-lint?[¶](https://docs.ansible.com/projects/lint/philosophy/#who-decides-which-best-practices-get-adopted-in-ansible-lint "Permanent link") The main source of new ideas was and remains our community. Before proposing a change, check with a few other Ansible users that work on different projects and see if they find it useful or not. It is better to get enough relevant feedback on our discussion forum before starting to implement new rules. If the proposed rule appears popular and does not conflict with existing rules, a core (maintainer) will tell you that the proposed rule can be added to ansible-lint, so you can start working on it without fear of rejection. The core team will decide on how a new rule will be added. Usually, they are added as experimental (warnings only) or even as opt-ins, being made implicit only when a major version is released. ### Do I need to pass all rules to get my collection certified?[¶](https://docs.ansible.com/projects/lint/philosophy/#do-i-need-to-pass-all-rules-to-get-my-collection-certified "Permanent link") Not really. The certification process is likely to use only a subset of rules. At this time, we are working on building that list. ### Why do many official Ansible docs examples fail to pass linting?[¶](https://docs.ansible.com/projects/lint/philosophy/#why-do-many-official-ansible-docs-examples-fail-to-pass-linting "Permanent link") Most of the official examples are written to exemplify specific features, and some might conflict with our rules. Still, we plan to include linting of official examples in the future and add specific exclusions where needed, making it more likely that a copy/paste from the docs will not raise a bunch of linter violations. ### Why does ansible-lint require an Ansible version newer than what I use in production?[¶](https://docs.ansible.com/projects/lint/philosophy/#why-does-ansible-lint-require-an-ansible-version-newer-than-what-i-use-in-production "Permanent link") Use `ansible-lint` as a **static analysis** tool for your content. You can run it with a version of ansible that is different than what you use in production. This helps you prepare your content for the future, so don't be afraid of using it in such a way. Back to top --- # DevSpaces - Ansible Development Tools Documentation [Skip to content](https://docs.ansible.com/projects/dev-tools/devspaces/#ansible-development-using-openshift-dev-spaces) [](https://github.com/ansible/ansible-dev-tools/blob/main/docs/devspaces.md "Edit this page") [](https://github.com/ansible/ansible-dev-tools/raw/main/docs/devspaces.md "View source of this page") Ansible Development using OpenShift Dev Spaces[¶](https://docs.ansible.com/projects/dev-tools/devspaces/#ansible-development-using-openshift-dev-spaces "Permanent link") ========================================================================================================================================================================== Ansible Development Tools can also be used using OpenShift Dev Spaces. If you are not already accustomed with them, you can start right now by using the free [OpenShift developer Sandbox](https://docs.ansible.com/projects/dev-tools/devspaces/) . In fact this repository is already configured to be used with OpenShift Dev Spaces and by clicking [![Contribute](https://www.eclipse.org/che/contribute.svg)](https://devspaces.apps.sandbox-m3.1530.p1.openshiftapps.com/dashboard/#/load-factory?url=https%3A%2F%2Fgithub.com%2Fansible%2Fansible-dev-tools) , you can open it inside the OpenShift Dev Spaces and may make your own contribution. You can test loading the OpenShift Dev Space defined inside [redhat-developer-demos](https://github.com/redhat-developer-demos/ansible-devspaces-demo/tree/devspaces-3-rhel-9) repository by clicking [![Developer Workspace](https://www.eclipse.org/che/contribute.svg)](https://workspaces.openshift.com/f?url=https://github.com/redhat-developer-demos/ansible-devspaces-demo/tree/devspaces-3-rhel-9) This repository provides a development environment for Ansible playbook creation, testing with Molecule, and ansible-lint checks using OpenShift Dev Spaces. Summary[¶](https://docs.ansible.com/projects/dev-tools/devspaces/#summary "Permanent link") -------------------------------------------------------------------------------------------- This repository contains a `devfile.yaml` file, which defines the development environment for Ansible. The DevSpace created using this `devfile` provides the necessary tools and dependencies for Ansible playbook development, testing with Molecule, and linting with ansible-lint. This is designed to be used in environments where developers do not have easy access to linux systems from which to develop ansible automation content, but do have OpenShift. The `devfile.yaml` includes configurations for: * Ansible * Molecule (testing framework for Ansible roles) * Ansible Lint (tool for checking best practices and potential issues in Ansible code) You can use the provided DevSpace to start working on your Ansible projects immediately, without worrying about setting up the development environment manually. Setting up OpenShift DevSpaces[¶](https://docs.ansible.com/projects/dev-tools/devspaces/#setting-up-openshift-devspaces "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------ To get started with OpenShift Dev Spaces, refer to the [OpenShift Dev Spaces documentation](https://access.redhat.com/documentation/en-us/red_hat_openshift_dev_spaces/3.5/html/administration_guide/index) for detailed instructions on setting up your development environment and creating your DevSpaces. Base Image Of Devfile[¶](https://docs.ansible.com/projects/dev-tools/devspaces/#base-image-of-devfile "Permanent link") ------------------------------------------------------------------------------------------------------------------------ [Community Ansible Dev Spaces Image](https://github.com/ansible/community-ansible-devspaces-image) is used as an image for Ansible development and it's defined in the `devfile.yaml`. ### GitHub OAuth2[¶](https://docs.ansible.com/projects/dev-tools/devspaces/#github-oauth2 "Permanent link") The instructions for configuring OAuth2 for GitHub can be found at the following link: [https://access.redhat.com/documentation/en-us/red\_hat\_openshift\_dev\_spaces/3.5/html/administration\_guide/configuring-devspaces#configuring-oauth-2-for-github](https://access.redhat.com/documentation/en-us/red_hat_openshift_dev_spaces/3.5/html/administration_guide/configuring-devspaces#configuring-oauth-2-for-github) Once the secret is in place, restart the main Dev Space container. Any workspace created before this step is complete will NOT have access to GitHub OAuth, and will need to be deleted and recreated to get access. NOTE: You will still need to configured your name/email globally the first time your workspace is accessed (or once for each new workspace, if you choose not to configure globally). `[](https://docs.ansible.com/projects/dev-tools/devspaces/#__codelineno-0-1) git config --global user.name "Homer Simpson" [](https://docs.ansible.com/projects/dev-tools/devspaces/#__codelineno-0-2) git config --global user.email homer@springfieldpower.com` Sample Molecule Testing Role[¶](https://docs.ansible.com/projects/dev-tools/devspaces/#sample-molecule-testing-role "Permanent link") -------------------------------------------------------------------------------------------------------------------------------------- A sample role has been provided in the collections/ansible\_collections/sample\_namespace/sample\_collection/roles/backup\_file directory to experiment with Test Driven Development using Molecule and OpenShift DevSpaces. A molecule verifier has been configured to test that the role functions as expected. ### Automation requirements[¶](https://docs.ansible.com/projects/dev-tools/devspaces/#automation-requirements "Permanent link") 1. Make a backup of a file identified using the backup\_file\_source variable 2. The backup should be stored in the directory identified by the backup\_file\_dest\_folder variable 3. If the backup directory doesn't exist, it should be created and writable 4. The backup file should have a suffix appended such as '.bak' which is identified by the backup\_file\_dest\_suffix variable ### To begin development against the backup\_file role[¶](https://docs.ansible.com/projects/dev-tools/devspaces/#to-begin-development-against-the-backup_file-role "Permanent link") 1. Click the three horizontal bar icon in the top left of the window and select 'Terminal' -> 'New Terminal' 2. Click into the terminal window 3. Change directory into backup file role `cd collections/ansible_collections/sample_namespace/sample_collection/extensions/` 4. Run `molecule create`. This will start a test pod for the automation to run against (defined in roles/backup\_file/molecule/default/molecule.yml). 5. Run `molecule list` and `oc get pods` to view the test instance that was created 6. Run `molecule verify` to run the verification against the test pod and see the failures to help guide the tasks necessary in the role. 7. Run `molecule converge` to apply the role to the pod. This will create a backup of a file in the backup destination folder with a suffix appended. 8. Run `molecule converge` to execute the role against the test instance, and `molecule verify` to see if any tests are still failing. Repeat this until all tests pass. To reset your test pod back to a fresh instance you can run `molecule destroy` and then `molecule create` to recreate it. To run the full molecule test without stepping through each stage, run `molecule test`. Contributing[¶](https://docs.ansible.com/projects/dev-tools/devspaces/#contributing "Permanent link") ------------------------------------------------------------------------------------------------------ Contributions to this repository are welcome! If you find any issues or have suggestions for improvements, feel free to open an issue with [Red Hat](https://issues.redhat.com/projects/CRW/issues) . Code of Conduct[¶](https://docs.ansible.com/projects/dev-tools/devspaces/#code-of-conduct "Permanent link") ------------------------------------------------------------------------------------------------------------ We ask all of our community members and contributors to adhere to the [Ansible code of conduct](http://docs.ansible.com/ansible/latest/community/code_of_conduct.html) . If you have questions or need assistance, please reach out to our community team at [codeofconduct@ansible.com](mailto:codeofconduct@ansible.com) Back to top --- # Execution environment definition — Ansible Builder Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/builder/en/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Builder Documentation](https://docs.ansible.com/projects/builder/en/latest/) * [](https://docs.ansible.com/projects/builder/en/latest/) * Execution environment definition * [View page source](https://docs.ansible.com/projects/builder/en/latest/_sources/definition.rst.txt) * * * Execution environment definition[](https://docs.ansible.com/projects/builder/en/latest/definition/#execution-environment-definition "Link to this heading") ============================================================================================================================================================= You define the content of your execution environment in a YAML file. By default, this file is called `execution-environment.yml` or `execution-environment.yaml`. This file tells Ansible Builder how to create the build instruction file (`Containerfile` for Podman, `Dockerfile` for Docker) and build context for your container image. Note This page documents the definition schema for Ansible Builder 3.x. If you are running an older version of Ansible Builder, you need an older schema version. Please consult older versions of the docs for more information. We recommend using version 3, which is more configurable and functional than previous versions. [Overview](https://docs.ansible.com/projects/builder/en/latest/definition/#id8) [](https://docs.ansible.com/projects/builder/en/latest/definition/#overview "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The Ansible Builder 3.x execution environment definition file accepts seven top-level sections: * additional\_build\_files * additional\_build\_steps * build\_arg\_defaults * dependencies * images * options * version [Version 3 sample files](https://docs.ansible.com/projects/builder/en/latest/definition/#id9) [](https://docs.ansible.com/projects/builder/en/latest/definition/#version-3-sample-files "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Below are some sample version 3 EE files. To use Ansible Builder 3.x, you must specify the schema version. If your EE file does not specify `version: 3`, Ansible Builder will assume you want version 1. This first simple example should successfully build an execution environment using the most recent `ubi9` base image and the most recently compatible versions of `ansible-core` and `ansible-runner` for that image. \--- version: 3 images: base\_image: name: docker.io/redhat/ubi9:latest dependencies: ansible\_core: package\_pip: ansible-core ansible\_runner: package\_pip: ansible-runner The second example below is more detailed and is not usable without modification and/or the creation of supporting requirements and extra files, but does demonstrate more complete EE file syntax. \--- version: 3 build\_arg\_defaults: ANSIBLE\_GALAXY\_CLI\_COLLECTION\_OPTS: '--pre' dependencies: ansible\_core: package\_pip: ansible-core==2.14.4 ansible\_runner: package\_pip: ansible-runner galaxy: requirements.yml python: \- six \- psutil system: bindep.txt exclude: python: \- docker system: \- python3-Cython images: base\_image: name: docker.io/redhat/ubi9:latest \# NOTE: Ansible Builder requires RPM-based images (those using dnf package management). \# Other RPM-based base images that should work: \# - quay.io/rockylinux/rockylinux:9 \# - quay.io/centos/centos:stream9 \# - registry.fedoraproject.org/fedora:38 \# - registry.redhat.io/ansible-automation-platform-23/ee-minimal-rhel8:latest \# (needs an account) \# Non-RPM images (Debian, Ubuntu, Alpine, etc.) are not supported. \# Custom package manager path for the RHEL based images \# options: \# package\_manager\_path: /usr/bin/microdnf additional\_build\_files: \- src: files/ansible.cfg dest: configs additional\_build\_steps: prepend\_base: \- RUN echo This is a prepend base command! \# Enable Non-default stream before packages provided by it can be installed. (optional) \# - RUN $PKGMGR module enable postgresql:15 -y \# - RUN $PKGMGR install -y postgresql prepend\_galaxy: \- COPY \_build/configs/ansible.cfg /etc/ansible/ansible.cfg prepend\_final: | RUN whoami RUN cat /etc/os-release append\_final: \- RUN echo This is a post-install command! \- RUN ls -la /etc [Configuration options](https://docs.ansible.com/projects/builder/en/latest/definition/#id10) [](https://docs.ansible.com/projects/builder/en/latest/definition/#configuration-options "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You may use the configuration YAML keys listed here in your v3 execution environment definition file. ### [additional\_build\_files](https://docs.ansible.com/projects/builder/en/latest/definition/#id11) [](https://docs.ansible.com/projects/builder/en/latest/definition/#additional-build-files "Link to this heading") Specifies files to be added to the build context directory. These can then be referenced or copied by additional\_build\_steps during any build stage. The format is a list of dictionary values, each with a `src` and `dest` key and value. Each list item must be a dictionary containing the following (non-optional) keys: > `src` > > Specifies the source file(s) to copy into the build context directory. This may either be an absolute path (e.g., `/home/user/.ansible.cfg`), or a path that is relative to the execution environment file. Relative paths may be a glob expression matching one or more files (e.g. `files/*.cfg`). Note that an absolute path may _not_ include a regular expression. If `src` is a directory, the entire contents of that directory are copied to `dest`. > > `dest` > > Specifies a subdirectory path underneath the `_build` subdirectory of the build context directory that should contain the source file(s) (e.g., `files/configs`). This may not be an absolute path or contain `..` within the path. This directory will be created for you if it does not exist. ### [additional\_build\_steps](https://docs.ansible.com/projects/builder/en/latest/definition/#id12) [](https://docs.ansible.com/projects/builder/en/latest/definition/#additional-build-steps "Link to this heading") Specifies custom build commands for any build phase. These commands will be inserted directly into the build instruction file for the container runtime (e.g., Containerfile or Dockerfile). The commands must conform to any rules required by the containerization tool. You can add build steps before or after any stage of the image creation process. For example, if you need `git` to be installed before you install your dependencies, you can add a build step at the end of the `base` build stage. Below are the valid keys for this section. Each supports either a multi-line string, or a list of strings. > `prepend_base` > > Commands to insert before building of the base image. > > `append_base` > > Commands to insert after building of the base image. > > `prepend_galaxy` > > Commands to insert before building of the galaxy image. > > `append_galaxy` > > Commands to insert after building of the galaxy image. > > `prepend_builder` > > Commands to insert before building of the builder image. > > `append_builder` > > Commands to insert after building of the builder image. > > `prepend_final` > > Commands to insert before building of the final image. > > `append_final` > > Commands to insert after building of the final image. Note Please make sure that you do not specify USER directives in these build steps. This may lead to failures while building the image. If you want to override the USER setting, consider using the options.user setting mentioned below. ### [build\_arg\_defaults](https://docs.ansible.com/projects/builder/en/latest/definition/#id13) [](https://docs.ansible.com/projects/builder/en/latest/definition/#build-arg-defaults "Link to this heading") Specifies default values for build args as a dictionary. This is an alternative to using the [\--build-arg](https://docs.ansible.com/projects/builder/en/latest/usage/#build-arg) CLI flag. Build args used by `ansible-builder` are the following: > `ANSIBLE_GALAXY_CLI_COLLECTION_OPTS` > > This allows the user to pass the –pre flag (or others) to enable the installation of pre-release collections. > > `ANSIBLE_GALAXY_CLI_ROLE_OPTS` > > This allows the user to pass any flags, such as –no-deps, to the role installation. > > `PKGMGR_PRESERVE_CACHE` > > This controls how often the package manager cache is cleared during the image build process. If this value is not set, which is the default, the cache is cleared frequently. If it is set to the string always, the cache is never cleared. Any other value forces the cache to be cleared only after the system dependencies are installed in the final build stage. Ansible Builder hard-codes values given inside of `build_arg_defaults` into the build instruction file, so they will persist if you run your container build manually. If you specify the same variable in the execution environment definition and at the command line with the CLI [\--build-arg](https://docs.ansible.com/projects/builder/en/latest/usage/#build-arg) flag, the CLI value will take higher precedence (the CLI value will override the value in the execution environment definition). ### [dependencies](https://docs.ansible.com/projects/builder/en/latest/definition/#id14) [](https://docs.ansible.com/projects/builder/en/latest/definition/#dependencies "Link to this heading") Specifies dependencies to install into the final image, including `ansible-core`, `ansible-runner`, Python packages, system packages, and Ansible Collections. Ansible Builder automatically installs dependencies for any Ansible Collections you install. In general, you can use standard syntax to constrain package versions. Use the same syntax you would pass to `dnf`, `pip`, `ansible-galaxy`, or any other package management utility. You can also define your packages or collections in separate files and reference those files in the `dependencies` section of your execution environment definition file. The following keys are valid for this section: > `ansible_core` > > The version of the `ansible-core` Python package to be installed. This value is a dictionary with a single key, `package_pip`. The `package_pip` value is passed directly to pip for installation and can be in any format that pip supports. Below are some example values: > > ansible\_core: > package\_pip: ansible-core > ansible\_core: > package\_pip: ansible-core==2.14.3 > ansible\_core: > package\_pip: https://github.com/example\_user/ansible/archive/refs/heads/ansible.tar.gz > > `ansible_runner` > > The version of the Ansible Runner Python package to be installed. This value is a dictionary with a single key, `package_pip`. The `package_pip` value is passed directly to pip for installation and can be in any format that pip supports. Below are some example values: > > ansible\_runner: > package\_pip: ansible-runner > ansible\_runner: > package\_pip: ansible-runner==2.3.2 > ansible\_runner: > package\_pip: https://github.com/example\_user/ansible-runner/archive/refs/heads/ansible-runner.tar.gz > > `galaxy` > > Ansible Collections to be installed from Galaxy. This may be a filename, a dictionary, or a multi-line string representation of an Ansible Galaxy `requirements.yml` file (see below for examples). Read more about the requirements file format in the [Galaxy user guide](https://docs.ansible.com/projects/ansible/latest/galaxy/user_guide.html#install-multiple-collections-with-a-requirements-file) > . > > `python` > > The Python installation requirements. This may either be a filename, or a list of requirements (see below for an example). > > Note > > Python requirement specifications are expected to be limited to features defined by [PEP 508](https://peps.python.org/pep-0508/) > . Hash tag comments will always be allowed. Any deviation from this specification will be passed through to pip unverified and unaltered, although this is considered undefined and unsupported behavior. It is not recommended that you depend on this behavior. > > `python_interpreter` > > A dictionary that defines the Python system package name to be installed by `dnf` (`package_system`) and/or a path to the Python interpreter to be used (`python_path`). > > `system` > > The system packages to be installed, in bindep format. This may either be a filename, or a list of requirements (see below for an example). > > `exclude` > > A dictionary defining the Python or system requirements to be excluded from the top-level dependency requirements of referenced collections. These exclusions will not apply to the user supplied Python or system dependencies, nor will they apply to dependencies of dependencies (top-level only). > > The following keys are valid for this section: > > > * `python` - A list of Python dependencies to be excluded. > > > > * `system` - A list of system dependencies to be excluded. > > > > * `all_from_collections` - If you want to exclude _all_ Python and system dependencies from one or more collections, supply a list of collection names under this key. > > > > The exclusion feature supports two forms of matching: > > > * Simple name matching. > > > > * Advanced name matching using regular expressions. > > > > For simple name matching, you need only supply the name of the requirement/collection to match. All values will be compared in a case-insensitive manner. > > For advanced name matching, begin the exclusion string with the tilde (`~`) character to indicate that the remaining portion of the string is a regular expression to be used to match a requirement/collection name. The regex should be considered case-insensitive. > > Note > > The regular expression must match the full requirement/collection name. For example, `~foo.` does not fully match the name `foobar`, but `~foo.+` does. > > With both forms of matching, the exclusion string will be compared against the _simple_ name of any Python or system requirement. For example, if you need to exclude the system requirement that appears as `foo [!platform:gentoo]` within an included collection, then your exclusion string should be `foo`. To exclude the Python requirement `bar == 1.0.0`, your exclusion string would be `bar`. > > Example using both simple and advanced matching: > > dependencies: > exclude: > python: > \- docker > system: > \- python3-Cython > all\_from\_collections: > \# Regular expression to exclude all from community collections > \- ~community\\..+ > > Note > > The `exclude` option requires `ansible-builder` version `3.1` or newer. The following example uses filenames that contain various dependencies: dependencies: python: requirements.txt system: bindep.txt galaxy: requirements.yml ansible\_core: package\_pip: ansible-core==2.14.2 ansible\_runner: package\_pip: ansible-runner==2.3.1 python\_interpreter: package\_system: "python310" python\_path: "/usr/bin/python3.10" And this example uses inline values: dependencies: python: \- pywinrm system: \- iputils \[platform:rpm\] galaxy: collections: \- name: community.windows \- name: ansible.utils version: 2.10.1 ansible\_core: package\_pip: ansible-core==2.14.2 ansible\_runner: package\_pip: ansible-runner==2.3.1 python\_interpreter: package\_system: "python310" python\_path: "/usr/bin/python3.10" ### [images](https://docs.ansible.com/projects/builder/en/latest/definition/#id15) [](https://docs.ansible.com/projects/builder/en/latest/definition/#images "Link to this heading") Specifies the base image to be used. At a minimum you _MUST_ specify a source, image, and tag for the base image. The base image provides the operating system and may also provide some packages. We recommend using the standard `host/namespace/container:tag` syntax to specify images. You may use Podman or Docker shortcut syntax instead, but the full definition is more reliable and portable. Valid keys for this section are: > `base_image` > > A dictionary defining the parent image for the execution environment. A `name` key must be supplied with the container image to use. Use the `signature_original_name` key if the image is mirrored within your repository, but signed with the original image’s signature key. #### [image verification](https://docs.ansible.com/projects/builder/en/latest/definition/#id16) [](https://docs.ansible.com/projects/builder/en/latest/definition/#image-verification "Link to this heading") You can verify signed container images if you are using the `podman` container runtime. Set the [\--container-policy](https://docs.ansible.com/projects/builder/en/latest/usage/#container-policy) CLI option to control how this data is used with a Podman [policy.json](https://github.com/containers/image/blob/main/docs/containers-policy.json.5.md) file for container image signature validation. > * `ignore_all` policy: Generate a policy.json file in the build [context directory](https://docs.ansible.com/projects/builder/en/latest/usage/#context) > where no signature validation is performed. > > * `system` policy: Signature validation is performed using pre-existing policy.json files in standard system locations. `ansible-builder` assumes no responsibility for the content within these files, and the user has complete control over the content. > > * `signature_required` policy: `ansible-builder` will use the container image definitions here to generate a policy.json file in the build [context directory](https://docs.ansible.com/projects/builder/en/latest/usage/#context) > that will be used during the build to validate the images. > ### [options](https://docs.ansible.com/projects/builder/en/latest/definition/#id17) [](https://docs.ansible.com/projects/builder/en/latest/definition/#options "Link to this heading") A dictionary of keywords/options that can affect builder runtime functionality. Valid keys for this section are: > `container_init` > > A dictionary with keys that allow for customization of the container `ENTRYPOINT` and `CMD` directives (and related behaviors). Customizing these behaviors is an advanced task, and may result in subtle, difficult-to-debug failures. As the provided defaults for this section control several intertwined behaviors, overriding any value will skip all remaining defaults in this dictionary. Valid keys are: > > `cmd` > > Literal value for the `CMD` Containerfile directive. The default value is `["bash"]`. > > `entrypoint` > > Literal value for the `ENTRYPOINT` Containerfile directive. The default entrypoint behavior handles signal propagation to subprocesses, as well as attempting to ensure at runtime that the container user has a proper environment with a valid writeable home directory, represented in `/etc/passwd`, with the `HOME` envvar set to match. The default entrypoint script may emit warnings to `stderr` in cases where it is unable to suitably adjust the user runtime environment. This behavior can be ignored or elevated to a fatal error; consult the source for the `entrypoint` target script for more details. The default value is `["/opt/builder/bin/entrypoint", "dumb-init"]`. > > `package_pip` > > Package to install via pip for entrypoint support. This package will be installed in the final build image. The default value is `dumb-init==1.2.5`. > > `package_manager_path` > > A string with the path to the package manager to use. The default is `/usr/bin/dnf`. > > This option allows you to choose between different RPM package managers available on your base image, such as `/usr/bin/dnf` or `/usr/bin/microdnf`. The package manager is used to install system packages, and if specified in `dependencies`, to install a Python interpreter during the build phase. > > Warning > > Only RPM-based package managers (for example, `dnf` or `microdnf`) are supported. Non-RPM package managers such as `apt-get` (Debian/Ubuntu) or `apk` (Alpine) are not supported and will cause build failures. > > `skip_ansible_check` > > This boolean value controls whether or not the check for an installation of Ansible and Ansible Runner is performed on the final image. Set this value to `True` to not perform this check. The default is `False`. > > `skip_pip_install` > > This boolean value controls whether or not we attempt to install pip into the base image. Pip is necessary for Python requirement installation, among other things. You may choose to disable this step and handle installing pip manually if the current method of pip installation does not work for you. The default is `False`. > > `relax_passwd_permissions` > > This boolean value controls whether the `root` group (GID 0) is explicitly granted write permission to `/etc/passwd` in the final container image. The default entrypoint script may attempt to update `/etc/passwd` under some container runtimes with dynamically created users to ensure a fully functional POSIX user environment and home directory. Disabling this capability can cause failures of software features that require users to be listed in `/etc/passwd` with a valid and writeable home directory (eg, `async` in ansible-core, and the `~username` shell expansion). The default is `True`. > > `workdir` > > Default current working directory for new processes started under the final container image. Some container runtimes also use this value as `HOME` for dynamically-created users in the `root` (GID 0) group. When this value is specified, the directory will be created (if it doesn’t already exist), set to `root` group ownership, and `rwx` group permissions recursively applied to it. The default value is `/runner`. > > `user` > > This sets the username or UID to use as the default user for the final container image. The default value `1000`. > > `tags` > > Specifies the names that are assigned to the resulting image if the build process completes successfully. The default value is `ansible-execution-env:latest`. Example `options` section: options: container\_init: package\_pip: dumb-init>=1.2.5 entrypoint: '\["dumb-init"\]' cmd: '\["csh"\]' package\_manager\_path: /usr/bin/microdnf relax\_passwd\_permissions: false skip\_ansible\_check: true workdir: /myworkdir user: bob tags: \- ee\_development:latest ### [version](https://docs.ansible.com/projects/builder/en/latest/definition/#id18) [](https://docs.ansible.com/projects/builder/en/latest/definition/#version "Link to this heading") An integer value that sets the schema version of the execution environment definition file. Defaults to `1`. Must be `3` if you are using Ansible Builder 3.x. --- # Changelogs - antsibull-changelog – Ansible Changelog Tool [Skip to content](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#changelogs-for-collections) Changelogs for Collections[¶](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#changelogs-for-collections "Permanent link") ============================================================================================================================================= The `antsibull-changelog` tool allows you to create and update changelogs for Ansible collections, that are similar to the ones provided by Ansible itself in earlier versions, and that are compatible to the combined Ansible Community Distribution changelogs. The following instructions assume that antsibull has been properly installed, for example via `pip install antsibull-changelog`. This is the preferred way to install `antsibull-changelog`. If you want to get the current `main` branch with not yet released changes, run `pip install https://github.com/ansible-community/antsibull-changelog/archive/main.tar.gz`. If you cloned the git repository and want to run it from there with `poetry`, `antsibull-changelog` has to be substituted with `poetry run antsibull-changelog`. Bootstrapping changelogs for collections[¶](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#bootstrapping-changelogs-for-collections "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- To set up `antsibull-changelog`, run: `[](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#__codelineno-0-1) antsibull-changelog init /path/to/your/collection` This is the directory which contains `galaxy.yml`. This creates subdirectories `changelogs/` and `changelogs/fragments/`, and a configuration file `changelogs/config.yaml`. Adjust the configuration file to your needs. The settings of highest interest are: 1. `title`: This is by default the titlecase of your collection's namespace and name. Feel free to insert a nicer name here. 2. `output_formats`: This is by default `[rst]`. Change this to `[rst, md]` to output both a RST and MarkDown version of the changelog, or to `[md]` to only output a MarkDown version. 3. `keep_fragments`: The default value `false` removes the fragment files after a release is done. If you prefer to keep fragment files for older releases, set this to `true`. If you want to remove fragments after a release, but archive them in another directory, you can use the `archive_path_template` option in combination with `keep_fragments: no`. See further below in the list for its usage. 4. `changelog_filename_template`: The default value `../CHANGELOG.rst` is relative to the `changelogs/` directory. 5. `use_fqcn`: The default value `true` uses FQCN when mentioning new plugins and modules. 6. `flatmap`: Setting to `true` or `false` explicitly enables resp. disables flatmapping. Since flatmapping is disabled by default (except for ansible-core/-base), this is effectively only needed for the big community collections `community.general` and `community.network`. 7. `always_refresh`: See ["Updating/Refreshing changelog.yaml"](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#updatingrefreshing-changelogyaml) on refreshing changelog fragments and/or plugin descriptions. 8. `archive_path_template`: If `keep_fragments` is set to `false`, and `archive_path_template` is set, fragments will be copied into the directory denoted by `archive_path_template` instead of being deleted. The directory is created if it does not exist. The placeholder `{version}` can be used for the current collection version into which the fragment was included. For a description of all configuration settings, see the separate document [Configuration Settings for antsibull-changelog](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/) . Validating changelog fragments[¶](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#validating-changelog-fragments "Permanent link") ----------------------------------------------------------------------------------------------------------------------------------------------------- If you want to do a basic syntax check of changelog fragments, you can run: `[](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#__codelineno-1-1) antsibull-changelog lint` If you want to check a specific fragment, you can provide a path to it; otherwise, all fragments in `changelogs/fragments/` are checked. This can be used in CI to avoid contributors to check in invalid changelog fragments, or introduce new sections (by mistyping existing ones, or simply guessing wrong names). If `antsibull-changelog lint` produces no output on stdout, and exits with exit code 0, the changelog fragments are OK. If errors are found, they are reported by one line in stdout for each error in the format `path/to/fragment:line:column:message`, and the program exits with exit code 3. Other exit codes indicate problems with the command line or during the execution of the linter. Releasing a new version of a collection[¶](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#releasing-a-new-version-of-a-collection "Permanent link") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- To release a new version of a collection, you need to run: `[](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#__codelineno-2-1) antsibull-changelog release` inside your collection's tree. This assumes that `galaxy.yml` exists and its version is the version of the release you want to make. If that file does not exist, or has a wrong value for `version`, you can explicitly specify the version you want to release: `[](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#__codelineno-3-1) antsibull-changelog release --version 1.0.0` You can also specify a release date with `--date 2020-12-31`, if the default (today) is not what you want. When doing a release, the changelog generator will read all changelog fragments which are not already mentioned in the changelog, and include them in a new entry in `changelogs/changelog.yaml`. It will also scan metadata for all modules and plugins of your collection, and mention all modules and plugins with `version_added` equal to this version as new modules/plugins. The metadata for modules and plugins is stored in `changelogs/.plugin-cache.yaml`, and is only recalculated once the release version changes. To force recollecting this data, either delete the file, or specify the `--reload-plugins` option to `antsibull-changelog release`. That file should **not** be added to source control. We suggest to add it to your `.gitignore` file, or use the equivalent mechanism if you use another source control. After running `antsibull-changelog release`, you should check `changelogs/changelog.yaml` and the generated reStructuredText file (by default `CHANGELOG.rst`) in. Updating/Refreshing changelog.yaml[¶](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#updatingrefreshing-changelogyaml "Permanent link") ----------------------------------------------------------------------------------------------------------------------------------------------------------- By default, the `changelogs/changelog.yaml` file is the main source of truth for antsibull-changelog. It is only modified when a new release is done, and in that case existing entries for other versions than the current one are not touched. If the main source of truth should be the fragments, or the plugin sources, the refreshing options or config has to be used. Please note that for plugins, a cache is created in `changelogs/.plugin-cache.yaml`. This cache is updated when the `generate` and `release` subcommands are run, and the latest version (for `generate`) resp. the release version (for `release`) differs from the version recorded in the cache file. Regeneration can be enforced by specifying the `--reload-plugins` option. Also note that refreshing plugins purges all plugins added by changelog fragments. This means that if plugin descriptions should be updated, either the plugin cache has to be deleted, or `--reload-plugins` has to be specified next to the refresh options/configuration. Refreshing can be configured in different ways, either by the `always_refresh` configuration setting, or three command line options `--refresh`, `--refresh-plugins` and `--refresh-fragments`. These can be specified for both the `generate` and `release` subcommands. 1. The `always_refresh` configuration is a string with one of the following values: 2. `none` (default): equivalent to `--refresh-plugins`, `--refresh-fragments`, and `--refresh` not specified; 3. `full`: equivalent to `--refresh-plugins allow-removal --refresh-fragments with-archives` specified, or alternatively `--refresh`; 4. a comma-separated list, where the following entries are supported: * `plugins`: equivalent to `--refresh-plugins allow-removal` specified; * `plugins-without-removal`: equivalent to `--refresh-plugins prevent-removal` specified; * `fragments`: equivalent to `--refresh-fragments with-archives` specified; * `fragments-without-archives`: equivalent to `--refresh-fragments without-archives` specified. 5. The `--refresh` command line parameter is equivalent to `--refresh-plugins allow-removal --refresh-fragments with-archives`. 6. `--refresh-plugins`: if specified, plugin and module descriptions are updated from the plugin cache. 7. `allow-removal` (default): Plugin and module descriptions are updated. If a module or plugin does not exist in the cache, it will be **removed** from the changelog. Please note that if you do not start a new changelog per major release of a collection, and have removed plugins or modules before, `--refresh plugins allow-removal` will remove earlier changelog entries from when these plugins resp. modules were added! 8. `prevent-removal`: Plugin and module descriptions are updated. If a module or plugin does not exist in the cache, it will **not** be removed from the changelog. 9. `--refresh-fragments`: if specified, the fragments for all versions will be recreated from the changelog fragment files. This is only possible if `keep_fragments` is `true`, or fragment archives exist (see the `archive_path_template` option). Note that if not all fragments were archived or kept in the fragments directory, they will be **removed** from the changelog. 10. `with-archives` (default): Uses both the archives and the current fragment directory to update the fragments. 11. `without-archives`: Uses only the current fragment directory to update the fragments. Fragments that have been moved to the archive and no longer exist in the fragment directory will vanish from the changelog. Changelog Fragment Categories[¶](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#changelog-fragment-categories "Permanent link") --------------------------------------------------------------------------------------------------------------------------------------------------- This section describes the section categories created in the default config. You can change them, though this is strongly discouraged for collections which will be included in the Ansible Community Distribution. The categories are the same as the ones in the [Ansible-case changelog fragments](https://docs.ansible.com/projects/ansible/devel/community/development_process.html#changelogs-how-to) . Note The changelog generator automatically detects new modules and new plugins which are documentable (i.e. where you have `DOCUMENTATION` where `version_added` is there), so you do not need to create changelog entries for them. The full list of categories is: **release\_summary** This is a special section: as opposed to a list of strings, it accepts one string. This string will be inserted at the top of the changelog entry for the current version, before any section. There can only be one fragment with a `release_summary` section. In ansible-core, this is used for stating the release date and for linking to the porting guide ([example](https://github.com/ansible/ansible/blob/stable-2.9/changelogs/fragments/v2.9.0_summary.yaml) , [result](https://github.com/ansible/ansible/blob/stable-2.9/changelogs/CHANGELOG-v2.9.rst#id23) ). **breaking\_changes** This (new) category should list all changes to features which absolutely require attention from users when upgrading, because an existing behavior is changed. This is mostly what Ansible's Porting Guide used to describe. This section should only appear in a initial major release (`x.0.0`) according to semantic versioning. **major\_changes** This category contains major changes to the collection. It should only contain a few items per major version, describing high-level changes. This section should not appear in patch releases according to semantic versioning. **minor\_changes** This category should mention all new features, like plugin or module options. This section should not appear in patch releases according to semantic versioning. **removed\_features** This category should mention all modules, plugins and features that have been removed in this release. This section should only appear in a initial major release (`x.0.0`) according to semantic versioning. **deprecated\_features** This category should contain all modules, plugins and features which have been deprecated and will be removed in a future release. This section should not appear in patch releases according to semantic versioning. **security\_fixes** This category should mention all security relevant fixes, including CVEs if available. **bugfixes** This category should be a list of all bug fixes which fix a bug that was present in a previous version. **known\_issues** This category should mention known issues that are currently not fixed or will not be fixed. **trivial** This category will **not be shown** in the changelog. It can be used to describe changes that are not touching user-facing code, like changes in tests. This is useful if every PR is required to have a changelog fragment. There are some special categories starting with `add`; please see the next section for details. ### Examples[¶](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#examples "Permanent link") A guide on how to write changelog fragments can be found in the [Ansible docs](https://docs.ansible.com/projects/ansible/devel/community/development_process.html#changelogs-how-to) . Example of a regular changelog fragment: `[](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#__codelineno-4-1) bugfixes: [](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#__codelineno-4-2) - docker_container - wait for removal of container if docker API returns early [](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#__codelineno-4-3) (https://github.com/ansible/ansible/issues/65811).` The filename in this case was `changelogs/fragments/65854-docker_container-wait-for-removal.yml`, because this was implemented in [PR #65854 in ansible/ansible](https://github.com/ansible/ansible/pull/65854) . A fragment can also contain multiple sections, or multiple entries in one section: `[](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#__codelineno-5-1) deprecated_features: [](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#__codelineno-5-2) - docker_container - the ``trust_image_content`` option will be removed. It has always been ignored by the module. [](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#__codelineno-5-3) - docker_stack - the return values ``err`` and ``out`` have been deprecated. Use ``stdout`` and ``stderr`` from now on instead. [](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#__codelineno-5-4) [](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#__codelineno-5-5) breaking_changes: [](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#__codelineno-5-6) - "docker_container - no longer passes information on non-anonymous volumes or binds as ``Volumes`` to the Docker daemon. This increases compatibility with the ``docker`` CLI program. Note that if you specify ``volumes: strict`` in ``comparisons``, this could cause existing containers created with docker_container from Ansible 2.9 or earlier to restart."` The `release_summary` section is special, in that it doesn't contain a list of strings, but a string, and that only one such entry can be shown in the changelog of a release. Usually for every release (pre-release or regular release), at most one fragment is added which contains a `release_summary`, and this is only done by the person doing the release. The `release_summary` should include some global information on the release; for example, in [Ansible's changelog](https://github.com/ansible/ansible/blob/stable-2.9/changelogs/CHANGELOG-v2.9.rst#release-summary) , it always mentions the release date and links to the porting guide. An example of how a fragment with `release_summary` could look like is `changelogs/fragments/0.2.0.yml` from community.general: `[](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#__codelineno-6-1) release_summary: | [](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#__codelineno-6-2) This is the first proper release of the ``community.general`` collection on 2020-06-20. [](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#__codelineno-6-3) The changelog describes all changes made to the modules and plugins included in this collection since Ansible 2.9.0.` Adding new Roles, Playbooks, Test and Filter Plugins[¶](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#adding-new-roles-playbooks-test-and-filter-plugins "Permanent link") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Note that with ansible-core 2.11+, new roles are automatically detected if their documentation (in the argument spec) contains an appropriate `version_added` value for the `main` entrypoint. With ansible-core 2.14+ (or the current `devel` and `milestone` branches), filter and test plugins are also automatically detected if their documentation contains an appropriate `version_added` value. No version of ansible-core allows to document playbooks (yet), so new playbooks have to be documented as described below. The following describes a way to document new playbooks. When using older versions of ansible-core during release time when the changelog is generated, this can also be used to document new roles, test plugins, and filter plugins. This works by using special sections in changelog fragments whose names start with `add`: `[](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#__codelineno-7-1) --- [](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#__codelineno-7-2) # Always needed for new playbooks: [](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#__codelineno-7-3) add object.playbook: [](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#__codelineno-7-4) - name: wipe_server [](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#__codelineno-7-5) description: Wipes a server [](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#__codelineno-7-6) [](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#__codelineno-7-7) # Only needed when ansible-core < 2.14 is used during the release process, [](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#__codelineno-7-8) # or when the filter has no documentation or the documentation is missing a [](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#__codelineno-7-9) # 'version_added' entry: [](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#__codelineno-7-10) add plugin.filter: [](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#__codelineno-7-11) - name: to_time_unit [](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#__codelineno-7-12) description: Converts a time expression to a given unit [](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#__codelineno-7-13) - name: to_seconds [](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#__codelineno-7-14) description: Converts a time expression to seconds [](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#__codelineno-7-15) [](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#__codelineno-7-16) # Only needed when ansible-core < 2.14 is used during the release process, [](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#__codelineno-7-17) # or when the test has no documentation or the documentation is missing a [](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#__codelineno-7-18) # 'version_added' entry: [](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#__codelineno-7-19) add plugin.test: [](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#__codelineno-7-20) - name: asn1time [](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#__codelineno-7-21) description: Check whether the given string is an ASN.1 time [](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#__codelineno-7-22) [](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#__codelineno-7-23) # Only needed when ansible-core < 2.11 is used during the release process, [](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#__codelineno-7-24) # or when the role has no argument spec or the argument spec is missing a [](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#__codelineno-7-25) # 'version_added' entry for the 'main' entrypoint: [](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#__codelineno-7-26) add object.role: [](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#__codelineno-7-27) - name: nginx [](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#__codelineno-7-28) description: A nginx installation role` Porting Guide Entries[¶](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#porting-guide-entries "Permanent link") ----------------------------------------------------------------------------------------------------------------------------------- The following sections are considered as the Porting Guide of the collection. For collections included in Ansible, these will be inserted into Ansible's Porting Guide: * `major_changes` * `breaking_changes` * `deprecated_features` * `removed_features` --- # Changelog configuration - antsibull-changelog – Ansible Changelog Tool [Skip to content](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#configuration-settings-for-antsibull-changelog) Configuration Settings for antsibull-changelog[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#configuration-settings-for-antsibull-changelog "Permanent link") ================================================================================================================================================================================================== This document describes all settings that are supported in `changelogs/config.yaml`. General options[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#general-options "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------ ### `add_plugin_period` (boolean)[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#add_plugin_period-boolean "Permanent link") The default value is `false` for existing configurations, and `true` for new configurations. If set to `false`, the plugin short description is used. If set to `true`, a period is added to the end of the plugin short description if no other end punctuation is present. Setting to `true` complies with the [Ansible changelog format](https://docs.ansible.com/projects/ansible/latest/community/development_process.html#changelogs-how-to-format) . ### `always_refresh` (string)[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#always_refresh-string "Permanent link") Allowed values are `none`, `full`, or a comma-separated combination of one or more of `plugins`, `plugins-without-removal`, `fragments` and `fragments-without-archives`. If `true` is passed, it will be converted to `full`. If `false` is passed, it will be converted to `none`. For details, see ["Updating/Refreshing changelog.yaml" in the main documentation](https://docs.ansible.com/projects/antsibull-changelog/changelogs/#updatingrefreshing-changelogyaml) . ### `archive_path_template` (optional string)[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#archive_path_template-optional-string "Permanent link") The default value is `null`. When `keep_fragments` is set to `false`, and this setting is defined, fragments will be copied to the path specified by this setting after a release is made. This setting is assumed to point to a directory, and the placeholder `{version}` can be used to make the destination dependent on the version number of the new release. If the directory does not yet exist, it will be created. ### `changes_file` (string)[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#changes_file-string "Permanent link") The default value is `.changes.yaml` for existing configurations, and `changelog.yaml` for new configurations. The YAML file where the changelog is stored in a machine-readable form. This is relative to the `changelogs/` directory and should not be changed, since `changelogs/changelog.yaml` is the standard place for the machine-readable file which is expected to be there by the Ansible Community Distribution changelog generator. ### `changes_format` (string)[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#changes_format-string "Permanent link") Must be set to `combined`. All fragments and plugin data is stored inside the file (used by ansible-base, ansible-core, and in collections). Note that support for `classic` has been **REMOVED** and the field is now required. ### `changelog_nice_yaml` (boolean)[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#changelog_nice_yaml-boolean "Permanent link") The default is `false`. When set to `true`, the `changelogs/changelog.yaml` file will be written with a slightly different YAML encoding that is compatible with ansible-lint's default rules. Note The exact format used might be adjusted in the future if new releases of ansible-lint adjust their yamllint configuration. ### `changelog_sort` (string)[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#changelog_sort-string "Permanent link") The default is `alphanumerical`. This option controls the sorting of changelog entries in `changelogs/changelog.yaml`. It accepts the following values: * `unsorted`: No sorting is performed on the changelog entries. The entries are stored in the order they were added. * `version`: Sorts the changelog entries by version in ascending order. * `version_reversed`: Sorts the changelog entries by version in descending order. * `alphanumerical`: Sorts the changelog entries in alphanumerical order. ### `flatmap` (optional boolean)[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#flatmap-optional-boolean "Permanent link") The default value is `null`. Can be set to `true` or `false` explicitly to enable respectively disable flatmapping. Since flatmapping is disabled by default (except for ansible-core), this is effectively only needed for the big community collections `community.general` and `community.network`. When enabled, a plugin `foo.bar.subdir.dir.plugin_name` will be mentioned as `plugin_name` or `foo.bar.plugin_name` (if `use_fqcn` is `true`), instead of as `subdir.dir.plugin_name` respectively `foo.bar.subdir.dir.plugin_name`. ### `is_other_project` (boolean)[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#is_other_project-boolean "Permanent link") The default value is `false`. If set to `true`, does not look for `galaxy.yml` and does not look for new Ansible objects (plugins, modules and roles). This allows the changelog generator to be used for projects which are not ansible-core/-base or an Ansible collection. ### `ignore_other_fragment_extensions` (boolean)[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#ignore_other_fragment_extensions-boolean "Permanent link") The default value is `false` for existing configurations, and `true` for new configurations. If set to `true`, only `.yml` and `.yaml` fragment filenames are considered which do not start with a dot. This is compatible with what `ansible-test sanity --test changelog` enforces. If set to `false` (default if not specified), all filenames that do not start with a dot are considered. ### `keep_fragments` (boolean)[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#keep_fragments-boolean "Permanent link") The default value is `false`. If set to `false`, the fragment files will be removed after a release is done. If set to `true`, fragment files for old releases are kept. If fragment files should be moved to another directory after release, set this setting to `false` and set `archive_path_template`. See also `prevent_known_fragments`. ### `mention_ancestor` (boolean)[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#mention_ancestor-boolean "Permanent link") The default value is `true`. If an ancestor is defined in `changelogs/changelog.yaml`, determines whether it should be mentioned at the beginning of the changelog or not. If set to `true`, `This changelog describes changes after version {ancestor}` will be inserted at the top of the changelog. ### `notes_dir` (string)[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#notes_dir-string "Permanent link") The default value is `fragments`. The name of the subdirectory of `changelogs/` that contains the changelog fragments. ### `prelude_name` (string)[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#prelude_name-string "Permanent link") The default value is `release_summary`. Name of the prelude section to be used in changelog fragments. This section is special, in that it does not accept a list, but a string. ### `output` (list of dictionaries)[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#output-list-of-dictionaries "Permanent link") Defines the changelog files written by `antsibull-changelog generate` and `antsibull-changelog release`. The default value for existing configurations, if not specified, is: `[](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#__codelineno-0-1) - file: changelogs/CHANGELOG-v%s.rst [](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#__codelineno-0-2) filename_version_depth: 2 [](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#__codelineno-0-3) title_version_depth: 2 [](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#__codelineno-0-4) format: rst` The default for new configurations is: `[](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#__codelineno-1-1) - file: CHANGELOG.rst [](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#__codelineno-1-2) filename_version_depth: 0 [](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#__codelineno-1-3) title_version_depth: 0 [](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#__codelineno-1-4) format: rst` The `output` option must not be used with the deprecated options `changelog_filename_template`, `changelog_filename_version_depth`, and `output_formats`. If any of these values is set, for every `output_format` in `output_formats` (default: `[rst]`) the following entry is added to `output`: `[](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#__codelineno-2-1) - file: (value of changelog_filename_template, with adjusted extension) [](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#__codelineno-2-2) filename_version_depth: (value of changelog_filename_version_depth) [](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#__codelineno-2-3) title_version_depth: (value of changelog_filename_version_depth) [](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#__codelineno-2-4) format: (value of output_format)` The format of `output` is as follows: * `file` (string, **required**): The filename to write the changelog to. This must include the correct extension. If it contains the placeholder `%s`, then parts of the latest release's version are inserted for `%s`. * `filename_version_depth` (int, default `0`): if `%s` is part of `file`, this determines the version parts of the latest release that `%s` is replaced by. For the value `2`, the latest version 1.2.3 will result in the string `1.2`. The value `0` results in an empty string being inserted. Must be zero if `%s` is not part of `file`, and must be non-zero if `%s` is part of `file`. * `title_version_depth` (int, default `0`): determines the version parts of the latest release that are inserted into the changelog's title. For the value `2`, the latest version 1.2.3 will result in the string `1.2`. The value `0` results in no version info being inserted into the changelog's title. * `format` (string, **required**): the output format to write the changelog as. Supported formats are `rst` for ReStructuredText and `md` for MarkDown. * `global_toc` (bool, default `true`): Whether the changelog should have a global Table of Contents. * `global_toc_depth` (int or `null`, default `null`): if `global_toc=true`, determines whether the Table of Contents has a maximum depth. * `per_release_toc` (bool, default `false`): Whether every release of the changelog should have a local Table of Contents. * `per_release_toc_depth` (int or `null`, default `null`): if `per_release_toc=true`, determines whether the Table of Contents for a release has a maximum depth. ### `prelude_title` (string)[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#prelude_title-string "Permanent link") The default value is `Release Summary`. The title for the section whose name is set in `prelude_name`. ### `prevent_known_fragments` (optional boolean)[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#prevent_known_fragments-optional-boolean "Permanent link") The default value is the same value as the `keep_fragments` option. If set to `true`, will not add changelog fragments to a release whose filename was already used in the past. This was the default behavior before antsibull-changelog 0.9.0. From 0.9.0 on, it is set to `false` by default if `keep_fragments` is `false`. If `keep_fragments` is set to `false` later-on when some fragments from older releases are still there, and you want to keep them, make sure to set `prevent_known_fragments` explicitly to `true`. Otherwise they will be added again to the next release. ### `sanitize_changelog` (boolean)[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#sanitize_changelog-boolean "Permanent link") The default value is `false` for existing configurations, and `true` for new configurations. Remove all invalid and superfluous information when loading a `changelogs/changelog.yaml` file. ### `sections` (list of two-element lists of strings)[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#sections-list-of-two-element-lists-of-strings "Permanent link") The default value is: `[](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#__codelineno-3-1) - - major_changes [](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#__codelineno-3-2) - Major Changes [](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#__codelineno-3-3) - - minor_changes [](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#__codelineno-3-4) - Minor Changes [](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#__codelineno-3-5) - - breaking_changes [](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#__codelineno-3-6) - Breaking Changes / Porting Guide [](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#__codelineno-3-7) - - deprecated_features [](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#__codelineno-3-8) - Deprecated Features [](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#__codelineno-3-9) - - removed_features [](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#__codelineno-3-10) - Removed Features (previously deprecated) [](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#__codelineno-3-11) - - security_fixes [](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#__codelineno-3-12) - Security Fixes [](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#__codelineno-3-13) - - bugfixes [](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#__codelineno-3-14) - Bugfixes [](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#__codelineno-3-15) - - known_issues [](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#__codelineno-3-16) - Known Issues` Lists all section names (first element) and their titles (second element). The only two sections not listed here are the prelude section (`release_summary` / "Release Summary") and the trivial section (`trivial`, no title). It is not recommended to change this list, except possibly adjust section titles. Collections using other section names will cause problems with the Ansible Community Distribution changelog generation. ### `title` (string)[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#title-string "Permanent link") The default value is the titlecase of the collection's namespace and name. The title is shown at the top of the changelog. ### `trivial_section_name` (optional string)[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#trivial_section_name-optional-string "Permanent link") The default value is `trivial` for collections and other projects, and `null` for ansible-core/ansible-base. This defines a section that is not included in the generated reStructuredText version of the changelog. It can be used to add changelog fragments to changes that are so minor (trivial) that they should not appear in the changelog, or that are irrelevant to the user (for example changes in the CI system used). When set to `null`, no trivial section is allowed. ### `use_fqcn` (boolean)[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#use_fqcn-boolean "Permanent link") The default value is `false` for existing configurations, and `true` for new configurations. When set to `true`, uses FQCN (Fully Qualified Collection Names) when mentioning new plugins and modules. This means that `namespace.name.` is prepended to the plugin respectively module names. ### `vcs` (optional string)[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#vcs-optional-string "Permanent link") Allowed values are `none`, `git`, or `auto`. The default value is `none` for existing configurations and `auto` for new configurations. Configures which Version Control System is used by the project, if any. Right now this is used when (re-)loading the plugin list for an Ansible collection. For that the project files are copied into a temporary directory tree so that `ansible-doc` can be used to extract the plugin documentation. When set to `none`, all files inside the project's directory will be considered. When set to `git`, will use `git ls-files` to determine which files to consider (directories and files ignored by `git` will be ignored). When set to `auto`, will automatically detect whether the project is part of a Git repository or not. Deprecated options[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#deprecated-options "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------ ### `new_plugins_after_name` (string)[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#new_plugins_after_name-string "Permanent link") The default value is `''` (empty string). This setting is not used. ### `changelog_filename_template` (string)[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#changelog_filename_template-string "Permanent link") The default value is `CHANGELOG-v%s.rst` for existing configurations. **This option is deprecated, use `output` instead.** This is the path relative to the `changelogs/` directory where the reStructuredText version of the changelog is written to. The placeholder `%s` will be replaced by the first `changelog_filename_version_depth` parts of the version of the release. Note The file extension (default `.rst`) will always be replaced by the extension matching the output format (see [`output_formats`](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#output_formats-list-of-strings) ). Therefore the extension provided here will always be ignored. ### `changelog_filename_version_depth` (integer)[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#changelog_filename_version_depth-integer "Permanent link") The default value is 2 for existing configurations. **This option is deprecated, use `output` instead.** Determines the number of parts of the current release version to be used when replacing `%s` in `changelog_filename_template` (see above). For the value 2, version 1.2.3 will result in the string `1.2`. The value 0 results in the empty string. ### `output_formats` (list of strings)[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#output_formats-list-of-strings "Permanent link") The default is `["rst"]`. **This option is deprecated, use `output` instead.** A list of output formats to write the changelog as. Supported formats are `rst` for ReStructuredText and `md` for MarkDown. Ansible-core/-base specific options[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#ansible-core-base-specific-options "Permanent link") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- These options are only used for the changelog for ansible-core, i.e. in the ansible/ansible GitHub repository. ### `use_semantic_versioning` (boolean)[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#use_semantic_versioning-boolean "Permanent link") The default value is `false`. If set to `true`, assumes that ansible-core use semantic versioning instead of the classic Ansible version numbers. This is mainly relevant for pre-releases. If set to `true`, `release_tag_re` and `pre_release_tag_re` are ignored. ### `release_tag_re` (string)[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#release_tag_re-string "Permanent link") The default value is `((?:[\d.ab]|rc)+)`. This value is used to detect versions that are proper release versions, and not prereleases. This is a regular expression matching the version string preprended with `v`. This setting is ignored if `use_semantic_versioning` is set to `true`. ### `pre_release_tag_re` (string)[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog-configuration/#pre_release_tag_re-string "Permanent link") The default value is `(?P\.\d+(?:[ab]|rc)+\d*)$`. This value is used to detect versions that are prereleases. This is a regular expression matching the version string preprended with `v`. This setting is ignored if `use_semantic_versioning` is set to `true`. --- # Changelog.yaml format - antsibull-changelog – Ansible Changelog Tool [Skip to content](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#changelog-yaml-format) Changelog YAML Format[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#changelog-yaml-format "Permanent link") ============================================================================================================================================== This describes the format which is required from collections which want to be included in the Ansible package if they want to have a nicely formatted changelog for their collection in the Ansible combined changelog. The format is similar to the `.changes.yaml` file used internally by Ansible until 2.9.x (see [here](https://github.com/ansible/ansible/blob/stable-2.9/changelogs/.changes.yaml) for an example). Concrete examples for collection changelogs with the new format described here can be found [here](https://github.com/felixfontein/ansible-versioning_test_collection/blob/master/changelogs/changelog.yaml) and [here](https://github.com/felixfontein/ansible-versioning_test_collection/blob/1.0.2/changelogs/changelog.yaml) . Please remember that collection versions **must** use [semantic versioning](https://semver.org/) if included in the Ansible package or RedHat's Automation Hub. You can use the `antsibull-changelog lint-changelog-yaml` tool included in the [antsibull-changelog package](https://pypi.org/project/antsibull-changelog/) to validate these files: `antsibull-changelog lint-changelog-yaml /path/to/changelog.yaml` (For `changelog.yaml` files of projects that do not conform to semantic versioning use the `--no-semantic-versioning` parameter.) The tool does not output anything and exits with exit code 0 in case the file is OK, and outputs errors and exits with exit code 3 in case an error was found. Other exit codes indicate problems with the command line or during the execution of the linter. To avoid extra data in `changelog.yaml` that should not be in there, add the `--strict` option. This can be useful to avoid typos, for example if you wrote `change:` instead of `changes:`, or forgot `changes:` alltogether. changelog.yaml[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#changelogyaml "Permanent link") ------------------------------------------------------------------------------------------------------------------------------- The file must be named `changelog.yaml` and stored in the `changelogs/` subdirectory of the collection root (i.e. the directory containing `galaxy.yml`). It must be a [YAML 1.1](https://yaml.org/spec/1.1/) file. At the top level, there are two entries: 1. A string `ancestor`, which can also be `null` or omitted if the changelog has no ancestor. 2. A dictionary `releases`, which maps version numbers to release information. If `ancestor` is a string, it must be an existing version of the collection which precedes all versions mentioned in this changelog. This is used when the changelog is truncated, for example when using release branches like for ansible-core. There, the `stable-2.10` branch's changelog contains only changelog entries for 2.10.x releases. Since the first 2.10.0b1 release contains all changes made to `devel` after `stable-2.9` was branched, the ancestor for the 2.10 changelog is `2.9.0b1`, the first release made after branching `stable-2.9`. The following shows the outline of a `changelog.yaml` file with four versions: `[](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-0-1) ancestor: 0.5.4 [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-0-2) releases: [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-0-3) 1.0.0-alpha: [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-0-4) ... [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-0-5) 1.0.0-beta: [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-0-6) ... [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-0-7) 1.0.0: [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-0-8) ... [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-0-9) 1.0.1: [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-0-10) ...` ### Release information[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#release-information "Permanent link") For a release `x.y.z`, the `releases` dictionary contains an entry `x.y.z` mapping to another dictionary. That dictionary can have the following entries: 1. `release_date`: a string in ISO format (`YYYY-MM-DD`) specifying on which date the release was made. 2. `codename`: a string for the version's codename. Optional; mainly required for ansible-core. 3. `fragments`: a list of strings mentioning changelog fragment files used for this release. This is not used for compiling a changelog. 4. `changes`: a dictionary containing all changes. See below. 5. `modules`: a list of plugin dictionaries. See below. 6. `plugins`: a dictionary mapping plugin types to lists of plugin dictionaries. See below. 7. `objects`: a dictionary mapping object types to lists of object dictionaries. See below. The following is an example of release information for version `1.0.0`: `[](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-1) releases: [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-2) 1.0.0: [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-3) release_date: '2020-04-01' [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-4) codename: White Rabbit [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-5) changes: [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-6) release_summary: This is the initial White Rabbit release. Enjoy! [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-7) major_changes: [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-8) - The authentication method handling has been rewritten. [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-9) minor_changes: [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-10) - foo - Module can now reformat hard disks without asking. [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-11) - bob lookup - Makes sure Bob isn't there multiple times. [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-12) breaking_changes: [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-13) - Due to the security bug in the post module, the module no longer accepts the password [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-14) option. Please stop using the option and change any password you ever supplied to the [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-15) module. [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-16) deprecated_features: [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-17) - foo - The bar option has been deprecated. Use the username option instead. [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-18) - send_request - The quic option has been deprecated. Use the protocol option instead. [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-19) removed_features: [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-20) - foo - The baz option has been removed. It has never been used anyway. [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-21) security_fixes: [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-22) - post - The module accidentally sent your password in plaintext to all servers it could find. [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-23) bugfixes: [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-24) - post - The module made PUT requests instead of POST requests. [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-25) - get - The module will no longer crash if it received invalid JSON data. [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-26) modules: [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-27) - name: head [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-28) description: Make a HEAD request [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-29) namespace: 'net_tools.rest' [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-30) - name: echo [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-31) description: Echo params [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-32) namespace: '' [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-33) plugins: [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-34) lookup: [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-35) - name: reverse [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-36) description: Reverse magic [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-37) namespace: null [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-38) inventory: [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-39) - name: docker [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-40) description: Inventory plugin for docker containers [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-41) namespace: null [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-42) objects: [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-43) role: [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-44) - name: install_reqs [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-45) description: Install all requirements of this collection [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-46) namespace: null [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-47) playbook: [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-48) - name: wipe_personal_data [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-49) description: Wipes all personal data from the database [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-1-50) namespace: null` #### Changes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#changes "Permanent link") The `changes` dictionary contains different sections of the changelog for this version. 1. `release_summary`: a string summarizing the release. Should not be long text. 2. `major_changes`: a list of strings describing major changes. A release should not have many major changes. The changes described here should be large changes affecting several modules, and be changes that the users should better be aware of. 3. `minor_changes`: a list of strings describing minor changes. A minor change could be adding a module or plugin option. 4. `breaking_changes`: a list of strings describing breaking changes. This should list all breaking changes (which are not deprecated or removed features) which every user _has_ to read when upgrading to find out what they have to change in their playbooks and roles. This is mainly what used to be in the Porting Guide for older Ansible versions. This should only appear for major releases (x.0.0) and pre-releases. 5. `deprecated_features`: a list of strings describing features deprecated in this release. This should only appear for major (x.0.0) or minor (x.y.0) versions. 6. `removed_features`: a list of strings describing features removed in this release. The features should have been deprecated earlier. This should only appear for major releases (x.0.0) as these are breaking changes. 7. `security_fixes`: a list of strings describing security-relevant bugfixes. If available, they should include the issue's CVE. 8. `bugfixes`: a list of strings describing other bugfixes. 9. `known_issues`: a list of strings describing known issues that are currently not fixed or will not be fixed. 10. `trivial`: a list of strings describing changes that are too trivial to show in the changelog. Note that not every section has to be used. Also note that the sections `deprecated_features`, `security_fixes` and `trivial` have been added only after Ansible 2.9, and that `trivial` is special in the sense that changes in there will not be shown to the user. Every of these sections - except `release_summary` - should contain a _list_ of strings. Every string in this list, as well as the `release_summary` section itself, must be valid [reStructuredText](https://en.wikipedia.org/wiki/ReStructuredText) . Every string should be one line only, except for `release_summary`. The `changes` dictionary could look as follows: `[](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-2-1) releases: [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-2-2) 1.0.0: [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-2-3) changes: [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-2-4) release_summary: | [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-2-5) This is the initial White Rabbit release. Enjoy! [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-2-6) major_changes: [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-2-7) - The authentication method handling has been rewritten. [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-2-8) minor_changes: [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-2-9) - foo - Module can now reformat hard disks without asking. [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-2-10) - bob lookup - Makes sure Bob isn't there multiple times. [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-2-11) breaking_changes: [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-2-12) - Due to the security bug in the post module, the module no longer accepts the password [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-2-13) option. Please stop using the option and change any password you ever supplied to the [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-2-14) module. [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-2-15) deprecated_features: [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-2-16) - foo - The bar option has been deprecated. Use the username option instead. [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-2-17) - send_request - The quic option has been deprecated. Use the protocol option instead. [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-2-18) removed_features: [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-2-19) - foo - The baz option has been removed. It has never been used anyway. [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-2-20) security_fixes: [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-2-21) - post - The module accidentally sent your password in plaintext to all servers it could find. [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-2-22) bugfixes: [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-2-23) - post - The module made PUT requests instead of POST requests. [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-2-24) - get - The module will no longer crash if it received invalid JSON data.` #### Plugins, modules and other objects[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#plugins-modules-and-other-objects "Permanent link") The `modules` list should a be list of module plugin descriptions. The `plugins` dictionary should map plugin types to lists of plugin descriptions. The `objects` dictionary is very similar to the `plugins` dictionary, except that it has different types. Currently valid plugin types are: 1. `become` 2. `cache` 3. `callback` 4. `cliconf` 5. `connection` 6. `httpapi` 7. `inventory` 8. `lookup` 9. `netconf`, 10. `shell` 11. `strategy` 12. `vars` 13. `filter` (documentable by `ansible-doc` from ansible-core 2.14+, or the current devel and milestone versions) 14. `test` (documentable by `ansible-doc` from ansible-core 2.14+, or the current devel and milestone versions) See `DOCUMENTABLE_PLUGINS` in https://github.com/ansible/ansible/blob/devel/lib/ansible/constants.py for a complete list of plugin types (minus `modules`). Currently valid object types are: 1. `role` (documentable by `ansible-doc` from ansible-core 2.11+) 2. `playbook` For every module, plugin or object, the description is a dictionary with the following keys: 1. `name`: the name of the module resp. plugin. It must not be the FQCN, but the name inside the collection. 2. `description`: the value of `short_description` in the module's resp. plugin's `DOCUMENTATION`. 3. `namespace`: must be `null` for plugins and objects. For modules, must be `''` for modules directly in `plugins/modules/`, or the dot-separated list of directories the module is in inside the `plugins/modules/` directory. This was mostly relevant for large collections such as community.general (up to 5.x.y) and community.network (up to 4.x.y). For example, the `community.general.ovh_ip_failover` module is in the directory `plugins/modules/cloud/ovh/` in community.general 5.x.y, hence its namespace must be `cloud.ovh`. The namespace is used to group new modules by their namespace inside the collection. The `modules` list, and the `plugins` and `objects` dictionary could look as follows: `[](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-3-1) releases: [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-3-2) 1.0.0: [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-3-3) modules: [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-3-4) - name: head [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-3-5) description: Make a HEAD request [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-3-6) namespace: 'net_tools.rest' [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-3-7) - name: echo [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-3-8) description: Echo params [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-3-9) namespace: '' [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-3-10) plugins: [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-3-11) lookup: [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-3-12) - name: reverse [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-3-13) description: Reverse magic [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-3-14) namespace: null [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-3-15) inventory: [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-3-16) - name: docker [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-3-17) description: Inventory plugin for docker containers [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-3-18) namespace: null [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-3-19) objects: [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-3-20) role: [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-3-21) - name: install_reqs [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-3-22) description: Install all requirements of this collection [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-3-23) namespace: null [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-3-24) playbook: [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-3-25) - name: wipe_personal_data [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-3-26) description: Wipes all personal data from the database [](https://docs.ansible.com/projects/antsibull-changelog/changelog.yaml-format/#__codelineno-3-27) namespace: null` --- # Ansible Collection Policies - Ansible Package Release Management [Skip to content](https://docs.ansible.com/projects/ansible-build-data/policies/#ansible-collection-policies) Ansible Collection Policies[¶](https://docs.ansible.com/projects/ansible-build-data/policies/#ansible-collection-policies "Permanent link") ============================================================================================================================================ This doc explains the necessary ansible-build-data changes to enforce Ansible Community Steering Committee Policies such as [Removal from Ansible](https://docs.ansible.com/projects/ansible/devel/community/collection_contributors/collection_package_removal.html) and [Repository management](https://docs.ansible.com/projects/ansible/devel/community/collection_contributors/collection_requirements.html#repository-management) . Removal from Ansible[¶](https://docs.ansible.com/projects/ansible-build-data/policies/#removal-from-ansible "Permanent link") ------------------------------------------------------------------------------------------------------------------------------ ### Announce removal of a collection (deprecation)[¶](https://docs.ansible.com/projects/ansible-build-data/policies/#announce-removal-of-a-collection-deprecation "Permanent link") If a collection should be removed in a future Ansible version, its removal should be announced in all current major releases, and should also be announced in the upcoming major release (unless it is removed from that version - [see the next subsection for that](https://docs.ansible.com/projects/ansible-build-data/policies/#removing-a-collection) ). To announce removal, removal metadata needs to be added to the collection metadata in `collection-meta.yaml`. Assume you have the following collection metadata: `[](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-0-1) collections: [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-0-2) foo.bar: [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-0-3) maintainers: [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-0-4) - Foo Bar [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-0-5) repository: https://github.com/ansible-collections/foo.bar` Then a `removal` subkey needs to be added to `foo.bar` with the following fields: * `major_version`: the major Ansible version from which the collection shall be removed. * `reason`: can be one of: 1. `deprecated`: the collection has been deprecated by its maintainers. ([Official process](https://docs.ansible.com/projects/ansible/devel/community/collection_contributors/collection_package_removal.html#removing-a-collection-that-has-been-explicitly-deprecated-or-abandoned-by-its-former-maintainers) .) 2. `considered-unmaintained`: the collection is considered unmaintained by the Steering Committee. ([Official process](https://docs.ansible.com/projects/ansible/devel/community/collection_contributors/collection_package_removal.html#identifying-and-removing-an-unmaintained-collection-that-has-not-been-deprecated-by-its-maintainers) .) 3. `renamed`: the collection has been renamed. The new name of the collection should be specified in `new_name`. Also `redirect_replacement_major_version` should be added with the major Ansible release that will contain only deprecated redirects to the new collections. Note that in this case, `major_version` can have the special value `TBD` for when it is not clear when the old collection will eventually be removed from Ansible yet. ([Official process](https://github.com/ansible-community/ansible-build-data/?tab=readme-ov-file#renaming-a-collection) .) 4. `guidelines-violation`: the collection has been removed by the Steering Committee due to guidelines violation. Further details must be provided in `reason_text`. ([Official process](https://docs.ansible.com/projects/ansible/devel/community/collection_contributors/collection_package_removal.html#collections-not-satisfying-the-collection-requirements) .) 5. `other`: the collection has been removed for other reasons. Further explanation on why the collection will be removed must be provided in `reason_text`. * `announce_version`: optional string to indicate in which release of this Ansible major version the removal should be announced. When adding a new removal, use the next version that will be used for a release. A corresponding changelog entry will automatically be added to this version in the Ansible changelog. * `discussion`: optional string with an URL to the removal discussion in the forum. This link will be mentioned in the generated changelog entries and on the docsite. The following are a few examples of how `removal` metadata can look: `[](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-1) collections: [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-2) foo.bar_deprecated: [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-3) # In case a collection has been deprecated/abandoned by its maintainers. [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-4) repository: https://github.com/ansible-collections/foo.bar [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-5) removal: [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-6) major_version: 20 [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-7) reason: deprecated [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-8) announce_version: 11.2.0 [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-9) discussion: https://forum.ansible.com/t/.../ [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-10) foo.bar_unmaintained: [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-11) # In case the Steering Committee decided that a collection is effectively unmaintained. [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-12) repository: https://github.com/ansible-collections/foo.bar [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-13) removal: [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-14) major_version: 20 [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-15) reason: considered-unmaintained [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-16) announce_version: 11.2.0 [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-17) discussion: https://forum.ansible.com/t/.../ [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-18) foo.bar_renamed: [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-19) # Use this in case a collection has been renamed. [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-20) repository: https://github.com/ansible-collections/foo.bar [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-21) removal: [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-22) major_version: 20 # can be TBD if not yet known [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-23) reason: renamed [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-24) new_name: foo.bar_new_name [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-25) redirect_replacement_major_version: 13 # leave away if not yet known [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-26) announce_version: 11.2.0 [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-27) discussion: https://forum.ansible.com/t/.../ [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-28) foo.bar_guidelines_violation: [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-29) # In case the Steering Committe decided to remove the collection for guidelines violation. [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-30) repository: https://github.com/ansible-collections/foo.bar [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-31) removal: [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-32) major_version: 20 [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-33) reason: guidelines-violation [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-34) reason_text: >- [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-35) Extra text that must specify what happened. Can use L(Ansible markup, [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-36) https://docs.ansible.com/projects/ansible/devel/dev_guide/developing_modules_documenting.html#linking-within-module-documentation). [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-37) announce_version: 11.2.0 [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-38) discussion: https://forum.ansible.com/t/.../ [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-39) foo.bar_other: [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-40) # If the Steering Committee decides to remove a collection for a non-predefined reason. [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-41) repository: https://github.com/ansible-collections/foo.bar [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-42) removal: [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-43) major_version: 20 [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-44) reason: other [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-45) reason_text: >- [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-46) Text that must specify why the collection was removed. Can use L(Ansible markup, [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-47) https://docs.ansible.com/projects/ansible/devel/dev_guide/developing_modules_documenting.html#linking-within-module-documentation). [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-48) announce_version: 11.2.0 [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-1-49) discussion: https://forum.ansible.com/t/.../` You can use `antsibull-build lint-build-data --data-dir /path/to/ansible-build-data/X/ X` (where `X` is the major version) to validate the entries. ### Removing a collection[¶](https://docs.ansible.com/projects/ansible-build-data/policies/#removing-a-collection "Permanent link") If a collection should be removed from the upcoming Ansible major version, for which a metadata directory already exists but for which feature freeze has not yet happened, the collection needs to be removed from the build metadata. Also note that the removal should be announced in existing major versions, [see the previous section for details on that](https://docs.ansible.com/projects/ansible-build-data/policies/#announce-removal-of-a-collection-deprecation) . First, remove the collection's entries from `ansible.in`, `ansible-X.build`, and if necessary, `ansible-X.constraints`. Then the metadata in `collections-meta.yaml` needs to be updated: 1. For that, locate the collection in the `collections` list. Select the entry, copy it to the clipboard, and remove it from `collections`. 2. Locate the `removed_collections` list and the position where the collection should be inserted. Paste the copied entry from the clipboard. 3. If `removal` already exists, edit it as follows: * Replace `major_version` by `version`, and put in the exact Ansible version from which the collection is removed. **Note that this should not happen after the feature freeze!** * If `announce_version` is present, remove it. This removes the corresponding changelog entry if the Ansible changelog is regenerated, but that entry should not have been there unless the major version for removal got changed (in that case add an explicit manual entry to `changelog.yaml` if you want to keep the old entry). 4. If `removal` does not yet exist, create it [as described in the previous section](https://docs.ansible.com/projects/ansible-build-data/policies/#announce-removal-of-a-collection-deprecation) , with the changes as described in the previous point. As an example, consider the following metadata entry: `[](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-2-1) collections: [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-2-2) foo.bar: [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-2-3) repository: https://github.com/ansible-collections/foo.bar` This should be moved to `removed_collections` and changed as follows: `[](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-3-1) removed_collections: [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-3-2) foo.bar: [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-3-3) repository: https://github.com/ansible-collections/foo.bar [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-3-4) removal: [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-3-5) version: 20.0.0a1 [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-3-6) reason: deprecated [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-3-7) discussion: https://forum.ansible.com/t/.../` You can use `antsibull-build lint-build-data --data-dir /path/to/ansible-build-data/X/ X` (where `X` is the major version) to validate the entries. ### Cancel deprecation of a collection[¶](https://docs.ansible.com/projects/ansible-build-data/policies/#cancel-deprecation-of-a-collection "Permanent link") If a collection that is scheduled for removal in an upcoming major release should be kept, the removal metadata needs to be adjusted. The collection needs to be re-added in the build metadata for the upcoming major release if it has already been removed from there; [details for this can be found in the next subsection](https://docs.ansible.com/projects/ansible-build-data/policies/#re-adding-a-already-removed-collection) . Locate the `removal` entry for the collection in `collection-meta.yaml`'s `collections` list, and update it as follows: 1. If not there, add a `updates:` subkey. 2. Add an entry with `cancelled_version` (the Ansible release where the cancelation should be announced in the changelog) and `reason_text` (explanation), and optionally `discussion` (if a different discussion URL should be used). This can look as follows: `[](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-4-1) collections: [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-4-2) foo.bar: [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-4-3) repository: https://github.com/ansible-collections/foo.bar [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-4-4) removal: [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-4-5) major_version: 20 [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-4-6) reason: deprecated [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-4-7) announce_version: 12.3.0 [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-4-8) discussion: https://forum.ansible.com/t/.../ [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-4-9) updates: [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-4-10) - cancelled_version: 12.5.0 [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-4-11) reason_text: Maintenance of the collection has been taken over by L(someone else, https://...).` You can use `antsibull-build lint-build-data --data-dir /path/to/ansible-build-data/X/ X` (where `X` is the major version) to validate the entries. ### Re-adding a already removed collection[¶](https://docs.ansible.com/projects/ansible-build-data/policies/#re-adding-a-already-removed-collection "Permanent link") If a collection that has already been removed from the upcoming major version should be kept, the removal metadata needs to be adjusted. The removal needs to be canceled for previous major releases, [details for this can be found in the prevous subsection](https://docs.ansible.com/projects/ansible-build-data/policies/#cancel-deprecation-of-a-collection) . First, add the collection's entries to `ansible.in` and `ansible-X.build`. Then the metadata in `collections-meta.yaml` needs to be updated: 1. For that, locate the collection in the `removed_collections` list. Select the entry, copy it to the clipboard, and remove it from `removed_collections`. 2. Locate the `collections` list and the position where the collection should be inserted. Paste the copied entry from the clipboard. 3. If not there, add a `updates:` subkey. 4. Remove `announce_version` from the main `removal` entry and add it to a new `updates` entry with key `removed_version`. 5. Add an `updates` entry with `readded_version` (the Ansible release where the re-add should be announced in the changelog) and `reason_text` (explanation), and optionally `discussion` (if a different discussion URL should be used). As an example, consider the following metadata entry: `[](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-5-1) removed_collections: [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-5-2) foo.bar: [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-5-3) maintainers: [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-5-4) - Foo bar [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-5-5) repository: https://github.com/ansible-collections/foo.bar [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-5-6) removal: [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-5-7) version: 11.0.0a1 [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-5-8) reason: considered-unmaintained [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-5-9) discussion: https://forum.ansible.com/t/.../ [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-5-10) announce_version: 10.0.0a1` This should be moved to `collections` and changed as follows: `[](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-6-1) collections: [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-6-2) foo.bar: [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-6-3) maintainers: [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-6-4) - Foo bar [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-6-5) repository: https://github.com/ansible-collections/foo.bar [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-6-6) removal: [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-6-7) major_version: 11 [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-6-8) reason: considered-unmaintained [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-6-9) discussion: https://forum.ansible.com/t/.../ [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-6-10) updates: [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-6-11) - removed_version: 11.0.0a1 [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-6-12) - readded_version: 11.0.0b2 [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-6-13) reason_text: Maintenance of the collection has been taken over by L(another team, https://...).` You can use `antsibull-build lint-build-data --data-dir /path/to/ansible-build-data/X/ X` (where `X` is the major version) to validate the entries. ### Re-deprecating a collection[¶](https://docs.ansible.com/projects/ansible-build-data/policies/#re-deprecating-a-collection "Permanent link") It can happen that a collection is scheduled for removal (deprecated) that already was scheduled for removal before (or even has been removed before), but the removal was canceled or the removed collection re-added. In that case, updating the build metadata is a bit different from [announcing its removal the first time](https://docs.ansible.com/projects/ansible-build-data/policies/#announce-removal-of-a-collection-deprecation) . Then the metadata in `collections-meta.yaml` needs to be updated. The collection should be in `collections` and already have a `removal` subkey, and that should have a `updates` subkey. Simply add a new entry there with: 1. `redeprecated_version`: the exact Ansible version when the re-deprecation should be announced. 2. `discussion`: optional URL if a new discussion thread is used on the forum. If not provided, `discussion` from the `removal` entry will be used. 3. `reason`: a reason why the collection has been re-deprecated. Can be one of `deprecated`, `considered-unmaintained`, `renamed`, `guidelines-violation`, or `other`. 4. `reason_text`: can only be provided if `reason` is not provided, or if it is one of `other` and `guidelines-violation`. It always must be provided if `reason` is one of `other` and `guidelines-violation`. For example: `[](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-7-1) collections: [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-7-2) foo.bar: [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-7-3) maintainers: [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-7-4) - Foo bar [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-7-5) repository: https://github.com/ansible-collections/foo.bar [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-7-6) removal: [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-7-7) major_version: 11 [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-7-8) reason: considered-unmaintained [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-7-9) discussion: https://forum.ansible.com/t/.../ [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-7-10) updates: [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-7-11) - removed_version: 11.0.0a1 [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-7-12) - readded_version: 11.0.0b2 [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-7-13) reason_text: Maintenance of the collection has been taken over by L(another team, https://...). [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-7-14) - redeprecated_version: 11.3.0 [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-7-15) discussion: https://... [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-7-16) reason: guidelines-violation [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-7-17) reason_text: The guideline L(XXX, https://...) was violated.` You can use `antsibull-build lint-build-data --data-dir /path/to/ansible-build-data/X/ X` (where `X` is the major version) to validate the entries. Repository management[¶](https://docs.ansible.com/projects/ansible-build-data/policies/#repository-management "Permanent link") -------------------------------------------------------------------------------------------------------------------------------- ### Background[¶](https://docs.ansible.com/projects/ansible-build-data/policies/#background "Permanent link") From ansible 7.2.0 onwards, each release contains a `ansible-VERSION-tags.yaml` data file in this repository. This file contains a mapping of collections to their git repositories and the git tag that corresponds to the version of a collection included in the ansible release. The [Ansible release playbook](https://github.com/ansible-community/antsibull-build/blob/main/playbooks/build-single-release.yaml) generates this tags data file during the `antsibull-build prepare` step and later runs the `antsibull-build validate-tags-file` command to validate it. It is also possible to separately run `antsibull-build validate-tags-file`. For example, to validate [the tags file for ansible 7.5.0](https://github.com/ansible-community/ansible-build-data/blob/main/7/ansible-7.5.0-tags.yaml) , run `[](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-8-1) $ antsibull-build validate-tags-file 7/ansible-7.5.0-tags.yaml [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-8-2) cisco.nso 1.0.3 is not tagged in https://github.com/CiscoDevNet/ansible-nso [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-8-3) hpe.nimble 1.1.4 is not tagged in https://github.com/hpe-storage/nimble-ansible-modules [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-8-4) mellanox.onyx 1.0.0 is not tagged in https://github.com/ansible-collections/mellanox.onyx [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-8-5) $ echo $? [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-8-6) 1` Since these collections were not properly tagged prior to this policy's formalization, they are listed in [`7/validate-tags-ignores`](https://github.com/ansible-community/ansible-build-data/blob/main/7/validate-tags-ignores) . The release playbook passes that file to `antsibull-build validate-tags-file`'s `--ignores-file` flag to ignore errors for those collections. `[](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-9-1) $ antsibull-build validate-tags-file --ignores-file 7/validate-tags-ignores 7/ansible-7.5.0-tags.yaml [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-9-2) (no output) [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-9-3) $ echo $? [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-9-4) 0` When building future ansible versions, any untagged collections will cause `ansible-build validate-tags-file` to fail. ### Enforcement[¶](https://docs.ansible.com/projects/ansible-build-data/policies/#enforcement "Permanent link") Prior to ansible 9.0.0a1, the release playbook treats validation errors as warnings. In ansible 9.0.0a1 and onwards, these validation errors constitute release blockers. The playbook will fail if any new collection releases are not properly tagged. > **Note** > > It is recommended to run the release playbook with [`ANSIBLE_CALLBACK_RESULT_FORMAT=yaml`](https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/default_callback.html#parameter-result_format) > so error messages and any other playbook output are more legible. In case of violations, the release manager must preform the following steps: 1. First, the collection must be restricted to the previous tagged release in the `ansible-VERSION.constraints` file. Take the `community.docker` collection as an example. If its version 3.9.0 was released and correctly tagged, and 3.9.1 was released but not correctly tagged, add `[](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-10-1) community.docker: <3.9.1` 2. Commit only the changed `ansible-VERSION.constraints` file: `[](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-11-1) git add 8/ansible-8.constraints [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-11-2) git commit -m "pin community.docker to previous release"` 3. Rerun the release playbook. In this example, the ansible distribution will be built with community.docker 3.9.0 even though community.docker 3.9.1 is the latest version. 4. Proceed with the rest of the release process as normal. Commit the other changed files. The collection release PR should be applied using the `Rebase and merge` option (as opposed to `Squash and merge`) so the first commit can be more easily reverted when/if the collection fixes the issue. 5. The release manager or another community member needs to file an issue in the violating collection's issue tracker. This part should not block the current ansible package release, but the issue must have been filed before the following minor release. The following issue template can be used: ``[](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-12-1) Hi! As part of the ansible community package release process, we've determined that version {VERSION} of {COLLECTION} was released to Ansible Galaxy but not properly tagged in this Git repository. [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-12-2) This violates the [repository management][1] section of the Collection Requirements: [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-12-3) [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-12-4) [1]: https://docs.ansible.com/projects/ansible/devel/community/collection_contributors/collection_requirements.html#repository-management [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-12-5) [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-12-6) > Every collection MUST have a public git repository. Releases of the collection MUST be tagged in said repository. This means that releases MUST be `git tag`ed and that the tag name MUST exactly match the Galaxy version number. Tag names MAY have a `v` prefix, but a collection's tag names MUST have a consistent format from release to release. [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-12-7) > [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-12-8) > Additionally, collection artifacts released to Galaxy MUST be built from the sources that are tagged in the collection's git repository as that release. Any changes made during the build process MUST be clearly documented so the collection artifact can be reproduced. [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-12-9) [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-12-10) Until this issue is fixed, ansible package releases will contain {OLD VERSION}, the previous version of this collection that was properly tagged. If the collection maintainers do not respond to this issue within a reasonable amount of time, the collection is subject to [Removal from ansible][2]. [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-12-11) [](https://docs.ansible.com/projects/ansible-build-data/policies/#__codelineno-12-12) [2]: https://github.com/ansible-collections/overview/blob/main/removal_from_ansible.rst#collections-not-satisfying-the-collection-requirements`` 6. Post a comment in [https://github.com/ansible-community/ansible-build-data/issues/223](https://github.com/ansible-community/ansible-build-data/issues/223) with a link to the issue. --- # Contributing to Ansible Navigator - Ansible Navigator Documentation [Skip to content](https://docs.ansible.com/projects/navigator/contributing/guidelines/#getting-started-with-ansible-navigator) [](https://github.com/ansible/ansible-navigator/blob/main/docs/contributing/guidelines.md "Edit this page") Contributing to Ansible Navigator[¶](https://docs.ansible.com/projects/navigator/contributing/guidelines/#contributing-to-ansible-navigator "Permanent link") ============================================================================================================================================================== Details can be found below on how to run these manually, our CI will also check them for you. In order to contribute, you'll need to: 1. Fork the repository. 2. Create a branch, push your changes there. 3. Send it to us as a PR. 4. Iterate on your PR, incorporating the requested improvements and participating in the discussions. Prerequisites: 1. Have {doc}`tox `. 2. Use {doc}`tox ` to run the tests. 3. Before sending a PR, make sure that `lint` passes: `[](https://docs.ansible.com/projects/navigator/contributing/guidelines/#__codelineno-0-1) $ tox -e lint [](https://docs.ansible.com/projects/navigator/contributing/guidelines/#__codelineno-0-2) lint create: .tox/lint [](https://docs.ansible.com/projects/navigator/contributing/guidelines/#__codelineno-0-3) lint installdeps: .[test] [](https://docs.ansible.com/projects/navigator/contributing/guidelines/#__codelineno-0-4) lint installed: ... [](https://docs.ansible.com/projects/navigator/contributing/guidelines/#__codelineno-0-5) lint run-test-pre: PYTHONHASHSEED='4242713142' [](https://docs.ansible.com/projects/navigator/contributing/guidelines/#__codelineno-0-6) lint run-test: commands[0] | pylint ansible_navigator tests ... [](https://docs.ansible.com/projects/navigator/contributing/guidelines/#__codelineno-0-7) ... [](https://docs.ansible.com/projects/navigator/contributing/guidelines/#__codelineno-0-8) _________________________________ summary __________________________________ [](https://docs.ansible.com/projects/navigator/contributing/guidelines/#__codelineno-0-9) lint: commands succeeded [](https://docs.ansible.com/projects/navigator/contributing/guidelines/#__codelineno-0-10) congratulations :)` Notice Because the version of python is pinned to a specific version to ensure the outcome of running `tox -e lint` locally is the same as `tox -e lint` being run by github actions, you may see the following error: `RuntimeError: failed to find interpreter for Builtin discover of python_spec='python3.XX'`. This indicates the version of python that needs to be installed for tox to run locally. In this case, the version of python that needs to be installed is Getting started with Ansible Navigator[¶](https://docs.ansible.com/projects/navigator/contributing/guidelines/#getting-started-with-ansible-navigator "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ ### Building from the source and installing packages for testing[¶](https://docs.ansible.com/projects/navigator/contributing/guidelines/#building-from-the-source-and-installing-packages-for-testing "Permanent link") After cloning the repository, create and activate a new [virtual environment](https://docs.python.org/3/library/venv.html) in the root of the repository. Once that is done all we need is to install ansible-navigator from the source. Use the following command in workspace (root folder of navigator).This will install package in editable/development mode, along with its additional dependencies required for testing. `[](https://docs.ansible.com/projects/navigator/contributing/guidelines/#__codelineno-1-1) pip install -e .\[test]` In case of any errors, try to run `pip install --upgrade pip`. Then run the above command again. ### Testing process and examples[¶](https://docs.ansible.com/projects/navigator/contributing/guidelines/#testing-process-and-examples "Permanent link") Once all the dependencies are installed, we can execute our tests using [pytest](https://docs.pytest.org/en/7.3.x/) . To run tests inside a file test\_xyz.py, we will need to traverse to that file. Example: To run an unit test "test\_circular\_imports.py", we will execute: `pytest tests/unit/test_circular_imports.py` Example: To run an integration test "test\_stdout\_vault.py ", we will execute: `pytest tests/integration/actions/exec/test_stdout_vault.py` and so on ... Additionally, leverage the ability of VSCode test tree to run and debug tests in a more easier and interactive way. There is a dedicated configuration provided inside launch.json named as **Debug tests** to interactively debug the tests through VSCode test tree. Hover to the **Testing** icon in the Activity Bar to see VSCode test tree. From there expand and reach to the desired unit or integration test and hit `Run Test` or `Debug Test` appropriately. ![VSCode test tree](https://docs.ansible.com/projects/navigator/contributing/images/test_tree_view.png) ### Overview of Base Entry Points and Summary of src files[¶](https://docs.ansible.com/projects/navigator/contributing/guidelines/#overview-of-base-entry-points-and-summary-of-src-files "Permanent link") * `src/ansible_navigator/cli.py` acts as the main entry point where the application starts. * `src/ansible_navigator/ui.py` contains show() function which is the entry point for rendering the UI. * `src/ansible_navigator/actions` has the implementation of all the actions ansible-navigator can perform (i.e. its [subcommands](https://ansible-navigator.readthedocs.io/subcommands/) ) like run, collections, images, doc, inventory, settings and a lot more. * `src/ansible_navigator/command_runner` command runner is a wrapper around subprocess to run shell commands. * `src/ansible_navigator/configuration_subsystem` herein lies the logic behind all the CLI parameters from their declaration to processing. * `src/ansible_navigator/data` this directory includes non-python files and stand alone scripts that will be run from inside an execution environment. * `src/ansible_navigator/image_manager` contains all the operations related to introspect, access, pull container images. * `src/ansible_navigator/runner` herein lies ability for all the interaction with ansible-runner. * `src/ansible_navigator/tm_tokenize` has the tokenization subsystem which allows for syntax highlighting of json and yaml files. * `src/ansible_navigator/ui_framework` has the implementation of our user-interface. * `src/ansible_navigator/utils` consists of all the common utilities use throughout the application. ### Configure VSCode settings[¶](https://docs.ansible.com/projects/navigator/contributing/guidelines/#configure-vscode-settings "Permanent link") Once we are inside vscode with project installed, we should see a `.vscode` folder in our workspace. Having a launch configuration file is beneficial because it allow us to configure and save debugging setup details. VS Code keeps debugging configuration information in a `launch.json` file located in a `.vscode` folder in our workspace (project root folder). Similarly, The workspace settings file `settings.json` is also located under the `.vscode` folder in our root folder. These are the project specific settings shared by all users of that project. Use the existing settings or drop in the required changes in configuration of these `launch.json` and `settings.json` files. Now, the final steps! * Put breakpoint(s) in the code where needed. * Hover to the **Run and Debug** icon in the Activity Bar to start the debugger. At this point, the debugger should hit your breakpoint and start the debugging session. ### Debug Ansible-Navigator Subcommands[¶](https://docs.ansible.com/projects/navigator/contributing/guidelines/#debug-ansible-navigator-subcommands "Permanent link") Ansible-Navigator comes in with bunch of [subcommands](https://ansible-navigator.readthedocs.io/subcommands/) . To debug around any specific subcommand, use the **Run and Debug** drop down menu to select the appropriate entry from launch.json configuration. We add `args` attribute (arguments passed to the program to debug) in our launch.json configuration file. **Example:** * To Debug `ansible-navigator run` subcommand, use _args_ attribute, provide playbook name and absolute path to the playbook in _cwd_. Following configuration will allow to debug `ansible-navigator site.yml --mode stdout`. `[](https://docs.ansible.com/projects/navigator/contributing/guidelines/#__codelineno-2-1) { [](https://docs.ansible.com/projects/navigator/contributing/guidelines/#__codelineno-2-2) "version": "0.2.0", [](https://docs.ansible.com/projects/navigator/contributing/guidelines/#__codelineno-2-3) "configurations": [ [](https://docs.ansible.com/projects/navigator/contributing/guidelines/#__codelineno-2-4) { [](https://docs.ansible.com/projects/navigator/contributing/guidelines/#__codelineno-2-5) "name": "Debug subcommand: run", [](https://docs.ansible.com/projects/navigator/contributing/guidelines/#__codelineno-2-6) "type": "python", [](https://docs.ansible.com/projects/navigator/contributing/guidelines/#__codelineno-2-7) "request": "launch", [](https://docs.ansible.com/projects/navigator/contributing/guidelines/#__codelineno-2-8) "module": "ansible_navigator", [](https://docs.ansible.com/projects/navigator/contributing/guidelines/#__codelineno-2-9) "args": ["run", "site.yml", "--mode", "stdout"], [](https://docs.ansible.com/projects/navigator/contributing/guidelines/#__codelineno-2-10) "cwd": "/home/user/../path/to/the/playbook", [](https://docs.ansible.com/projects/navigator/contributing/guidelines/#__codelineno-2-11) "justMyCode": false [](https://docs.ansible.com/projects/navigator/contributing/guidelines/#__codelineno-2-12) } [](https://docs.ansible.com/projects/navigator/contributing/guidelines/#__codelineno-2-13) ] [](https://docs.ansible.com/projects/navigator/contributing/guidelines/#__codelineno-2-14) }` Similar configuration entries are present inside the launch.json file to debug different subcommands. Choose an entry from the drop-down while debugging and modify accordingly if needed. ### Useful Links[¶](https://docs.ansible.com/projects/navigator/contributing/guidelines/#useful-links "Permanent link") * VS code debugging [guide](https://code.visualstudio.com/docs/editor/debugging) . * Facilitate [Python Debugger](https://www.geeksforgeeks.org/python-debugger-python-pdb/) (pdb) in navigator for pure command line debugging. Contributing docs[¶](https://docs.ansible.com/projects/navigator/contributing/guidelines/#contributing-docs "Permanent link") ------------------------------------------------------------------------------------------------------------------------------ The documentation source code is located under the [docs](https://github.com/ansible/ansible-navigator/tree/main/docs) directory in the repository's root. We use [mkdocs](https://www.mkdocs.org/) to generate our docs website. You can trigger the process locally by executing: `[](https://docs.ansible.com/projects/navigator/contributing/guidelines/#__codelineno-3-1) $ tox -e docs [](https://docs.ansible.com/projects/navigator/contributing/guidelines/#__codelineno-3-2) ...` It is also integrated with [Read The Docs](https://readthedocs.org/) that builds and publishes each commit to the main branch and generates live docs previews for each pull request. --- # Contributing - Ansible Lint Documentation [Skip to content](https://docs.ansible.com/projects/lint/contributing/#contributing-to-ansible-lint) [](https://github.com/ansible/ansible-lint/blob/main/docs/contributing.md "Edit this page") [](https://github.com/ansible/ansible-lint/raw/main/docs/contributing.md "View source of this page") Contributing to Ansible-lint[¶](https://docs.ansible.com/projects/lint/contributing/#contributing-to-ansible-lint "Permanent link") ==================================================================================================================================== To contribute to ansible-lint, please use pull requests on a branch of your own fork. After [creating your fork on GitHub](https://docs.github.com/en/get-started/quickstart/contributing-to-projects) , you can do: `[](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-1) $ git clone --recursive git@github.com:your-name/ansible-lint [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-2) $ cd ansible-lint [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-3) $ # Recommended: Initialize and activate a Python virtual environment [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-4) $ pip install --upgrade pip [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-5) $ pip install -e '.[test]' # Install testing dependencies [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-6) $ tox run -e lint,pkg,docs,py # Ensure subset of tox tests work in clean checkout [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-7) $ git checkout -b your-branch-name [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-8) # DO SOME CODING HERE [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-9) $ tox run -e lint,pkg,docs,py # Ensure subset of tox tests work with your changes [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-10) $ git add your new files [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-11) $ git commit -v [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-12) $ git push origin your-branch-name` You will then be able to create a pull request from your commit. All fixes to core functionality (i.e. anything except docs or examples) should be accompanied by tests that fail prior to your change and succeed afterwards. Feel free to raise issues in the repo if you feel unable to contribute a code fix. Standards[¶](https://docs.ansible.com/projects/lint/contributing/#standards "Permanent link") ---------------------------------------------------------------------------------------------- ansible-lint works only with supported Ansible versions at the time it was released. Automated tests will be run against all PRs, to run checks locally before pushing commits, just use [tox](https://tox.wiki/en/latest/) . Talk to us[¶](https://docs.ansible.com/projects/lint/contributing/#talk-to-us "Permanent link") ------------------------------------------------------------------------------------------------ Connect with the Ansible community! Join the Ansible forum to ask questions, get help, and interact with the community. * [Get Help](https://forum.ansible.com/c/help/6) : get help or help others. Please add appropriate tags if you start new discussions, for example use the `ansible-lint` or `devtools` tags. * [Social Spaces](https://forum.ansible.com/c/chat/4) : meet and interact with fellow enthusiasts. * [News & Announcements](https://forum.ansible.com/c/news/5) : track project-wide announcements including social events. To get release announcements and important changes from the community, see the [Bullhorn newsletter](https://docs.ansible.com/projects/ansible/devel/community/communication.html#the-bullhorn) . For a live chat experience join the [#devtools:ansible.com](https://matrix.to/#/#devtools:ansible.com) Matrix room. You can find more information in the [Ansible communication guide](https://docs.ansible.com/projects/ansible/devel/community/communication.html) . Possible security bugs should be reported via email to [security@ansible.com](mailto:security@ansible.com) . Code of Conduct[¶](https://docs.ansible.com/projects/lint/contributing/#code-of-conduct "Permanent link") ---------------------------------------------------------------------------------------------------------- As with all Ansible projects, we have a [Code of Conduct](https://docs.ansible.com/projects/ansible/latest/community/code_of_conduct.html) . Module dependency graph[¶](https://docs.ansible.com/projects/lint/contributing/#module-dependency-graph "Permanent link") -------------------------------------------------------------------------------------------------------------------------- Extra care should be taken when considering adding any dependency. Removing most dependencies on Ansible internals is desired as these can change without any warning. `[](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-1) uv pip tree --package ansible-lint --show-version-specifiers --strict [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-2) Using Python 3.14.3 environment at: .tox/docs [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-3) ansible-lint v26.3.1.dev12 [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-4) ├── ansible-compat v26.3.0 [required: >=26.3.0] [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-5) │ ├── ansible-core v2.20.3 [required: >=2.16] [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-6) │ │ ├── cryptography v46.0.6 [required: *] [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-7) │ │ │ └── cffi v2.0.0 [required: >=2.0.0] [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-8) │ │ │ └── pycparser v3.0 [required: *] [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-9) │ │ ├── jinja2 v3.1.6 [required: >=3.1.0] [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-10) │ │ │ └── markupsafe v3.0.3 [required: >=2.0] [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-11) │ │ ├── packaging v26.0 [required: *] [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-12) │ │ ├── pyyaml v6.0.3 [required: >=5.1] [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-13) │ │ └── resolvelib v1.2.1 [required: >=0.8.0, <2.0.0] [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-14) │ ├── jsonschema v4.26.0 [required: >=4.6.0] [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-15) │ │ ├── attrs v25.4.0 [required: >=22.2.0] [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-16) │ │ ├── jsonschema-specifications v2025.9.1 [required: >=2023.3.6] [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-17) │ │ │ └── referencing v0.37.0 [required: >=0.31.0] [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-18) │ │ │ ├── attrs v25.4.0 [required: >=22.2.0] [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-19) │ │ │ └── rpds-py v0.30.0 [required: >=0.7.0] [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-20) │ │ ├── referencing v0.37.0 [required: >=0.28.4] (*) [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-21) │ │ └── rpds-py v0.30.0 [required: >=0.25.0] [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-22) │ ├── packaging v26.0 [required: >=22.0] [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-23) │ ├── pyyaml v6.0.3 [required: >=6.0.1] [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-24) │ └── subprocess-tee v0.4.2 [required: >=0.4.1] [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-25) ├── ansible-core v2.20.3 [required: >=2.16.14] (*) [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-26) ├── black v26.3.1 [required: >=24.3.0] [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-27) │ ├── click v8.3.1 [required: >=8.0.0] [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-28) │ ├── mypy-extensions v1.1.0 [required: >=0.4.3] [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-29) │ ├── packaging v26.0 [required: >=22.0] [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-30) │ ├── pathspec v1.0.4 [required: >=1.0.0] [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-31) │ ├── platformdirs v4.9.4 [required: >=2] [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-32) │ └── pytokens v0.4.1 [required: ~=0.4.0] [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-33) ├── cffi v2.0.0 [required: >=1.15.1] (*) [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-34) ├── cryptography v46.0.6 [required: >=37] (*) [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-35) ├── distro v1.9.0 [required: >=1.9.0] [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-36) ├── filelock v3.25.2 [required: >=3.8.2] [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-37) ├── jsonschema v4.26.0 [required: >=4.10.0] (*) [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-38) ├── packaging v26.0 [required: >=22.0] [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-39) ├── pathspec v1.0.4 [required: >=1.0.3, <1.1.0] [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-40) ├── pyyaml v6.0.3 [required: >=6.0.1] [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-41) ├── referencing v0.37.0 [required: >=0.36.2] (*) [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-42) ├── ruamel-yaml v0.19.1 [required: >=0.18.11] [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-43) ├── subprocess-tee v0.4.2 [required: >=0.4.1] [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-44) ├── wcmatch v10.1 [required: >=8.5.0] [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-45) │ └── bracex v2.6 [required: >=2.1.1] [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-46) └── yamllint v1.38.0 [required: >=1.38.0] [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-47) ├── pathspec v1.0.4 [required: >=1.0.0] [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-48) └── pyyaml v6.0.3 [required: *] [](https://docs.ansible.com/projects/lint/contributing/#__codelineno-0-49) (*) Package tree already displayed` Adding a new rule[¶](https://docs.ansible.com/projects/lint/contributing/#adding-a-new-rule "Permanent link") -------------------------------------------------------------------------------------------------------------- Writing a new rule is as easy as adding a single new rule, one that combines **implementation, testing and documentation**. One good example is [MetaTagValidRule](https://github.com/ansible/ansible-lint/blob/main/src/ansiblelint/rules/meta_no_tags.py) which can easily be copied in order to create a new rule by following the steps below: * Use a short but clear class name, which must match the filename * Pick an unused `id`, the first number is used to determine rule section. Look at [rules](https://docs.ansible.com/projects/lint/rules/) page and pick one that matches the best your new rule and ee which one fits best. * Include `experimental` tag. Any new rule must stay as experimental for at least two weeks until this tag is removed in next major release. * Update all class level variables. * Implement linting methods needed by your rule, these are those starting with **match** prefix. Implement only those you need. For the moment you will need to look at how similar rules were implemented to figure out what to do. * Update the tests. It must have at least one test and likely also a negative match one. * If the rule is task specific, it may be best to include a test to verify its use inside blocks as well. * Optionally run only the rule specific tests with a command like: `tox -e py -- -k NewRule` * Run `tox` in order to run all ansible-lint tests. Adding a new rule can break some other tests. Update them if needed. * Run `ansible-lint -L` and check that the rule description renders correctly. * Build the docs using `tox -e docs` and check that the new rule is displayed correctly in them. Documentation changes[¶](https://docs.ansible.com/projects/lint/contributing/#documentation-changes "Permanent link") ---------------------------------------------------------------------------------------------------------------------- To build the docs, run `tox -e docs`. At the end of the build, you will see the local location of your built docs. Building docs locally may not be identical to CI/CD builds. We recommend you to create a draft PR and check the RTD PR preview page too. If you do not want to learn the reStructuredText format, you can also [file an issue](https://github.com/ansible/ansible-lint/issues) , and let us know how we can improve our documentation. Back to top --- # Execution Environment - Ansible Development Tools Documentation [Skip to content](https://docs.ansible.com/projects/dev-tools/container/#community-ansible-dev-tools) [](https://github.com/ansible/ansible-dev-tools/blob/main/docs/container.md "Edit this page") [](https://github.com/ansible/ansible-dev-tools/raw/main/docs/container.md "View source of this page") community-ansible-dev-tools[¶](https://docs.ansible.com/projects/dev-tools/container/#community-ansible-dev-tools "Permanent link") ==================================================================================================================================== A container image for Ansible Development Tools (ADT). This image is built on top of [Fedora minimal](https://quay.io/repository/fedora/fedora-minimal?tab=info) and has container-in-container support with [`podman`](https://podman.io/docs) . The current version in use can be found in the [`execution-environment.yml`](https://github.com/ansible/ansible-dev-tools/blob/main/execution-environment.yml) file used for the base layer. Installation[¶](https://docs.ansible.com/projects/dev-tools/container/#installation "Permanent link") ------------------------------------------------------------------------------------------------------ `[](https://docs.ansible.com/projects/dev-tools/container/#__codelineno-0-1) podman pull ghcr.io/ansible/community-ansible-dev-tools:latest` Usage[¶](https://docs.ansible.com/projects/dev-tools/container/#usage "Permanent link") ---------------------------------------------------------------------------------------- ### Using this as a VS code Dev Container[¶](https://docs.ansible.com/projects/dev-tools/container/#using-this-as-a-vs-code-dev-container "Permanent link") Dev Containers provide you with a containerized development environment in VS code. Details on what they are and how to use them can be found in [Developing inside a Container](https://code.visualstudio.com/docs/devcontainers/containers) . This image can be used as an image for a Dev Container where you build and consume Ansible content. This repository comes with a sample [`.devcontainer directory`](https://github.com/ansible/ansible-dev-tools/tree/main/.devcontainer) with 2 subdirectories - `podman` and `docker` each having its own `devcontainer.json` file. You can simply copy over the `.devcontainer` directory to your Ansible project and start using it! ### Using this with Github Codespaces[¶](https://docs.ansible.com/projects/dev-tools/container/#using-this-with-github-codespaces "Permanent link") To use this image with [Github Codespaces](https://docs.github.com/en/codespaces/overview) , copy the [`devcontainer.json`](https://github.com/ansible/ansible-dev-tools/blob/main/.devcontainer/devcontainer.json) in this repo to your project and push to Github. **Note:** If you are planning to start writing a new Ansible playbook project or collection, use [Ansible Creator](https://ansible.readthedocs.io/projects/creator) to scaffold it for you and your project/collection will already have all the `.devcontainer` files ready. ### Using this image as an EE[¶](https://docs.ansible.com/projects/dev-tools/container/#using-this-image-as-an-ee "Permanent link") This image can also be used as an Ansible Execution Environment (EE). If you're not familiar with what an EE is, checkout the documentation in [Getting started with EE](https://docs.ansible.com/ansible/devel/getting_started_ee/index.html) . It is shipped with the following Ansible collections: * ansible.netcommon * ansible.posix * ansible.scm * ansible.utils You can also create a new EE based on this with more Ansible collections (or Python/System packages) of your choice by using Ansible Builder. Read this [documentation](https://ansible.readthedocs.io/projects/builder/en/latest/) to know about ansible-builder. The below example shows how to make a custom EE that adds the `amazon.aws` and `cisco.nxos` collections as well as the `ansible-pylibssh` python package to this image. 1. Create an `execution-environment.yml` file with the following content. execution-environment.yml `[](https://docs.ansible.com/projects/dev-tools/container/#__codelineno-1-1) --- [](https://docs.ansible.com/projects/dev-tools/container/#__codelineno-1-2) version: 3 [](https://docs.ansible.com/projects/dev-tools/container/#__codelineno-1-3) [](https://docs.ansible.com/projects/dev-tools/container/#__codelineno-1-4) images: [](https://docs.ansible.com/projects/dev-tools/container/#__codelineno-1-5) base_image: [](https://docs.ansible.com/projects/dev-tools/container/#__codelineno-1-6) name: ghcr.io/ansible/community-ansible-dev-tools:latest [](https://docs.ansible.com/projects/dev-tools/container/#__codelineno-1-7) [](https://docs.ansible.com/projects/dev-tools/container/#__codelineno-1-8) dependencies: [](https://docs.ansible.com/projects/dev-tools/container/#__codelineno-1-9) galaxy: requirements.yml [](https://docs.ansible.com/projects/dev-tools/container/#__codelineno-1-10) python: requirements.txt [](https://docs.ansible.com/projects/dev-tools/container/#__codelineno-1-11) [](https://docs.ansible.com/projects/dev-tools/container/#__codelineno-1-12) options: [](https://docs.ansible.com/projects/dev-tools/container/#__codelineno-1-13) package_manager_path: /usr/bin/dnf5` 1. Populate `requirements.txt` and `requirements.yml` with the respective contents. requirements.txt `[](https://docs.ansible.com/projects/dev-tools/container/#__codelineno-2-1) ansible-pylibssh==1.1.0` 1. Use `ansible-builder` to create the new EE. `[](https://docs.ansible.com/projects/dev-tools/container/#__codelineno-3-1) ansible-builder build -t custom-ee:latest --prune-images -v3` Once this image is built, you can use [`ansible-navigator`](https://ansible.readthedocs.io/projects/navigator/) to reference this image and run your playbooks! ### Using with podman from the command-line[¶](https://docs.ansible.com/projects/dev-tools/container/#using-with-podman-from-the-command-line "Permanent link") If you want to use this image with `podman` the following command to run the container. `[](https://docs.ansible.com/projects/dev-tools/container/#__codelineno-4-1) podman run -it --rm \ [](https://docs.ansible.com/projects/dev-tools/container/#__codelineno-4-2) --cap-add=SYS_ADMIN \ [](https://docs.ansible.com/projects/dev-tools/container/#__codelineno-4-3) --cap-add=SYS_RESOURCE \ [](https://docs.ansible.com/projects/dev-tools/container/#__codelineno-4-4) --device "/dev/fuse" \ [](https://docs.ansible.com/projects/dev-tools/container/#__codelineno-4-5) --hostname=ansible-dev-container \ [](https://docs.ansible.com/projects/dev-tools/container/#__codelineno-4-6) --name=ansible-dev-container \ [](https://docs.ansible.com/projects/dev-tools/container/#__codelineno-4-7) --security-opt "apparmor=unconfined" \ [](https://docs.ansible.com/projects/dev-tools/container/#__codelineno-4-8) --security-opt "label=disable" \ [](https://docs.ansible.com/projects/dev-tools/container/#__codelineno-4-9) --security-opt "seccomp=unconfined" \ [](https://docs.ansible.com/projects/dev-tools/container/#__codelineno-4-10) --user=root \ [](https://docs.ansible.com/projects/dev-tools/container/#__codelineno-4-11) --userns=host \ [](https://docs.ansible.com/projects/dev-tools/container/#__codelineno-4-12) -e SSH_AUTH_SOCK=$SSH_AUTH_SOCK \ [](https://docs.ansible.com/projects/dev-tools/container/#__codelineno-4-13) -v $HOME/.gitconfig:/root/.gitconfig \ [](https://docs.ansible.com/projects/dev-tools/container/#__codelineno-4-14) -v $PWD:/workdir \ [](https://docs.ansible.com/projects/dev-tools/container/#__codelineno-4-15) -v $SSH_AUTH_SOCK:$SSH_AUTH_SOCK \ [](https://docs.ansible.com/projects/dev-tools/container/#__codelineno-4-16) ghcr.io/ansible/community-ansible-dev-tools:latest` Note: * The `security-opt` and `cap-add` options are used to allow `podman` to run in the container. * The `device` option is used to allow the container to access the `/dev/fuse` device. * `userns=host` maps the default user account to root user in container. * This command will mount the current directory to `/workdir` in the container * The SSH agent socket is also mounted to the container to allow for SSH key forwarding. * The user's `.gitconfig` is mounted to the container to allow for git operations. ### Signing git commits (SSH)[¶](https://docs.ansible.com/projects/dev-tools/container/#signing-git-commits-ssh "Permanent link") If the `user.signingkey` in the `gitconfig` points directly public key on the file system that key may not be available in the container. If only one key is preset, the `ssh-add` command can be used for key retrieval in the user's `gitconfig`: ~/.gitconfig `[](https://docs.ansible.com/projects/dev-tools/container/#__codelineno-5-1) [gpg "ssh"] [](https://docs.ansible.com/projects/dev-tools/container/#__codelineno-5-2) defaultKeyCommand = ssh-add -L` Alternatively, the public key can added in-line in the `gitconfig` ~/.gitconfig `[](https://docs.ansible.com/projects/dev-tools/container/#__codelineno-6-1) [user] [](https://docs.ansible.com/projects/dev-tools/container/#__codelineno-6-2) email = johnd@acme.com [](https://docs.ansible.com/projects/dev-tools/container/#__codelineno-6-3) name = John Doe [](https://docs.ansible.com/projects/dev-tools/container/#__codelineno-6-4) signingkey = key:: ssh-rsa ...` ### Layering ADT and container-in-container support on a custom image[¶](https://docs.ansible.com/projects/dev-tools/container/#layering-adt-and-container-in-container-support-on-a-custom-image "Permanent link") To add the Ansible Devtools package and the container-in-container support with podman using a custom EE or another container image, you can use to the [final Containerfile](https://github.com/ansible/ansible-dev-tools/blob/main/final/Containerfile) from this repository. Update the `FROM` instruction to point to your preferred image and build it using `podman` or `docker`. **Note:** The container-in-container support is added with the help of the [podman image](https://github.com/containers/image_build/tree/main/podman) definition. For more information, read [How to use Podman inside of a container](https://www.redhat.com/sysadmin/podman-inside-container) . Related Links[¶](https://docs.ansible.com/projects/dev-tools/container/#related-links "Permanent link") -------------------------------------------------------------------------------------------------------- * [ansible-builder](https://github.com/ansible/ansible-builder) * [ansible-creator](https://github.com/ansible/ansible-creator) * [podman](https://github.com/containers/podman/) Back to top --- # Running nox in CI - antsibull-nox – Antsibull Nox Helper [Skip to content](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#running-nox-in-ci) Running nox in CI[¶](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#running-nox-in-ci "Permanent link") ==================================================================================================================== GitHub Actions[¶](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#github-actions "Permanent link") -------------------------------------------------------------------------------------------------------------- The antsibull-nox repository contains a GitHub Action which makes it easy to run nox in GitHub's CI. The action takes care of installing Python, nox, and antsibull-nox, and separating environment setup from actually running the environments. The following GitHub workflow demonstrates how the action can be used. It is taken from the community.dns collection. `[](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-0-1) --- [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-0-2) name: nox [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-0-3) 'on': [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-0-4) push: [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-0-5) branches: [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-0-6) - main [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-0-7) - stable-* [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-0-8) pull_request: [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-0-9) # Run CI once per day (at 07:30 UTC) [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-0-10) schedule: [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-0-11) - cron: '30 7 * * *' [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-0-12) workflow_dispatch: [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-0-13) [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-0-14) jobs: [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-0-15) nox: [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-0-16) runs-on: ubuntu-latest [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-0-17) name: "Run nox" [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-0-18) steps: [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-0-19) - name: Check out collection [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-0-20) uses: actions/checkout@v5 [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-0-21) with: [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-0-22) persist-credentials: false [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-0-23) - name: Run nox [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-0-24) uses: ansible-community/antsibull-nox@main` Info The workflow uses the `main` branch of the `ansible-community/antsibull-nox` action. This is generally not a good idea, since there can be breaking changes any time. You can use the `stable-1` branch to get updates less often, but only after they have been tested on `main` for some time. ### Run extra sanity tests with change detection[¶](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#run-extra-sanity-tests-with-change-detection "Permanent link") While the action provided by the antsibull-nox repository allows to do change detection, you will have to do the repository setup yourself. If you like a simple solution, you can use a provided shared workflow for this. `[](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-1-1) --- [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-1-2) name: nox [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-1-3) 'on': [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-1-4) push: [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-1-5) branches: [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-1-6) - main [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-1-7) - stable-* [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-1-8) pull_request: [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-1-9) # Run CI once per day (at 07:30 UTC) [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-1-10) schedule: [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-1-11) - cron: '30 7 * * *' [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-1-12) workflow_dispatch: [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-1-13) [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-1-14) jobs: [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-1-15) nox: [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-1-16) uses: ansible-community/antsibull-nox/.github/workflows/reusable-nox-run.yml@main [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-1-17) with: [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-1-18) session-name: Run extra sanity tests [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-1-19) change-detection-in-prs: true` ### Running ansible-test CI matrix from nox[¶](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#running-ansible-test-ci-matrix-from-nox "Permanent link") If you use the `[sessions.ansible_test_sanity]`, `[sessions.ansible_test_units]`, `[sessions.ansible_test_integration_w_default_container]`, or `[sessions.ee_check]` sections in `antsibull-nox.toml`, or the `antsibull_nox.add_ansible_test_session()` function in `noxfile.py` to add specific `ansible-test` sessions, then you can use the shared workflow [ansible-community/antsibull-nox/.github/workflows/reusable-nox-matrix.yml@main](https://github.com/ansible-community/antsibull-nox/blob/main/.github/workflows/reusable-nox-matrix.yml) to generate a CI matrix and run the `ansible-test` jobs: The following example is taken from community.dns, with comments indicating further options: `[](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-2-1) --- [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-2-2) name: nox [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-2-3) 'on': [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-2-4) push: [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-2-5) branches: [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-2-6) - main [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-2-7) - stable-* [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-2-8) pull_request: [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-2-9) # Run CI once per day (at 04:30 UTC) [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-2-10) schedule: [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-2-11) - cron: '30 4 * * *' [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-2-12) workflow_dispatch: [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-2-13) [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-2-14) jobs: [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-2-15) ansible-test: [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-2-16) uses: ansible-community/antsibull-nox/.github/workflows/reusable-nox-matrix.yml@main [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-2-17) with: [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-2-18) upload-codecov: true [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-2-19) # To explicitly disable codecov upload for specific events, you can set: [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-2-20) # upload-codecov-pr: false [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-2-21) # upload-codecov-schedule: false [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-2-22) # upload-codecov-push: false [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-2-23) # You can also enable change detection in PRs, [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-2-24) # but that will disable codecov uploading in PRs. [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-2-25) # To enable it, simply add: [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-2-26) # change-detection-in-prs: true [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-2-27) # You can limit the ansible-core version with: [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-2-28) # min-ansible-core: "2.15" [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-2-29) # max-ansible-core: "2.18" [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-2-30) # You can limit to all the given tags being present: [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-2-31) # include-tags: tag1, tag2, tag3 [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-2-32) # You can limit to all the given tags being absent: [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-2-33) # exclude-tags: tag1, tag2, tag3 [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-2-34) secrets: [](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/#__codelineno-2-35) CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}` --- # Getting started - antsibull-nox – Antsibull Nox Helper [Skip to content](https://docs.ansible.com/projects/antsibull-nox/getting-started/#getting-started-with-antsibull-nox) Getting started with antsibull-nox[¶](https://docs.ansible.com/projects/antsibull-nox/getting-started/#getting-started-with-antsibull-nox "Permanent link") ============================================================================================================================================================ `antsibull-nox` is a tool for testing [Ansible collections](https://docs.ansible.com/ansible/devel/collections_guide/) . Before you get started, ensure that you: * [Create an Ansible collection](https://docs.ansible.com/ansible/devel/dev_guide/developing_modules_in_groups.html) or have a collection project available. * Become familiar with the basics of [developing collections](https://docs.ansible.com/ansible/devel/dev_guide/developing_collections.html) . Adding basic tests to your collection[¶](https://docs.ansible.com/projects/antsibull-nox/getting-started/#adding-basic-tests-to-your-collection "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------------------------------ `antsibull-nox` defines collection tests in a `noxfile.py` file. 1. Run `antsibull-nox init` in the root of your collection. The root is the directory that contains `galaxy.yml`. That creates the `noxfile.py` and `antsibull-nox.toml` files shown below. 2. Ensure your `galaxy.yml` file contains values for the `name` and `namespace` fields at a minimum. The **`noxfile.py`** file: ``[](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-0-1) # The following metadata allows Python runners and nox to install the required [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-0-2) # dependencies for running this Python script: [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-0-3) # [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-0-4) # /// script [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-0-5) # dependencies = ["nox>=2025.02.09", "antsibull-nox"] [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-0-6) # /// [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-0-7) [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-0-8) import sys [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-0-9) [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-0-10) import nox [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-0-11) [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-0-12) [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-0-13) # We try to import antsibull-nox, and if that doesn't work, provide a more useful [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-0-14) # error message to the user. [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-0-15) try: [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-0-16) import antsibull_nox [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-0-17) except ImportError: [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-0-18) print("You need to install antsibull-nox in the same Python environment as nox.") [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-0-19) sys.exit(1) [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-0-20) [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-0-21) [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-0-22) antsibull_nox.load_antsibull_nox_toml() [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-0-23) [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-0-24) [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-0-25) # Allow to run the noxfile with `python noxfile.py`, `pipx run noxfile.py`, or similar. [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-0-26) # Requires nox >= 2025.02.09 [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-0-27) if __name__ == "__main__": [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-0-28) nox.main()`` The **`antsibull-nox.toml`** file: `[](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-1-1) [sessions] [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-1-2) [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-1-3) [sessions.lint] [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-1-4) # disable reformatting for now [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-1-5) run_isort = false [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-1-6) [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-1-7) # disable reformatting for now [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-1-8) run_black = false [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-1-9) [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-1-10) # Add more configuration settings here to adjust to your collection; [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-1-11) # see https://ansible.readthedocs.io/projects/antsibull-nox/config-file/#basic-linting-sessions [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-1-12) [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-1-13) [sessions.docs_check] [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-1-14) # Add configuration settings here to adjust to your collection; [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-1-15) # see https://ansible.readthedocs.io/projects/antsibull-nox/config-file/#collection-documentation-check` Running all tests against your collection[¶](https://docs.ansible.com/projects/antsibull-nox/getting-started/#running-all-tests-against-your-collection "Permanent link") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- After you add the `noxfile.py` and `antsibull-nox.toml` files to your collection root, you can run the tests as follows: 1. Install `antsibull-nox`, which also installs `nox`. `[](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-2-1) pip install antsibull-nox` 2. Run `nox` in the collection root to run all tests. Alternatively, you do not have to install `antsibull-nox` and can run either of the following commands in the collection root: * `pipx run noxfile.py` * `uv run noxfile.py` Running specific tests against your collection[¶](https://docs.ansible.com/projects/antsibull-nox/getting-started/#running-specific-tests-against-your-collection "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ By default, nox runs all tests that you add to the `noxfile.py` file. However, the more sessions a `nox` test suite contains, the more useful it is to run only some of the test sessions. 1. Run `nox --list` to list all available test sessions. 2. Run `nox -e ` to run a specific test session: `[](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-3-1) # List all test sessions [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-3-2) nox --list [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-3-3) pipx run noxfile.py --list [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-3-4) uv run noxfile.py --list [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-3-5) [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-3-6) # Run only the 'lint' session [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-3-7) nox -e lint [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-3-8) pipx run noxfile.py -e lint [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-3-9) uv run noxfile.py -e lint` Reusing virtual environments[¶](https://docs.ansible.com/projects/antsibull-nox/getting-started/#reusing-virtual-environments "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------------ For each run, `nox` recreates the virtual environment for every session. You can re-use virtual environments in subsequent runs by passing the `-R` parameter. `[](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-4-1) # Reuse existing virtual environments [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-4-2) nox -R [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-4-3) pipx run noxfile.py -R [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-4-4) uv run noxfile.py -R` Alternatively, use a combination with the `-e` parameter: `[](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-5-1) # Run only 'lint' session and reuse existing virtual environments [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-5-2) nox -Re lint [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-5-3) pipx run noxfile.py -Re lint [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-5-4) uv run noxfile.py -Re lint` Formatting code before commits[¶](https://docs.ansible.com/projects/antsibull-nox/getting-started/#formatting-code-before-commits "Permanent link") ---------------------------------------------------------------------------------------------------------------------------------------------------- If present, the `formatters` session reformats Python code and should be run before a commit is made. This session is included with the `lint` session, which takes longer because it does additional linting. `[](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-6-1) # Reformat code [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-6-2) nox -Re formatters [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-6-3) pipx run noxfile.py -Re formatters [](https://docs.ansible.com/projects/antsibull-nox/getting-started/#__codelineno-6-4) uv run noxfile.py -Re formatters` Note Whether or not a collection has a `formatters` section depends on the parameters passed to `antsibull_nox.add_lint_sessions()` in the `noxfile.py` file. In the example in the previous section, `run_isort=False` and `run_black=False` disable both currently supported formatters. In this case, `antsibull-nox` does not add the `formatters` session because it would be empty. Dependent collections[¶](https://docs.ansible.com/projects/antsibull-nox/getting-started/#dependent-collections "Permanent link") ---------------------------------------------------------------------------------------------------------------------------------- By default, antsibull-nox will use `ansible-galaxy collection list` to find collections, will look in adjacent directories, and will download and install missing collections needed to run tests in the `.nox` cache directory. More precisely: 1. If the current checked out collection is part of a tree structure `ansible_collections///`, then antsibull-nox will inspect all collections that are part of that tree and use them. 2. If the current checked out collection is not part of such a tree structure, then antsibull-nox will look for adjacent directories of the form `.`. 3. If the environment variable `ANTSIBULL_NOX_IGNORE_INSTALLED_COLLECTIONS` is not set to `true`, antibull-nox will call `ansible-galaxy collection list` to find all installed collections. 4. If more collections are needed, and `ANTSIBULL_NOX_INSTALL_COLLECTIONS` is not set to `never`, antsibull-nox will download and install them into the `.nox` cache directory. In the included GitHub Action, `ANTSIBULL_NOX_IGNORE_INSTALLED_COLLECTIONS` is always set to `true`. This avoids using collections from the Ansible community package that is installed in GitHub's default images. --- # Contributing - Ansible Molecule [Skip to content](https://docs.ansible.com/projects/molecule/contributing/#contributing) [](https://github.com/ansible/molecule/blob/main/docs/contributing.md "Edit this page") [](https://github.com/ansible/molecule/raw/main/docs/contributing.md "View source of this page") Contributing[¶](https://docs.ansible.com/projects/molecule/contributing/#contributing "Permanent link") ======================================================================================================== Noticed a bug or have an idea to improve Ansible Molecule? Want to write some documentation or share your expertise on the forum? There are many ways to get involved and contribute, find out how. Guidelines[¶](https://docs.ansible.com/projects/molecule/contributing/#guidelines "Permanent link") ---------------------------------------------------------------------------------------------------- * We are interested in various different kinds of improvement for Molecule; please feel free to raise an [Issue](https://github.com/ansible-community/molecule/issues/new/choose) if you would like to work on something major to ensure efficient collaboration and avoid duplicate effort. * Create a topic branch from where you want to base your work. * Make sure you have added tests for your changes. * Although not required, it is good to sign off commits using `git commit --signoff`, and agree that usage of `--signoff` constitutes agreement with the terms of [DCO 1.1](https://github.com/ansible-community/molecule/blob/main/DCO_1_1.md) . * Run all the tests to ensure nothing else was accidentally broken. * Reformat the code by following the formatting section below. * Submit a pull request. Talk to us[¶](https://docs.ansible.com/projects/molecule/contributing/#talk-to-us "Permanent link") ---------------------------------------------------------------------------------------------------- Connect with the Ansible community! Join the Ansible forum to ask questions, get help, and interact with the community. * [Get Help](https://forum.ansible.com/c/help/6) : get help or help others. Please add appropriate tags if you start new discussions, for example use the `molecule`, `molecule6`, or `devtools` tags. * [Social Spaces](https://forum.ansible.com/c/chat/4) : meet and interact with fellow enthusiasts. * [News & Announcements](https://forum.ansible.com/c/news/5) : track project-wide announcements including social events. To get release announcements and important changes from the community, see the [Bullhorn newsletter](https://docs.ansible.com/projects/ansible/devel/community/communication.html#the-bullhorn) . You can find more information in the [Ansible communication guide](https://docs.ansible.com/projects/ansible/devel/community/communication.html) . Possible security bugs should be reported via email to [security@ansible.com](mailto:security@ansible.com) . Code Of Conduct[¶](https://docs.ansible.com/projects/molecule/contributing/#code-of-conduct "Permanent link") -------------------------------------------------------------------------------------------------------------- Please see our [Code of Conduct](https://github.com/ansible-community/molecule/blob/main/.github/CODE_OF_CONDUCT.md) document. Pull Request and Governance[¶](https://docs.ansible.com/projects/molecule/contributing/#pull-request-and-governance "Permanent link") -------------------------------------------------------------------------------------------------------------------------------------- * If your PRs get stuck [join us on IRC](https://github.com/ansible/community/wiki/Molecule#join-the-discussion) or add to the [working group agenda](https://github.com/ansible/community/wiki/Molecule#meetings) . * The code style is what is enforced by CI, everything else is off-topic. * All PRs must be reviewed by one other person. This is enforced by GitHub. Larger changes require +2. Testing[¶](https://docs.ansible.com/projects/molecule/contributing/#testing "Permanent link") ---------------------------------------------------------------------------------------------- Molecule has an extensive set of unit and functional tests. Molecule uses [Tox](https://tox.wiki/en/latest/) factors to generate a matrix of python x Ansible x unit/functional tests. Manual setup required as of this time. ### Dependencies[¶](https://docs.ansible.com/projects/molecule/contributing/#dependencies "Permanent link") Tests will be skipped when the driver's binary is not present. Install the test framework [Tox](https://tox.wiki/en/latest/) . `[](https://docs.ansible.com/projects/molecule/contributing/#__codelineno-0-1) python3 -m pip install tox` ### Running the test suite[¶](https://docs.ansible.com/projects/molecule/contributing/#running-the-test-suite "Permanent link") Run all tests, including linting and coverage reports. This should be run prior to merging or submitting a pull request. `[](https://docs.ansible.com/projects/molecule/contributing/#__codelineno-1-1) tox` ### List available scenarios[¶](https://docs.ansible.com/projects/molecule/contributing/#list-available-scenarios "Permanent link") List all available scenarios. This is useful to target specific Python and Ansible version for the functional and unit tests. `[](https://docs.ansible.com/projects/molecule/contributing/#__codelineno-2-1) tox -av` ### Unit[¶](https://docs.ansible.com/projects/molecule/contributing/#unit "Permanent link") Run all unit tests with coverage. `[](https://docs.ansible.com/projects/molecule/contributing/#__codelineno-3-1) tox -e py` Run all unit tests for a specific version of Python. `[](https://docs.ansible.com/projects/molecule/contributing/#__codelineno-4-1) tox -e py311` ### Linting[¶](https://docs.ansible.com/projects/molecule/contributing/#linting "Permanent link") Linting is performed by a combination of linters. Run all the linters (some perform changes to conform the code to the style rules). `[](https://docs.ansible.com/projects/molecule/contributing/#__codelineno-5-1) tox -e lint` ### Documentation[¶](https://docs.ansible.com/projects/molecule/contributing/#documentation "Permanent link") Generate the documentation, using [mkdocs](https://www.mkdocs.org/) . `[](https://docs.ansible.com/projects/molecule/contributing/#__codelineno-6-1) tox -e docs` ### Updating Dependencies[¶](https://docs.ansible.com/projects/molecule/contributing/#updating-dependencies "Permanent link") Dependencies need to be updated by hand in: * `.config/requirements.in` * `.pre-commit-config.yaml` (2 places) Credits[¶](https://docs.ansible.com/projects/molecule/contributing/#credits "Permanent link") ---------------------------------------------------------------------------------------------- Based on the good work of John Dewey ([@retr0h](https://github.com/retr0h) ) and other [contributors](https://github.com/ansible-community/molecule/graphs/contributors) . Active member list can be seen at [Molecule working group](https://github.com/ansible/community/wiki/Molecule) . Back to top --- # Installation and Usage - Ansible Creator Documentation [Skip to content](https://docs.ansible.com/projects/creator/installing/#installation-and-usage) [](https://github.com/ansible/ansible-creator/blob/main/docs/installing.md "Edit this page") [](https://github.com/ansible/ansible-creator/raw/main/docs/installing.md "View source of this page") Installation and Usage[¶](https://docs.ansible.com/projects/creator/installing/#installation-and-usage "Permanent link") ========================================================================================================================= ansible-creator provides two main functionalities: `init` and `add`. The `init` command allows you to initialize an Ansible project, while `add` command allows you to add resources to an existing ansible project. Installation[¶](https://docs.ansible.com/projects/creator/installing/#installation "Permanent link") ----------------------------------------------------------------------------------------------------- Recommendation The **recommended** approach to install `ansible-creator` is using the `ansible-dev-tools` package. [Ansible Development Tools](https://docs.ansible.com/projects/dev-tools/) aims to streamline the setup and usage of several tools needed in order to create [Ansible](https://www.ansible.com/) content. It combines critical Ansible development packages into a unified Python package. `[](https://docs.ansible.com/projects/creator/installing/#__codelineno-0-1) # This also installs ansible-core if it is not already installed [](https://docs.ansible.com/projects/creator/installing/#__codelineno-0-2) pip3 install ansible-dev-tools` To install ansible-creator, use the following pip command: `[](https://docs.ansible.com/projects/creator/installing/#__codelineno-1-1) pip install ansible-creator` CLI Usage[¶](https://docs.ansible.com/projects/creator/installing/#cli-usage "Permanent link") ----------------------------------------------------------------------------------------------- The Command-Line Interface (CLI) for ansible-creator provides a straightforward and efficient way to interact with the tool. Users can initiate actions, such as initializing Ansible Collections and other Ansible Projects, through concise commands. The CLI is designed for simplicity, allowing users to execute operations with ease and without the need for an extensive understanding of the tool's intricacies. It serves as a flexible and powerful option for users who prefer command-line workflows, enabling them to integrate ansible-creator seamlessly into their development processes. If command line is not your preferred method, you can also leverage the GUI interface within VS Code's Ansible extension that offers a more visually intuitive experience of ansible-creator. See [content creation](https://docs.ansible.com/projects/creator/content_creation/) . Command line completion[¶](https://docs.ansible.com/projects/creator/installing/#command-line-completion "Permanent link") --------------------------------------------------------------------------------------------------------------------------- `ansible-creator` has experimental command line completion for common shells. Please ensure you have the `argcomplete` package installed and configured. `[](https://docs.ansible.com/projects/creator/installing/#__codelineno-2-1) pip install argcomplete --user [](https://docs.ansible.com/projects/creator/installing/#__codelineno-2-2) activate-global-python-argcomplete --user` ### General Usage[¶](https://docs.ansible.com/projects/creator/installing/#general-usage "Permanent link") Get an overview of available commands and options by running: `[](https://docs.ansible.com/projects/creator/installing/#__codelineno-3-1) ansible-creator --help` Initialize projects[¶](https://docs.ansible.com/projects/creator/installing/#initialize-projects "Permanent link") ------------------------------------------------------------------------------------------------------------------- ### Initialize Ansible collection project[¶](https://docs.ansible.com/projects/creator/installing/#initialize-ansible-collection-project "Permanent link") The `init collection` command enables you to initialize an Ansible collection project. Use the following command template: `[](https://docs.ansible.com/projects/creator/installing/#__codelineno-4-1) ansible-creator init collection ` #### Positional Arguments[¶](https://docs.ansible.com/projects/creator/installing/#positional-arguments "Permanent link") | Parameter | Description | | --- | --- | | collection-name | The collection name in the format `.`. | | path | The destination directory for the collection project. | #### Optional Arguments[¶](https://docs.ansible.com/projects/creator/installing/#optional-arguments "Permanent link") | Short flag | Long flag | Flag argument | Description | | --- | --- | --- | --- | | \-f | \--force | | Force re-initialize the specified directory as an Ansible collection. This flag is deprecated and will be removed soon. (default: False) | | \-o | \--overwrite | | Overwrites existing files or directories. (default: False) | | \-no | \--no-overwrite | | Restricts the overwriting operation for files or directories. (default: False) | | | \--json | | Output messages as JSON (default: False) | | \--la | \--log-append | bool | Append to log file. (choices: true, false) (default: true) | | \--lf | \--log-file | file | Log file to write to. (default: ./ansible-creator.log) | | \--ll | \--log-level | level | Log level for file output. (choices: notset, debug, info, warning, error, critical) (default: notset) | | \--na | \--no-ansi | | Disable the use of ANSI codes for terminal color. (default: False) | | \-h | \--help | | Show this help message and exit | | \-v | \--verbosity | | Give more Cli output. Option is additive, and can be used up to 3 times. (default: 0) | #### Example[¶](https://docs.ansible.com/projects/creator/installing/#example "Permanent link") `[](https://docs.ansible.com/projects/creator/installing/#__codelineno-5-1) ansible-creator init collection testns.testname $HOME/collections/ansible_collections` This command will scaffold the collection `testns.testname` at `/home/ansible-dev/collections/ansible_collections/testns/testname` #### Generated Ansible Collection Structure[¶](https://docs.ansible.com/projects/creator/installing/#generated-ansible-collection-structure "Permanent link") Running the `init collection` command generates an Ansible collection project with a comprehensive directory structure. Explore it using: `[](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-1) $ tree -lla /home/ansible-dev/collections/ansible_collections/testns/testname [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-2) . [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-3) ├── CHANGELOG.rst [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-4) ├── changelogs [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-5) │ └── config.yaml [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-6) ├── CODE_OF_CONDUCT.md [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-7) ├── CONTRIBUTING [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-8) ├── .devcontainer [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-9) │   ├── devcontainer.json [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-10) │   ├── docker [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-11) │   │   └── devcontainer.json [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-12) │   └── podman [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-13) │   └── devcontainer.json [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-14) ├── devfile.yaml [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-15) ├── docs [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-16) │ ├── docsite [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-17) │ │ └── links.yml [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-18) │ └── .keep [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-19) ├── extensions [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-20) │ ├── eda [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-21) │ │ └── rulebooks [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-22) │ │ └── rulebook.yml [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-23) │ └── molecule [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-24) │ ├── integration_hello_world [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-25) │ │ └── molecule.yml [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-26) │ └── utils [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-27) │ ├── playbooks [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-28) │ │ ├── converge.yml [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-29) │ │ └── noop.yml [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-30) │ └── vars [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-31) │ └── vars.yml [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-32) ├── galaxy.yml [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-33) ├── .github [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-34) │ └── workflows [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-35) │ ├── release.yml [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-36) │ └── test.yml [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-37) ├── .isort.cfg [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-38) ├── LICENSE [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-39) ├── MAINTAINERS [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-40) ├── meta [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-41) │ └── runtime.yml [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-42) ├── plugins [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-43) │ ├── action [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-44) │ │ ├── sample_action.py [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-45) │ │ └── __init__.py [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-46) │ ├── cache [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-47) │ │ └── __init__.py [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-48) │ ├── lookup [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-49) │ │ ├── sample_lookup.py [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-50) │ │ └── __init__.py [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-51) │ ├── filter [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-52) │ │ ├── sample_filter.py [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-53) │ │ └── __init__.py [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-54) │ ├── inventory [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-55) │ │ └── __init__.py [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-56) │ ├── modules [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-57) │ │ ├── sample_module.py [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-58) │ │ ├── sample_action.py [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-59) │ │ └── __init__.py [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-60) │ ├── module_utils [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-61) │ │ └── __init__.py [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-62) │ ├── plugin_utils [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-63) │ │ └── __init__.py [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-64) │ ├── sub_plugins [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-65) │ │ └── __init__.py [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-66) │ ├── test [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-67) │ │ ├── sample_test.py [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-68) │ │ └── __init__.py [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-69) ├── .pre-commit-config.yaml [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-70) ├── .prettierignore [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-71) ├── pyproject.toml [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-72) ├── README.md [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-73) ├── roles [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-74) │ └── run [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-75) │ ├── defaults [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-76) │ │ └── main.yml [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-77) │ ├── files [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-78) │ │ └── .keep [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-79) │ ├── handlers [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-80) │ │ └── main.yaml [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-81) │ ├── meta [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-82) │ │ └── main.yml [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-83) │ ├── README.md [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-84) │ ├── tasks [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-85) │ │ └── main.yml [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-86) │ ├── templates [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-87) │ │ └── .keep [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-88) │ ├── tests [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-89) │ │ └── inventory [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-90) │ ├── vars [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-91) │ │ └── main.yml [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-92) ├── tests [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-93) │ ├── .gitignore [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-94) │ ├── integration [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-95) │ │ ├── __init__.py [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-96) │ │ ├── targets [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-97) │ │ │ └── hello_world [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-98) │ │ │ └── tasks [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-99) │ │ │ └── main.yml [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-100) │ │ └── test_integration.py [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-101) │ └── unit [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-102) │ └── .keep [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-103) └── .vscode [](https://docs.ansible.com/projects/creator/installing/#__codelineno-6-104) └── extensions.json` **Note:** The scaffolded collection includes a `sample_filter` filter plugin, along with a molecule scenario and an integration test target for it, that can be run using `pytest`. This serves as an example for you to refer when writing tests for your Ansible plugins and can be removed when it is no longer required. To run the `hello_world` integration test, follow these steps: * Git initialize the repository containing the scaffolded collection with `git init`. * `pip install ansible-dev-tools`. * Invoke `pytest` from collection root. ### Initialize Ansible playbook project[¶](https://docs.ansible.com/projects/creator/installing/#initialize-ansible-playbook-project "Permanent link") The `init playbook` command enables you to initialize an Ansible playbook project. Use the following command template: `[](https://docs.ansible.com/projects/creator/installing/#__codelineno-7-1) ansible-creator init playbook ` #### Collection Positional Arguments[¶](https://docs.ansible.com/projects/creator/installing/#collection-positional-arguments "Permanent link") | Parameter | Description | | --- | --- | | collection-name | The name for the playbook adjacent collection in the format `.`. | | path | The destination directory for the playbook project. | #### Collection Optional Arguments[¶](https://docs.ansible.com/projects/creator/installing/#collection-optional-arguments "Permanent link") | Short flag | Long flag | Flag argument | Description | | --- | --- | --- | --- | | \-f | \--force | | Force re-initialize the specified directory as an Ansible collection. This flag is deprecated and will be removed soon. (default: False) | | \-o | \--overwrite | | Overwrites existing files or directories. (default: False) | | \-no | \--no-overwrite | | Restricts the overwriting operation for files or directories. (default: False) | | | \--json | | Output messages as JSON (default: False) | | \--la | \--log-append | bool | Append to log file. (choices: true, false) (default: true) | | \--lf | \--log-file | file | Log file to write to. (default: ./ansible-creator.log) | | \--ll | \--log-level | level | Log level for file output. (choices: notset, debug, info, warning, error, critical) (default: notset) | | \--na | \--no-ansi | | Disable the use of ANSI codes for terminal color. (default: False) | | \-h | \--help | | Show this help message and exit | | \-v | \--verbosity | | Give more Cli output. Option is additive, and can be used up to 3 times. (default: 0) | Example: `[](https://docs.ansible.com/projects/creator/installing/#__codelineno-8-1) ansible-creator init playbook myorg.myproject $HOME/ansible-projects/playbook-project` This command will scaffold the new Ansible playbook project at `/home/user/ansible-projects/playbook-project`. #### Generated Ansible playbook project Structure[¶](https://docs.ansible.com/projects/creator/installing/#generated-ansible-playbook-project-structure "Permanent link") Running the `init playbook` command generates an Ansible playbook project with a comprehensive directory structure. Explore it using: `[](https://docs.ansible.com/projects/creator/installing/#__codelineno-9-1) $ tree -la /home/user/ansible-projects/playbook-project [](https://docs.ansible.com/projects/creator/installing/#__codelineno-9-2) . [](https://docs.ansible.com/projects/creator/installing/#__codelineno-9-3) ├── ansible.cfg [](https://docs.ansible.com/projects/creator/installing/#__codelineno-9-4) ├── ansible-navigator.yml [](https://docs.ansible.com/projects/creator/installing/#__codelineno-9-5) ├── collections [](https://docs.ansible.com/projects/creator/installing/#__codelineno-9-6) │   ├── ansible_collections [](https://docs.ansible.com/projects/creator/installing/#__codelineno-9-7) │   │   └── myorg [](https://docs.ansible.com/projects/creator/installing/#__codelineno-9-8) │   │   └── myproject [](https://docs.ansible.com/projects/creator/installing/#__codelineno-9-9) │   │   ├── README.md [](https://docs.ansible.com/projects/creator/installing/#__codelineno-9-10) │   │   └── roles [](https://docs.ansible.com/projects/creator/installing/#__codelineno-9-11) │   │   └── run [](https://docs.ansible.com/projects/creator/installing/#__codelineno-9-12) │   │   ├── README.md [](https://docs.ansible.com/projects/creator/installing/#__codelineno-9-13) │   │   └── tasks [](https://docs.ansible.com/projects/creator/installing/#__codelineno-9-14) │   │   └── main.yml [](https://docs.ansible.com/projects/creator/installing/#__codelineno-9-15) │   └── requirements.yml [](https://docs.ansible.com/projects/creator/installing/#__codelineno-9-16) ├── .devcontainer [](https://docs.ansible.com/projects/creator/installing/#__codelineno-9-17) │   ├── devcontainer.json [](https://docs.ansible.com/projects/creator/installing/#__codelineno-9-18) │   ├── docker [](https://docs.ansible.com/projects/creator/installing/#__codelineno-9-19) │   │   └── devcontainer.json [](https://docs.ansible.com/projects/creator/installing/#__codelineno-9-20) │   └── podman [](https://docs.ansible.com/projects/creator/installing/#__codelineno-9-21) │   └── devcontainer.json [](https://docs.ansible.com/projects/creator/installing/#__codelineno-9-22) ├── devfile.yaml [](https://docs.ansible.com/projects/creator/installing/#__codelineno-9-23) ├── .github [](https://docs.ansible.com/projects/creator/installing/#__codelineno-9-24) │   ├── ansible-code-bot.yml [](https://docs.ansible.com/projects/creator/installing/#__codelineno-9-25) │   └── workflows [](https://docs.ansible.com/projects/creator/installing/#__codelineno-9-26) │   └── tests.yml [](https://docs.ansible.com/projects/creator/installing/#__codelineno-9-27) ├── inventory [](https://docs.ansible.com/projects/creator/installing/#__codelineno-9-28) │   ├── group_vars [](https://docs.ansible.com/projects/creator/installing/#__codelineno-9-29) │   │   ├── all.yml [](https://docs.ansible.com/projects/creator/installing/#__codelineno-9-30) │   │   └── web_servers.yml [](https://docs.ansible.com/projects/creator/installing/#__codelineno-9-31) │   ├── hosts.yml [](https://docs.ansible.com/projects/creator/installing/#__codelineno-9-32) │   └── host_vars [](https://docs.ansible.com/projects/creator/installing/#__codelineno-9-33) │   ├── server1.yml [](https://docs.ansible.com/projects/creator/installing/#__codelineno-9-34) │   ├── server2.yml [](https://docs.ansible.com/projects/creator/installing/#__codelineno-9-35) │   ├── server3.yml [](https://docs.ansible.com/projects/creator/installing/#__codelineno-9-36) │   ├── switch1.yml [](https://docs.ansible.com/projects/creator/installing/#__codelineno-9-37) │   └── switch2.yml [](https://docs.ansible.com/projects/creator/installing/#__codelineno-9-38) ├── linux_playbook.yml [](https://docs.ansible.com/projects/creator/installing/#__codelineno-9-39) ├── network_playbook.yml [](https://docs.ansible.com/projects/creator/installing/#__codelineno-9-40) ├── README.md [](https://docs.ansible.com/projects/creator/installing/#__codelineno-9-41) ├── site.yml [](https://docs.ansible.com/projects/creator/installing/#__codelineno-9-42) └── .vscode [](https://docs.ansible.com/projects/creator/installing/#__codelineno-9-43) └── extensions.json` It also comes equipped with Github Action Workflows that use [ansible-content-actions](https://github.com/marketplace/actions/ansible-content-actions) for testing and publishing the collection. For details on how to use these, please refer to the following: * [Using the testing workflow](https://ansible.readthedocs.io/projects/dev-tools/user-guide/ci-setup/) * [Using the release workflow](https://ansible.readthedocs.io/projects/dev-tools/user-guide/content-release/) Please ensure that you review any potential `TO-DO` items in the scaffolded content and make the necessary modifications according to your requirements. ### Initialize execution environment project[¶](https://docs.ansible.com/projects/creator/installing/#initialize-execution-environment-project "Permanent link") The `init execution_env` command enables you to initialize an Ansible execution environment project. Use the following command template: `[](https://docs.ansible.com/projects/creator/installing/#__codelineno-10-1) ansible-creator init execution_env ` Example: `[](https://docs.ansible.com/projects/creator/installing/#__codelineno-11-1) ansible-creator init execution_env $HOME/ansible-projects/ee-project` This command will scaffold the new execution environment playbook project at `/home/user/ansible-projects/ee-project`. For a comprehensive guide covering all EE configuration options (Galaxy servers, collections, build steps, token security, and more), see the [EE Scaffolding Guide](https://docs.ansible.com/projects/creator/ee_scaffolding/) . #### Generated Ansible execution environment project Structure[¶](https://docs.ansible.com/projects/creator/installing/#generated-ansible-execution-environment-project-structure "Permanent link") Running the `init execution_env` command generates an Ansible execution environment project with a comprehensive directory structure. Explore it using: `[](https://docs.ansible.com/projects/creator/installing/#__codelineno-12-1) $ tree -la /home/user/ansible-projects/ee-project [](https://docs.ansible.com/projects/creator/installing/#__codelineno-12-2) . [](https://docs.ansible.com/projects/creator/installing/#__codelineno-12-3) ├── .github [](https://docs.ansible.com/projects/creator/installing/#__codelineno-12-4) │ └── workflows [](https://docs.ansible.com/projects/creator/installing/#__codelineno-12-5) │ └── ee-build.yml [](https://docs.ansible.com/projects/creator/installing/#__codelineno-12-6) ├── .gitignore [](https://docs.ansible.com/projects/creator/installing/#__codelineno-12-7) ├── README.md [](https://docs.ansible.com/projects/creator/installing/#__codelineno-12-8) └── execution-environment.yml` Add resources[¶](https://docs.ansible.com/projects/creator/installing/#add-resources "Permanent link") ------------------------------------------------------------------------------------------------------- The `add` subcommand allows users to scaffold content types like resources and plugins into an existing project. This feature is designed to streamline the development environment setup by automatically generating the necessary configuration files. ### Resources General Usage[¶](https://docs.ansible.com/projects/creator/installing/#resources-general-usage "Permanent link") Get an overview of available commands and options by running: `[](https://docs.ansible.com/projects/creator/installing/#__codelineno-13-1) ansible-creator add --help` #### Add Positional Arguments[¶](https://docs.ansible.com/projects/creator/installing/#add-positional-arguments "Permanent link") | Parameter | Description | | --- | --- | | resource | Add resources to an existing Ansible project. | | plugin | Add a plugin to an Ansible collection. | #### Resource Optional Arguments[¶](https://docs.ansible.com/projects/creator/installing/#resource-optional-arguments "Permanent link") | Short flag | Long flag | Flag argument | Description | | --- | --- | --- | --- | | \-h | \--help | | Show this help message and exit. | ### Add resource to an existing project[¶](https://docs.ansible.com/projects/creator/installing/#add-resource-to-an-existing-project "Permanent link") The `add resource` command enables you to add a resource to an already existing project. Use the following command template: `[](https://docs.ansible.com/projects/creator/installing/#__codelineno-14-1) ansible-creator add resource ` #### Resource Positional Arguments[¶](https://docs.ansible.com/projects/creator/installing/#resource-positional-arguments "Permanent link") | Parameter | Description | | --- | --- | | devcontainer | Add devcontainer files to an existing Ansible project. | | devfile | Add a devfile file to an existing Ansible project. | | execution-environment | Add a sample execution-environment.yml file to an existing path. | | play-argspec | Add playbook argspec examples file to an existing Ansible project. | | role | Add a role to an existing Ansible collection. | #### Example of adding a resource[¶](https://docs.ansible.com/projects/creator/installing/#example-of-adding-a-resource "Permanent link") `[](https://docs.ansible.com/projects/creator/installing/#__codelineno-15-1) ansible-creator add resource devcontainer /home/user/..path/to/your/existing_project` This command will scaffold the devcontainer directory at `/home/user/..path/to/your/existing_project` ### Add plugins to an existing ansible collection[¶](https://docs.ansible.com/projects/creator/installing/#add-plugins-to-an-existing-ansible-collection "Permanent link") The `add plugin` command enables you to add a plugin to an existing collection project. Use the following command template: `[](https://docs.ansible.com/projects/creator/installing/#__codelineno-16-1) ansible-creator add plugin ` #### Plugin Positional Arguments[¶](https://docs.ansible.com/projects/creator/installing/#plugin-positional-arguments "Permanent link") | Parameter | Description | | --- | --- | | action | Add an action plugin to an existing Ansible Collection. | | filter | Add a filter plugin to an existing Ansible Collection. | | lookup | Add a lookup plugin to an existing Ansible Collection. | | module | Add a generic module to an existing Ansible Collection. | | test | Add a test plugin to an existing Ansible Collection. | #### Example of adding a plugin[¶](https://docs.ansible.com/projects/creator/installing/#example-of-adding-a-plugin "Permanent link") `[](https://docs.ansible.com/projects/creator/installing/#__codelineno-17-1) ansible-creator add plugin action test_plugin /home/user/..path/to/your/existing_collection` This command will scaffold an action plugin at `/home/user/..path/to/your/existing_collection` Back to top --- # Installation - Ansible Molecule [Skip to content](https://docs.ansible.com/projects/molecule/installation/#installation) [](https://github.com/ansible/molecule/blob/main/docs/installation.md "Edit this page") [](https://github.com/ansible/molecule/raw/main/docs/installation.md "View source of this page") Installation[¶](https://docs.ansible.com/projects/molecule/installation/#installation "Permanent link") ======================================================================================================== This document assumes the developer has a basic understanding of Python packaging, and how to install and manage Python on the system executing Molecule. Requirements[¶](https://docs.ansible.com/projects/molecule/installation/#requirements "Permanent link") -------------------------------------------------------------------------------------------------------- A recent version of `ansible-core` that is still under support. Depending on the driver chosen, you may need to install additional OS packages. CentOSUbuntu `[](https://docs.ansible.com/projects/molecule/installation/#__codelineno-0-1) $ sudo dnf install -y gcc python3-pip python3-devel openssl-devel python3-libselinux` `[](https://docs.ansible.com/projects/molecule/installation/#__codelineno-1-1) $ sudo apt update [](https://docs.ansible.com/projects/molecule/installation/#__codelineno-1-2) $ sudo apt install -y python3-pip libssl-dev` Pip[¶](https://docs.ansible.com/projects/molecule/installation/#pip "Permanent link") -------------------------------------------------------------------------------------- [pip](https://pip.pypa.io/en/stable/installation/) is the only supported installation method. Recommendation The **recommended** approach to install `molecule` is using the `ansible-dev-tools` package. [Ansible Development Tools](https://docs.ansible.com/projects/dev-tools/) aims to streamline the setup and usage of several tools needed in order to create [Ansible](https://www.ansible.com/) content. It combines critical Ansible development packages into a unified Python package. `[](https://docs.ansible.com/projects/molecule/installation/#__codelineno-2-1) # This also installs ansible-core if it is not already installed [](https://docs.ansible.com/projects/molecule/installation/#__codelineno-2-2) pip3 install ansible-dev-tools` `[](https://docs.ansible.com/projects/molecule/installation/#__codelineno-3-1) python3 -m pip install molecule ansible-core` Keep in mind that on selinux supporting systems, if you install into a virtual environment, you may face [issue 34340](https://github.com/ansible/ansible/issues/34340) even if selinux is not enabled or is configured to be permissive. It is your responsibility to ensure that soft dependencies of Ansible are available on your controller or host machines. Warning It is highly recommended that you install molecule in a \[virtual environment\]. This will provide a modern copy of \[setuptools\] which is mandatory in order for molecule to be installed successfully and function correctly. If you cannot use a virtual environment then you can attempt a package upgrade with the following: `[](https://docs.ansible.com/projects/molecule/installation/#__codelineno-4-1) python3 -m pip install --upgrade --user setuptools` ### Requirements (pip)[¶](https://docs.ansible.com/projects/molecule/installation/#requirements-pip "Permanent link") Depending on the driver chosen, you may need to install additional Python packages. See the driver's documentation in that case. ### Install[¶](https://docs.ansible.com/projects/molecule/installation/#install "Permanent link") Install Molecule: `[](https://docs.ansible.com/projects/molecule/installation/#__codelineno-5-1) python3 -m pip install --user molecule` Molecule does not include ansible-lint (nor does the lint extra), but is easily installed separately: `[](https://docs.ansible.com/projects/molecule/installation/#__codelineno-6-1) python3 -m pip install --user molecule ansible-lint` Molecule uses the \\"delegated\\" driver by default. Other drivers can be installed separately from PyPI, most of them being included in [molecule-plugins](https://github.com/ansible-community/molecule-plugins) package. If you would like to use podman as the molecule driver, the installation command would look like this: `[](https://docs.ansible.com/projects/molecule/installation/#__codelineno-7-1) python3 -m pip install --user "molecule-plugins[podman]"` Warning If you upgrade molecule from previous versions, make sure to remove previously installed drivers like for instance `molecule-podman` or `molecule-vagrant` since those are now available in the `molecule-plugins` package. Installing molecule package also installed its main script `molecule`, usually in `PATH`. Users should know that molecule can also be called as a python module, using `python3 -m molecule ...`. This alternative method has some benefits: * allows to explicitly control which Python interpreter is used by molecule * allows molecule installation at the user level without even needing to have the script in `PATH`. Container[¶](https://docs.ansible.com/projects/molecule/installation/#container "Permanent link") -------------------------------------------------------------------------------------------------- `Molecule` is built into a [container image for Ansible Development Tools (ADT)](https://docs.ansible.com/projects/dev-tools/container/) Any questions or bugs related to the use of Molecule from within a container should be addressed by the ADT project. Source[¶](https://docs.ansible.com/projects/molecule/installation/#source "Permanent link") -------------------------------------------------------------------------------------------- Due to the rapid pace of development on this tool, you might want to install and update a bleeding-edge version of Molecule from Git. Follow the instructions below to do the initial install and subsequent updates. The package distribution that you'll get installed will be autogenerated and will contain commit hash information, making it easier to refer to. ### Source Requirements[¶](https://docs.ansible.com/projects/molecule/installation/#source-requirements "Permanent link") CentOSUbuntu `[](https://docs.ansible.com/projects/molecule/installation/#__codelineno-8-1) $ sudo dnf install -y libffi-devel git` `[](https://docs.ansible.com/projects/molecule/installation/#__codelineno-9-1) $ sudo apt install -y libffi-dev git` Install `[](https://docs.ansible.com/projects/molecule/installation/#__codelineno-10-1) python3 -m pip install -U git+https://github.com/ansible-community/molecule` Back to top --- # Contributor Guide - Ansible Development Tools Documentation [Skip to content](https://docs.ansible.com/projects/dev-tools/contributor-guide/#contributor-guide) [](https://github.com/ansible/ansible-dev-tools/blob/main/docs/contributor-guide.md "Edit this page") [](https://github.com/ansible/ansible-dev-tools/raw/main/docs/contributor-guide.md "View source of this page") Contributor Guide[¶](https://docs.ansible.com/projects/dev-tools/contributor-guide/#contributor-guide "Permanent link") ======================================================================================================================== To contribute to `ansible-dev-tools` python package or to the list of tools part of it, please use pull requests on a branch of your own fork. After [creating your fork on GitHub](https://docs.github.com/en/get-started/quickstart/contributing-to-projects) , you can do: `[](https://docs.ansible.com/projects/dev-tools/contributor-guide/#__codelineno-0-1) $ git clone --recursive git@github.com:your-name/developer-tool-name [](https://docs.ansible.com/projects/dev-tools/contributor-guide/#__codelineno-0-2) $ cd developer-tool-name [](https://docs.ansible.com/projects/dev-tools/contributor-guide/#__codelineno-0-3) $ git checkout -b your-branch-name [](https://docs.ansible.com/projects/dev-tools/contributor-guide/#__codelineno-0-4) # DO SOME CODING HERE [](https://docs.ansible.com/projects/dev-tools/contributor-guide/#__codelineno-0-5) $ git add your new files [](https://docs.ansible.com/projects/dev-tools/contributor-guide/#__codelineno-0-6) $ git commit -v [](https://docs.ansible.com/projects/dev-tools/contributor-guide/#__codelineno-0-7) $ git push origin your-branch-name` You will then be able to create a pull request from your commit. Prerequisites: 1. All fixes to core functionality (i.e. anything except docs or examples) should be accompanied by tests that fail prior to your change and succeed afterwards. 2. Before sending a PR, make sure that `tox -e lint` passes. Feel free to raise issues in the repo if you feel unable to contribute a code fix. Container testing[¶](https://docs.ansible.com/projects/dev-tools/contributor-guide/#container-testing "Permanent link") ------------------------------------------------------------------------------------------------------------------------ `pytest` has been extended to facilitate testing a container. `[](https://docs.ansible.com/projects/dev-tools/contributor-guide/#__codelineno-1-1) Custom options: [](https://docs.ansible.com/projects/dev-tools/contributor-guide/#__codelineno-1-2) --container-engine=CONTAINER_ENGINE [](https://docs.ansible.com/projects/dev-tools/contributor-guide/#__codelineno-1-3) Container engine to use. (default=ADT_CONTAINER_ENGINE, podman, docker, '') [](https://docs.ansible.com/projects/dev-tools/contributor-guide/#__codelineno-1-4) --container-name=CONTAINER_NAME [](https://docs.ansible.com/projects/dev-tools/contributor-guide/#__codelineno-1-5) Container name to use for the running container. (default=ADT_CONTAINER_NAME) [](https://docs.ansible.com/projects/dev-tools/contributor-guide/#__codelineno-1-6) --image-name=IMAGE_NAME [](https://docs.ansible.com/projects/dev-tools/contributor-guide/#__codelineno-1-7) Container name to use. (default=ADT_IMAGE_NAME) [](https://docs.ansible.com/projects/dev-tools/contributor-guide/#__codelineno-1-8) --only-container Only run container tests [](https://docs.ansible.com/projects/dev-tools/contributor-guide/#__codelineno-1-9) --include-container Include container tests` Container tests can be run with either of the following commands: `[](https://docs.ansible.com/projects/dev-tools/contributor-guide/#__codelineno-2-1) # Run the tests against the default container engine [](https://docs.ansible.com/projects/dev-tools/contributor-guide/#__codelineno-2-2) pytest --only-container [](https://docs.ansible.com/projects/dev-tools/contributor-guide/#__codelineno-2-3) pytest --only-container --container-engine= --image-name [](https://docs.ansible.com/projects/dev-tools/contributor-guide/#__codelineno-2-4) tox -e test-image [](https://docs.ansible.com/projects/dev-tools/contributor-guide/#__codelineno-2-5) tox -e test-image -- --container-engine= --image-name ` See the `tests/integration/test_container.py` for examples. ### Manual testing of devspaces container[¶](https://docs.ansible.com/projects/dev-tools/contributor-guide/#manual-testing-of-devspaces-container "Permanent link") At this moment the devspaces container is not tested by the CI, so it is important to test it manually before merging any changes. * Get the checksum of the temporary container made from your pull request, the containers are pushed to [https://github.com/ansible/ansible-dev-tools/pkgs/container/ansible-devspaces-tmp](https://github.com/ansible/ansible-dev-tools/pkgs/container/ansible-devspaces-tmp) * Open an already made * [https://console.redhat.com/openshift/sandbox](https://console.redhat.com/openshift/sandbox) Talk to us[¶](https://docs.ansible.com/projects/dev-tools/contributor-guide/#talk-to-us "Permanent link") ---------------------------------------------------------------------------------------------------------- * Join the Ansible forum: * [Get Help](https://forum.ansible.com/c/help/6) : get help or help others. Please add appropriate tags if you start new discussions, for example the `devtools` tag. * [Posts tagged with 'devtools'](https://forum.ansible.com/tag/devtools) : subscribe to participate in project-related conversations. * [Social Spaces](https://forum.ansible.com/c/chat/4) : gather and interact with fellow enthusiasts. * [News & Announcements](https://forum.ansible.com/c/news/5) : track project-wide announcements including social events. * [Bullhorn newsletter](https://docs.ansible.com/ansible/devel/community/communication.html#the-bullhorn) : used to announce releases and important changes. * We are also available on Matrix in the [#devtools:ansible.com](https://matrix.to/#/#devtools:ansible.com) room. Possible security bugs should be reported via email to [security@ansible.com](mailto:security@ansible.com) . For more information about communication, see the [Ansible communication guide](https://docs.ansible.com/ansible/devel/community/communication.html) . Code of Conduct[¶](https://docs.ansible.com/projects/dev-tools/contributor-guide/#code-of-conduct "Permanent link") -------------------------------------------------------------------------------------------------------------------- Please see the official [Ansible Community Code of Conduct](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html) . Back to top --- # Updating playbook output in RST files - antsibull-docs – Ansible Documentation Build Scripts [Skip to content](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#updating-ansible-playbook-output-in-rst-files) Updating ansible-playbook output in RST files[¶](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#updating-ansible-playbook-output-in-rst-files "Permanent link") ================================================================================================================================================================================== One common problem with Ansible playbook examples in documentation is that while it is helpful to include the playbook's output, it is somewhat tedious to update the playbook output, especially when changes occur to plugins or modules. Antsibull-docs provides a tool through the `antsibull-docs ansible-output` subcommand that lets you update the `ansible-playbook` output in code blocks within RST files. The `antsibull-docs ansible-output` subcommand also lets you check whether code blocks need to be updated, which can be a useful consistency check in CI pipelines. Metadata and code blocks[¶](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#metadata-and-code-blocks "Permanent link") ---------------------------------------------------------------------------------------------------------------------------------------- To know which code blocks to update and what playbook and environment variables to use, you need to provide a `ansible-output-data` directive before the actual code block: `[](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-0-1) .. ansible-output-data:: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-0-2) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-0-3) env: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-0-4) ANSIBLE_STDOUT_CALLBACK: community.general.tasks_only [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-0-5) ANSIBLE_COLLECTIONS_TASKS_ONLY_NUMBER_OF_COLUMNS: "90" [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-0-6) playbook: |- [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-0-7) - hosts: localhost [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-0-8) gather_facts: false [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-0-9) tasks: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-0-10) - name: Sort list by version number [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-0-11) debug: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-0-12) var: ansible_versions | community.general.version_sort [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-0-13) vars: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-0-14) ansible_versions: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-0-15) - '2.8.0' [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-0-16) - '2.11.0' [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-0-17) - '2.7.0' [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-0-18) - '2.10.0' [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-0-19) - '2.9.0' [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-0-20) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-0-21) .. code-block:: ansible-output [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-0-22) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-0-23) TASK [Sort list by version number] ******************************************************** [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-0-24) ok: [localhost] => { [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-0-25) "ansible_versions | community.general.version_sort": [ [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-0-26) "2.7.0", [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-0-27) "2.8.0", [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-0-28) "2.9.0", [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-0-29) "2.10.0", [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-0-30) "2.11.0" [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-0-31) ] [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-0-32) }` Antsibull-docs looks for the next code block with language `ansible-output`, and replaces its contents with the output of `ansible-playbook playbook.yml`, where `playbook.yml` is filled with the provided playbook. ### The `ansible-output-data` directive in detail[¶](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#the-ansible-output-data-directive-in-detail "Permanent link") The `ansible-output-data` directive does not generate any visible content in rendered documentation when the `sphinx_antsibull_ext` Sphinx extension is used. The directive contains YAML configuration data that is meant for `antsibull-docs` and not for readers. In the YAML configuration you can use the following top-level keys. Also take a look at the example further below which demonstrates all of them. * The playbook is provided as a multi-line YAML string `playbook`. Note that you can use Jinja expressions; to avoid clashes with Ansible's use of Jinja, you need to prepend and append `@` to template expressions, statements, and comments: * Expressions are of the form `@{{ expression }}@`; * Statements are of the form `@{% statement %}@`; * Comments are of the form `@{# Comment #}@`. * The `variables` directionary allows you to define variables that can be used for templating the playbook. The key in the dictionary is the variable's name, and the value is a dictionary with exactly one of the following keys: * `value`: provide a string that defines the value of the variable. * `previous_code_block`: the content of the last code block before the `ansible-output-data` directive of this language will be used as the value. The additional key `previous_code_block_index` (integer, default `-1`) determines which of the previous code blocks of the given language is picked. An index of `0` uses the first one in the file; `1` the second; `-1` the last one; and `-2` the second to last before the `ansible-output-data` directive. * The `env` dictionary allows you to set environment variables that are set when calling `ansible-playbook`. In the example further below, we set an explicit callback stdout plugin (using `ANSIBLE_STDOUT_CALLBACK`) and provide configuration for that plugin (`ANSIBLE_COLLECTIONS_TASKS_ONLY_NUMBER_OF_COLUMNS`). * The `language` key allows to override the language for the code block that will be replaced. By default `antsibull-docs ansible-output` looks for code blocks of language `ansible-output`. * The `skip_first_lines` key allows to remove a fixed number of lines from the beginning of the `ansible-playbook` output. * The `skip_last_lines` key allows to remove a fixed number of lines from the end of the `ansible-playbook` output. * The `prepend_lines` key allows to prepend a multi-line YAML string to the `ansible-playbook` output. * The `postprocessors` key allows to define a list of post-processors. This is explained in more detail in the [Post-processing ansible-playbook output section](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#post-processing-ansible-playbook-output) . * The `inventory` key allows to define a YAML inventory. See the [Ansible documentation on inventories](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html) for the format of a YAML inventory. An example looks like this. The `console` code block contains the generated result: `[](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-1) This is an Ansible task we're going to reference in the playbook: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-2) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-3) .. code-block:: yaml+jinja [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-4) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-5) - name: Sort list by version number [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-6) debug: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-7) var: ansible_versions | community.general.version_sort [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-8) vars: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-9) ansible_versions: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-10) - '2.8.0' [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-11) - '2.11.0' [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-12) - '2.7.0' [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-13) - '2.10.0' [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-14) - '2.9.0' [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-15) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-16) .. ansible-output-data:: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-17) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-18) --- [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-19) # Note that the content of the 'ansible-output-data' directive [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-20) # is hidden from the user [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-21) # (assuming you are using the sphinx_antsibull_ext Sphinx extension) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-22) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-23) # Use the community.general.tasks_only callback plugin [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-24) # and configure it to use 90 columns by setting appropriate [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-25) # environment variables: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-26) env: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-27) ANSIBLE_STDOUT_CALLBACK: community.general.tasks_only [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-28) ANSIBLE_COLLECTIONS_TASKS_ONLY_NUMBER_OF_COLUMNS: "90" [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-29) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-30) # Look for the next code-block with language 'console': [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-31) language: console [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-32) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-33) # Prepend the following lines to the output of 'ansible-playbook'. [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-34) # In this case, we add a fake console prompt that seems to run the [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-35) # playbook: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-36) prepend_lines: | [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-37) $ ansible-playbook playbook.yml [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-38) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-39) # Remove the first three lines at the beginning of the playbook. [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-40) # This is the output for the 'ansible.builtin.set_fact' task: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-41) skip_first_lines: 3 [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-42) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-43) # Do not remove lines at the end of the playbook [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-44) skip_last_lines: 0 [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-45) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-46) # Define variables for templating the playbook [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-47) variables: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-48) hosts: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-49) value: localhost [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-50) tasks: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-51) previous_code_block: yaml+jinja [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-52) previous_code_block_index: -1 [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-53) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-54) # No post-processors [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-55) postprocessors: [] [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-56) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-57) # Basic inventory with localhost [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-58) inventory: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-59) ungrouped: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-60) localhost: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-61) ansible_connection: local [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-62) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-63) # The actual playbook to run: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-64) playbook: |- [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-65) @{# Use the 'hosts' variable defined above #}@ [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-66) - hosts: @{{ hosts }}@ [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-67) gather_facts: false [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-68) tasks: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-69) - name: Set some value. [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-70) ansible.builtin.set_fact: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-71) some_variable: some_value [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-72) @{# Insert tasks from the previous code block #}@ [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-73) @{# (We need to indent all other lines by 4 spaces) #}@ [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-74) @{{ tasks | indent(4) }}@ [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-75) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-76) The task produces the following output: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-77) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-78) .. code-block:: console [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-79) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-80) $ ansible-playbook playbook.yml [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-81) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-82) TASK [Sort list by version number] ******************************************************** [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-83) ok: [localhost] => { [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-84) "ansible_versions | community.general.version_sort": [ [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-85) "2.7.0", [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-86) "2.8.0", [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-87) "2.9.0", [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-88) "2.10.0", [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-89) "2.11.0" [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-90) ] [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-1-91) }` Controlling code block contexts[¶](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#controlling-code-block-contexts "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------------------ Next to the `ansible-output-data` RST directive, antsibull-docs also provides a `ansible-output-meta` RST directive. This meta directive allows to apply actions to the context for the next `ansible-output-data` directives. ### Reset previous code blocks[¶](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#reset-previous-code-blocks "Permanent link") The `reset-previous-blocks` action resets the list of previous code blocks. It can be used as follows: `[](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-2-1) .. ansible-output-meta:: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-2-2) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-2-3) actions: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-2-4) - name: reset-previous-blocks` This is relevant when using `previous_code_block` variables where you specify `previous_code_block_index`. If you want several consecutive `ansible-output-data` directives to reference the same code block, you can reset the previous blocks directly before that code block, and then reference that code block as the one with index `0`: `[](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-3-1) (more text with other code blocks) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-3-2) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-3-3) .. ansible-output-meta:: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-3-4) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-3-5) actions: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-3-6) - name: reset-previous-blocks [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-3-7) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-3-8) .. code-block:: yaml [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-3-9) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-3-10) # This code block now has index 0, no matter how many other code blocks [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-3-11) # came before the above action. [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-3-12) foo: bar [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-3-13) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-3-14) Now you can have multiple ansible-output-data directives referencing the [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-3-15) above ``yaml`` block as the ``yaml`` block with index 0: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-3-16) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-3-17) .. ansible-output-data:: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-3-18) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-3-19) variables: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-3-20) content: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-3-21) previous_code_block: yaml [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-3-22) previous_code_block_index: 0 [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-3-23) playbook: |- [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-3-24) - hosts: localhost [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-3-25) tasks: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-3-26) - ansible.builtin.debug: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-3-27) msg: "{{ data }}" [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-3-28) vars: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-3-29) data: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-3-30) @{{ content | indent(10) }}@ [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-3-31) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-3-32) .. code-block:: ansible-output [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-3-33) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-3-34) ...` ### Define template for `ansible-output-data`[¶](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#define-template-for-ansible-output-data "Permanent link") The `set-template` action defines a template for all following `ansible-output-data` directives. You can use all fields that you can also use for `ansible-output-data` in the template: `[](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-1) .. ansible-output-meta:: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-2) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-3) actions: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-4) - name: set-template [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-5) template: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-6) # The environment variables will be merged. If a variable is provided here, [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-7) # you do not have to provide it again in the directive - only if you want to [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-8) # override its value. [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-9) env: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-10) ANSIBLE_STDOUT_CALLBACK: community.general.tasks_only [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-11) ANSIBLE_COLLECTIONS_TASKS_ONLY_NUMBER_OF_COLUMNS: "90" [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-12) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-13) # Will use this value if not specified in the directive. [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-14) # If no language is provided in both the template and the directive, [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-15) # 'ansible-output' will be used. [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-16) language: console [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-17) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-18) # Will use this value if not specified in the directive. [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-19) prepend_lines: | [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-20) $ ansible-playbook playbook.yml [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-21) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-22) # Will use this value if not specified in the directive. [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-23) skip_first_lines: 3 [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-24) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-25) # Will use this value if not specified in the directive. [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-26) skip_last_lines: 0 [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-27) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-28) # The variables will be merged. If a varibale is provided here, [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-29) # you can override it in the directive by specifying a variable [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-30) # of the same name. [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-31) variables: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-32) hosts: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-33) value: localhost [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-34) tasks: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-35) previous_code_block: yaml+jinja [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-36) previous_code_block_index: -1 [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-37) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-38) # Will use this value if not specified in the directive. [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-39) postprocessors: [] [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-40) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-41) # Will use this value if not specified in the directive. [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-42) inventory: {} [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-43) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-44) # Will use this value if explicitly set to null/~ in the directive. [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-45) playbook: |- [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-4-46) (some Ansible playbook)` This can be useful to avoid repeating some definitions for multiple code blocks. If another `ansible-output-meta` action sets a new template, the previous templates will be thrown away. Post-processing ansible-playbook output[¶](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#post-processing-ansible-playbook-output "Permanent link") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- Out of the box, you can post-process the `ansible-playbook` output in some ways: * Skip a fixed number of lines at the top (`skip_first_lines`) or bottom (`skip_last_lines`). * Prepend lines to the output (`prepend_lines`). This, together with chosing an appropriate callback plugin (like [community.general.tasks\_only](https://docs.ansible.com/projects/ansible/devel/collections/community/general/tasks_only_callback.html) ) gives you a lot of freedom to get the output you want. In some cases, it is not sufficient though. For example, if you want to extract YAML output, and present it in a way that [matches your yamllint configuration](https://docs.ansible.com/projects/antsibull-nox/config-file/#yamllint-part-of-the-yamllint-session) . The default callback's YAML output suffers from [PyYAML's list indentation issue](https://github.com/yaml/pyyaml/issues/234) , which causes problems with many yamllint configurations. Also, the [ansible.builtin.default callback's YAML output](https://docs.ansible.com/projects/ansible/devel/collections/ansible/builtin/default_callback.html#parameter-result_format) is indented by 4 spaces, while most YAML is expected to be indented by 2 spaces. If you use the above settings (`skip_first_lines` / `skip_last_lines`) to extract only the YAML content of one task of the playbook's output, you can for example use [Pretty YAML (pyaml)](https://pypi.org/project/pyaml/) to reformat it. For that, you can use the `postprocessors` list to specify a post-processor command: `[](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-5-1) postprocessors: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-5-2) - command: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-5-3) - python [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-5-4) - "-m" [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-5-5) - pyaml` This tells `antsibull-docs ansible-output` to feed the extracted output (with `skip_first_lines`, `skip_last_lines`, and `prepend_lines` already processed) through standard input into the `python -m pyaml` process, and use its output instead. A full example looks like this: `[](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-1) .. code-block:: yaml+jinja [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-2) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-3) input: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-4) - k0_x0: A0 [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-5) k1_x1: B0 [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-6) k2_x2: [C0] [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-7) k3_x3: foo [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-8) - k0_x0: A1 [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-9) k1_x1: B1 [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-10) k2_x2: [C1] [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-11) k3_x3: bar [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-12) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-13) target: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-14) - {after: a0, before: k0_x0} [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-15) - {after: a1, before: k1_x1} [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-16) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-17) result: "{{ input | community.general.replace_keys(target=target) }}" [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-18) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-19) .. ansible-output-data:: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-20) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-21) env: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-22) ANSIBLE_CALLBACK_RESULT_FORMAT: yaml [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-23) variables: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-24) data: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-25) previous_code_block: yaml+jinja [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-26) postprocessors: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-27) - command: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-28) - python [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-29) - "-m" [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-30) - pyaml [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-31) language: yaml [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-32) skip_first_lines: 4 [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-33) skip_last_lines: 3 [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-34) playbook: |- [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-35) - hosts: localhost [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-36) gather_facts: false [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-37) tasks: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-38) - vars: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-39) @{{ data | indent(8) }}@ [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-40) ansible.builtin.debug: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-41) var: result [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-42) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-43) This results in: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-44) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-45) .. code-block:: yaml [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-46) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-47) result: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-48) - a0: A0 [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-49) a1: B0 [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-50) k2_x2: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-51) - C0 [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-52) k3_x3: foo [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-53) - a0: A1 [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-54) a1: B1 [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-55) k2_x2: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-56) - C1 [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-6-57) k3_x3: bar` Right now there are two kind of post-processor entries in `postprocessors`: 1. Command-based post-processors: You can provide a list `command`. This command is executed, the input fed in through standard input, and its standard output is taken as the output. Example: `[](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-7-1) postprocessors: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-7-2) - command: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-7-3) - python [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-7-4) - "-m" [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-7-5) - pyaml` 2. Name-reference post-processors: You can use `name` to reference a named globally defined post-processor. This is right now only possible in collections, since you need to define these in the collection's config file (`docs/docsite/config.yml` - see the [Collection usage section](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#collection-usage) ). Example: `[](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-8-1) postprocessors: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-8-2) - name: reformat-yaml` Standalone usage[¶](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#standalone-usage "Permanent link") ------------------------------------------------------------------------------------------------------------------------ If you want to update a RST file, or all RST files in a directory, you can run antsibull-docs as follows: `[](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-9-1) $ antsibull-docs ansible-output /path/to/rst-file.rst [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-9-2) $ antsibull-docs ansible-output /path/to/directory-with-rst-files` If the provided path is a directory, it will recursively look for `.rst` files in it. You can pass a path to a config file with `--config /path/to/config.yaml`. You can use the keys that are described as part of `ansible_output` in [the following section](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#collection-usage) . This can look as follows: `[](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-10-1) --- [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-10-2) # Configuration for 'antsibull-docs ansible-output' [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-10-3) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-10-4) # Insert definitions into 'env' for every ansible-output-data directive [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-10-5) global_env: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-10-6) ANSIBLE_STDOUT_CALLBACK: community.general.tasks_only [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-10-7) ANSIBLE_COLLECTIONS_TASKS_ONLY_NUMBER_OF_COLUMNS: 80 [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-10-8) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-10-9) # Global post-processors for Ansible output [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-10-10) global_postprocessors: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-10-11) # Keys are the names that can be referenced in ansible-output-data directives [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-10-12) reformat-yaml: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-10-13) # For CLI tools, you can specify a command that accepts input on stdin [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-10-14) # and outputs the result on stdout: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-10-15) command: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-10-16) - python [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-10-17) - "-m" [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-10-18) - pyaml` Collection usage[¶](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#collection-usage "Permanent link") ------------------------------------------------------------------------------------------------------------------------ If you run `antsibull-docs ansible-output` without a path, it assumes that you are in a collection's root directory. (This is the directory that contains `galaxy.yml` or `MANIFEST.json`.) It will check all `.rst` files in `docs/docsite/rst/`, if that directory exists, and load configuration from `docs/docsite/config.yml`. (See [more information on that configuration file](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#configuring-the-docsite) .) The configuration allows you to specify entries for `env` for all code blocks, and you can define global post-processors that can be referenced in `postprocessors`: `[](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-11-1) --- [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-11-2) # Configuration for 'antsibull-docs ansible-output' [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-11-3) ansible_output: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-11-4) # Insert definitions into 'env' for every ansible-output-data directive [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-11-5) global_env: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-11-6) ANSIBLE_STDOUT_CALLBACK: community.general.tasks_only [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-11-7) ANSIBLE_COLLECTIONS_TASKS_ONLY_NUMBER_OF_COLUMNS: 80 [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-11-8) [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-11-9) # Global post-processors for Ansible output [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-11-10) global_postprocessors: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-11-11) # Keys are the names that can be referenced in ansible-output-data directives [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-11-12) reformat-yaml: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-11-13) # For CLI tools, you can specify a command that accepts input on stdin [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-11-14) # and outputs the result on stdout: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-11-15) command: [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-11-16) - python [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-11-17) - "-m" [](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#__codelineno-11-18) - pyaml` This is useful to standardize the callback and its settings for most code blocks in a collection's extra docs, and set up a pre-defined set of post-processors that can be used everywhere. Usage in CI[¶](https://docs.ansible.com/projects/antsibull-docs/ansible-output/#usage-in-ci "Permanent link") -------------------------------------------------------------------------------------------------------------- If you want to run `antsibull-docs ansible-output` in CI, you might find the `--check` parameter useful. If that parameter is specified, antsibull-docs will not update files, but instead fail if a file would be modified. A diff of the changes that would be applied will be printed to standard output. Warning Please note that you have to make sure that `antsibull-docs ansible-output` runs in CI with the minimum set of privileges, since it can run **arbitrary code**! Someone can add a playbook to documentation that recursively deletes all files you have access to. If you run `antsibull-docs ansible-output` (with or without `--check`) on such a RST file without sufficient isolation, all your files will be deleted. If you run `antsibull-docs ansible-output` in CI in a context where the code run has access to credentials, a playbook could send these credentials to an arbitrary location on the internet. --- # Using Runner as a Python Module Interface to Ansible — Ansible Runner Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/runner/en/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Runner Documentation](https://docs.ansible.com/projects/runner/en/stable/) * [](https://docs.ansible.com/projects/runner/en/latest/) * Using Runner as a Python Module Interface to Ansible * [View page source](https://docs.ansible.com/projects/runner/en/latest/_sources/python_interface.rst.txt) * * * Using Runner as a Python Module Interface to Ansible[](https://docs.ansible.com/projects/runner/en/latest/python_interface/#using-runner-as-a-python-module-interface-to-ansible "Link to this heading") ========================================================================================================================================================================================================== **Ansible Runner** is intended to provide a directly importable and usable API for interfacing with **Ansible** itself and exposes a few helper interfaces. The modules center around the [`Runner`](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/#ansible_runner.runner.Runner "ansible_runner.runner.Runner") object. The helper methods will either return an instance of this object which provides an interface to the results of executing the **Ansible** command or a tuple the actual output and error response based on the interface. **Ansible Runner** itself is a wrapper around **Ansible** execution and so adds plugins and interfaces to the system in order to gather extra information and process/store it for use later. Helper Interfaces[](https://docs.ansible.com/projects/runner/en/latest/python_interface/#helper-interfaces "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------ The helper [`interfaces`](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/#module-ansible_runner.interface "ansible_runner.interface") provides a quick way of supplying the recommended inputs in order to launch a **Runner** process. These interfaces also allow overriding and providing inputs beyond the scope of what the standalone or container interfaces support. You can see a full list of the inputs in the linked module documentation. `run()` helper function[](https://docs.ansible.com/projects/runner/en/latest/python_interface/#run-helper-function "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------- [`ansible_runner.interface.run()`](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/#ansible_runner.interface.run "ansible_runner.interface.run") When called, this function will take the inputs (either provided as direct inputs to the function or from the [Runner Input Directory Hierarchy](https://docs.ansible.com/projects/runner/en/latest/intro/#inputdir) ), and execute **Ansible**. It will run in the foreground and return the [`Runner`](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/#ansible_runner.runner.Runner "ansible_runner.runner.Runner") object when finished. `run_async()` helper function[](https://docs.ansible.com/projects/runner/en/latest/python_interface/#run-async-helper-function "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------- [`ansible_runner.interface.run_async()`](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/#ansible_runner.interface.run_async "ansible_runner.interface.run_async") Takes the same arguments as [`ansible_runner.interface.run()`](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/#ansible_runner.interface.run "ansible_runner.interface.run") but will launch **Ansible** asynchronously and return a tuple containing the `thread` object and a [`Runner`](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/#ansible_runner.runner.Runner "ansible_runner.runner.Runner") object. The **Runner** object can be inspected during execution. `run_command()` helper function[](https://docs.ansible.com/projects/runner/en/latest/python_interface/#run-command-helper-function "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------ [`ansible_runner.interface.run_command()`](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/#ansible_runner.interface.run_command "ansible_runner.interface.run_command") When called, this function will take the inputs (either provided as direct inputs to the function or from the [Runner Input Directory Hierarchy](https://docs.ansible.com/projects/runner/en/latest/intro/#inputdir) ), and execute the command passed either locally or within an container based on the parameters passed. It will run in the foreground and return a tuple of output and error response when finished. While running the within container image command the current local working directory will be volume mounted within the container, in addition to this for any of ansible command line utilities the inventory, vault-password-file, private-key file path will be volume mounted if provided in the `cmdline_args` parameters. `run_command_async()` helper function[](https://docs.ansible.com/projects/runner/en/latest/python_interface/#run-command-async-helper-function "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ [`ansible_runner.interface.run_command_async()`](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/#ansible_runner.interface.run_command_async "ansible_runner.interface.run_command_async") Takes the same arguments as [`ansible_runner.interface.run_command()`](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/#ansible_runner.interface.run_command "ansible_runner.interface.run_command") but will launch asynchronously and return a tuple containing the `thread` object and a [`Runner`](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/#ansible_runner.runner.Runner "ansible_runner.runner.Runner") object. The **Runner** object can be inspected during execution. `get_plugin_docs()` helper function[](https://docs.ansible.com/projects/runner/en/latest/python_interface/#get-plugin-docs-helper-function "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------- [`ansible_runner.interface.get_plugin_docs()`](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/#ansible_runner.interface.get_plugin_docs "ansible_runner.interface.get_plugin_docs") When called, this function will take the inputs, and execute the ansible-doc command to return the either the plugin-docs or playbook snippet for the passed list of plugin names. The plugin docs can be fetched either from locally installed plugins or from within an container image based on the parameters passed. It will run in the foreground and return a tuple of output and error response when finished. While running the command within the container the current local working directory will be volume mounted within the container. `get_plugin_docs_async()` helper function[](https://docs.ansible.com/projects/runner/en/latest/python_interface/#get-plugin-docs-async-helper-function "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- [`ansible_runner.interface.get_plugin_docs_async()`](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/#ansible_runner.interface.get_plugin_docs_async "ansible_runner.interface.get_plugin_docs_async") Takes the same arguments as [`ansible_runner.interface.get_plugin_docs_async()`](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/#ansible_runner.interface.get_plugin_docs_async "ansible_runner.interface.get_plugin_docs_async") but will launch asynchronously and return a tuple containing the `thread` object and a [`Runner`](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/#ansible_runner.runner.Runner "ansible_runner.runner.Runner") object. The **Runner** object can be inspected during execution. `get_plugin_list()` helper function[](https://docs.ansible.com/projects/runner/en/latest/python_interface/#get-plugin-list-helper-function "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------- [`ansible_runner.interface.get_plugin_list()`](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/#ansible_runner.interface.get_plugin_list "ansible_runner.interface.get_plugin_list") When called, this function will take the inputs, and execute the ansible-doc command to return the list of installed plugins. The installed plugin can be fetched either from local environment or from within an container image based on the parameters passed. It will run in the foreground and return a tuple of output and error response when finished. While running the command within the container the current local working directory will be volume mounted within the container. `get_inventory()` helper function[](https://docs.ansible.com/projects/runner/en/latest/python_interface/#get-inventory-helper-function "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------- [`ansible_runner.interface.get_inventory()`](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/#ansible_runner.interface.get_inventory "ansible_runner.interface.get_inventory") When called, this function will take the inputs, and execute the ansible-inventory command to return the inventory related information based on the action. If `action` is `list` it will return all the applicable configuration options for ansible, for `host` action it will return information of a single host and for `graph` action it will return the inventory. The execution will be in the foreground and return a tuple of output and error response when finished. While running the command within the container the current local working directory will be volume mounted within the container. `get_ansible_config()` helper function[](https://docs.ansible.com/projects/runner/en/latest/python_interface/#get-ansible-config-helper-function "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- [`ansible_runner.interface.get_ansible_config()`](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/#ansible_runner.interface.get_ansible_config "ansible_runner.interface.get_ansible_config") When called, this function will take the inputs, and execute the ansible-config command to return the Ansible configuration related information based on the action. If `action` is `list` it will return all the hosts related information including the host and group variables, for `dump` action it will return the entire active configuration and it can be customized to return only the changed configuration value by setting the `only_changed` boolean parameter to `True`. For `view` action it will return the view of the active configuration file. The execution will be in the foreground and return a tuple of output and error response when finished. While running the command within the container the current local working directory will be volume mounted within the container. `get_role_list()` helper function[](https://docs.ansible.com/projects/runner/en/latest/python_interface/#get-role-list-helper-function "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------- [`ansible_runner.interface.get_role_list()`](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/#ansible_runner.interface.get_role_list "ansible_runner.interface.get_role_list") _Version added: 2.2_ This function will execute the `ansible-doc` command to return the list of installed roles that have an argument specification defined. This data can be fetched from either the local environment or from within a container image based on the parameters passed. It will run in the foreground and return a tuple of output and error response when finished. Successful output will be in JSON format as returned from `ansible-doc`. `get_role_argspec()` helper function[](https://docs.ansible.com/projects/runner/en/latest/python_interface/#get-role-argspec-helper-function "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- [`ansible_runner.interface.get_role_argspec()`](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/#ansible_runner.interface.get_role_argspec "ansible_runner.interface.get_role_argspec") _Version added: 2.2_ This function will execute the `ansible-doc` command to return a role argument specification. This data can be fetched from either the local environment or from within a container image based on the parameters passed. It will run in the foreground and return a tuple of output and error response when finished. Successful output will be in JSON format as returned from `ansible-doc`. The `Runner` object[](https://docs.ansible.com/projects/runner/en/latest/python_interface/#the-runner-object "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------- The [`Runner`](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/#ansible_runner.runner.Runner "ansible_runner.runner.Runner") object is returned as part of the execution of **Ansible** itself. Since it wraps both execution and output it has some helper methods for inspecting the results. Other than the methods and indirect properties, the instance of the object itself contains two direct properties: * `rc` will represent the actual return code of the **Ansible** process * `status` will represent the state and can be one of: * `unstarted`: This is a very brief state where the Runner task has been created but hasn’t actually started yet. * `successful`: The `ansible` process finished successfully. * `failed`: The `ansible` process failed. `Runner.stdout`[](https://docs.ansible.com/projects/runner/en/latest/python_interface/#runner-stdout "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------ The [`Runner`](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/#ansible_runner.runner.Runner "ansible_runner.runner.Runner") object contains a property [`ansible_runner.runner.Runner.stdout`](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/#ansible_runner.runner.Runner.stdout "ansible_runner.runner.Runner.stdout") which will return an open file handle containing the [`stdout`](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/#ansible_runner.runner.Runner.stdout "ansible_runner.runner.Runner.stdout") of the **Ansible** process. `Runner.stderr`[](https://docs.ansible.com/projects/runner/en/latest/python_interface/#runner-stderr "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------ When the `runner_mode` is set to `subprocess` the [`Runner`](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/#ansible_runner.runner.Runner "ansible_runner.runner.Runner") object uses a property [`ansible_runner.runner.Runner.stderr`](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/#ansible_runner.runner.Runner.stderr "ansible_runner.runner.Runner.stderr") which will return an open file handle containing the `stderr` of the **Ansible** process. `Runner.events`[](https://docs.ansible.com/projects/runner/en/latest/python_interface/#runner-events "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------ [`ansible_runner.runner.Runner.events`](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/#ansible_runner.runner.Runner.events "ansible_runner.runner.Runner.events") is a `generator` that will return the [Playbook and Host Events](https://docs.ansible.com/projects/runner/en/latest/intro/#artifactevents) as Python `dict` objects. `Runner.stats`[](https://docs.ansible.com/projects/runner/en/latest/python_interface/#runner-stats "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------- [`ansible_runner.runner.Runner.stats`](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/#ansible_runner.runner.Runner.stats "ansible_runner.runner.Runner.stats") is a property that will return the final `playbook stats` event from **Ansible** in the form of a Python `dict` `Runner.host_events`[](https://docs.ansible.com/projects/runner/en/latest/python_interface/#runner-host-events "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------- [`ansible_runner.runner.Runner.host_events()`](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/#ansible_runner.runner.Runner.host_events "ansible_runner.runner.Runner.host_events") is a method that, given a hostname, will return a list of only **Ansible** event data executed on that Host. `Runner.get_fact_cache`[](https://docs.ansible.com/projects/runner/en/latest/python_interface/#runner-get-fact-cache "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------- [`ansible_runner.runner.Runner.get_fact_cache()`](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/#ansible_runner.runner.Runner.get_fact_cache "ansible_runner.runner.Runner.get_fact_cache") is a method that, given a hostname, will return a dictionary containing the [Facts](https://docs.ansible.com/projects/ansible/latest/user_guide/playbooks_variables.html#variables-discovered-from-systems-facts) stored for that host during execution. `Runner.event_handler`[](https://docs.ansible.com/projects/runner/en/latest/python_interface/#runner-event-handler "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------- A function passed to `__init__` of :class:`Runner `, this is invoked every time an Ansible event is received. You can use this to inspect/process/handle events as they come out of Ansible. This function should return `True` to keep the event, otherwise it will be discarded. `Runner.cancel_callback`[](https://docs.ansible.com/projects/runner/en/latest/python_interface/#runner-cancel-callback "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------ A function passed to `__init__` of [`Runner`](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/#ansible_runner.runner.Runner "ansible_runner.runner.Runner") , and to the [`ansible_runner.interface.run()`](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/#ansible_runner.interface.run "ansible_runner.interface.run") interface functions. This function will be called for every iteration of the [`ansible_runner.interface.run()`](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/#ansible_runner.interface.run "ansible_runner.interface.run") event loop and should return [`True`](https://docs.python.org/3/library/constants.html#True "(in Python v3.14)") to inform **Runner** cancel and shutdown the **Ansible** process or [`False`](https://docs.python.org/3/library/constants.html#False "(in Python v3.14)") to allow it to continue. `Runner.finished_callback`[](https://docs.ansible.com/projects/runner/en/latest/python_interface/#runner-finished-callback "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------- A function passed to `__init__` of [`Runner`](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/#ansible_runner.runner.Runner "ansible_runner.runner.Runner") , and to the [`ansible_runner.interface.run()`](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/#ansible_runner.interface.run "ansible_runner.interface.run") interface functions. This function will be called immediately before the **Runner** event loop finishes once **Ansible** has been shut down. `Runner.status_handler`[](https://docs.ansible.com/projects/runner/en/latest/python_interface/#runner-status-handler "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------- A function passed to `__init__` of [`Runner`](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/#ansible_runner.runner.Runner "ansible_runner.runner.Runner") and to the [`ansible_runner.interface.run()`](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/#ansible_runner.interface.run "ansible_runner.interface.run") interface functions. This function will be called any time the `status` changes, expected values are: * `starting`: Preparing to start but hasn’t started running yet * `running`: The **Ansible** task is running * `canceled`: The task was manually canceled either via callback or the cli * `timeout`: The timeout configured in Runner Settings was reached (see [env/settings - Settings for Runner itself](https://docs.ansible.com/projects/runner/en/latest/intro/#runnersettings) ) * `failed`: The **Ansible** process failed * `successful`: The **Ansible** process succeeded Usage examples[](https://docs.ansible.com/projects/runner/en/latest/python_interface/#usage-examples "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------ import ansible\_runner r \= ansible\_runner.run(private\_data\_dir\='/tmp/demo', playbook\='test.yml') print("{}: {}".format(r.status, r.rc)) \# successful: 0 for each\_host\_event in r.events: print(each\_host\_event\['event'\]) print("Final status:") print(r.stats) import ansible\_runner def my\_artifacts\_handler(artifacts\_dir): \# Do something here print(artifacts\_dir) \# Do something with artifact directory after the run is complete r \= ansible\_runner.run(private\_data\_dir\='/tmp/demo', playbook\='test.yml', artifacts\_handler\=my\_artifacts\_handler) import ansible\_runner def my\_status\_handler(data, runner\_config): \# Do something here print(data) r \= ansible\_runner.run(private\_data\_dir\='/tmp/demo', playbook\='test.yml', status\_handler\=my\_status\_handler) import ansible\_runner def my\_event\_handler(data): \# Do something here print(data) r \= ansible\_runner.run(private\_data\_dir\='/tmp/demo', playbook\='test.yml', event\_handler\=my\_event\_handler) import ansible\_runner r \= ansible\_runner.run(private\_data\_dir\='/tmp/demo', host\_pattern\='localhost', module\='shell', module\_args\='whoami') print("{}: {}".format(r.status, r.rc)) \# successful: 0 for each\_host\_event in r.events: print(each\_host\_event\['event'\]) print("Final status:") print(r.stats) from ansible\_runner import Runner, RunnerConfig \# Using tag using RunnerConfig rc \= RunnerConfig( private\_data\_dir\="project", playbook\="main.yml", tags\='my\_tag', ) rc.prepare() r \= Runner(config\=rc) r.run() \# run the role named 'myrole' contained in the '/project/roles' directory r \= ansible\_runner.run(private\_data\_dir\='/tmp/demo', role\='myrole') print("{}: {}".format(r.status, r.rc)) print(r.stats) \# run ansible/generic commands in interactive mode within container out, err, rc \= ansible\_runner.run\_command( executable\_cmd\='ansible-playbook', cmdline\_args\=\['gather.yaml', '-i', 'inventory', '-vvvv', '-k'\], input\_fd\=sys.stdin, output\_fd\=sys.stdout, error\_fd\=sys.stderr, host\_cwd\='/home/demo', process\_isolation\=True, container\_image\='network-ee' ) print("rc: {}".format(rc)) print("out: {}".format(out)) print("err: {}".format(err)) \# run ansible/generic commands in interactive mode locally out, err, rc \= ansible\_runner.run\_command( executable\_cmd\='ansible-playbook', cmdline\_args\=\['gather.yaml', '-i', 'inventory', '-vvvv', '-k'\], input\_fd\=sys.stdin, output\_fd\=sys.stdout, error\_fd\=sys.stderr, ) print("rc: {}".format(rc)) print("out: {}".format(out)) print("err: {}".format(err)) \# get plugin docs from within container out, err \= ansible\_runner.get\_plugin\_docs( plugin\_names\=\['vyos.vyos.vyos\_command'\], plugin\_type\='module', response\_format\='json', process\_isolation\=True, container\_image\='network-ee' ) print("out: {}".format(out)) print("err: {}".format(err)) \# get plugin docs from within container in async mode thread\_obj, runner\_obj \= ansible\_runner.get\_plugin\_docs\_async( plugin\_names\=\['ansible.netcommon.cli\_config', 'ansible.netcommon.cli\_command'\], plugin\_type\='module', response\_format\='json', process\_isolation\=True, container\_image\='network-ee' ) while runner\_obj.status not in \['canceled', 'successful', 'timeout', 'failed'\]: time.sleep(0.01) continue print("out: {}".format(runner\_obj.stdout.read())) print("err: {}".format(runner\_obj.stderr.read())) \# get plugin list installed on local system out, err \= ansible\_runner.get\_plugin\_list() print("out: {}".format(out)) print("err: {}".format(err)) \# get plugins with file list from within container out, err \= ansible\_runner.get\_plugin\_list(list\_files\=True, process\_isolation\=True, container\_image\='network-ee') print("out: {}".format(out)) print("err: {}".format(err)) \# get list of changed ansible configuration values out, err \= ansible\_runner.get\_ansible\_config(action\='dump', config\_file\='/home/demo/ansible.cfg', only\_changed\=True) print("out: {}".format(out)) print("err: {}".format(err)) \# get ansible inventory information out, err \= ansible\_runner.get\_inventory( action\='list', inventories\=\['/home/demo/inventory1', '/home/demo/inventory2'\], response\_format\='json', process\_isolation\=True, container\_image\='network-ee' ) print("out: {}".format(out)) print("err: {}".format(err)) \# get all roles with an arg spec installed locally out, err \= ansible\_runner.get\_role\_list() print("out: {}".format(out)) print("err: {}".format(err)) \# get roles with an arg spec from the \`foo.bar\` collection in a container out, err \= ansible\_runner.get\_role\_list(collection\='foo.bar', process\_isolation\=True, container\_image\='network-ee') print("out: {}".format(out)) print("err: {}".format(err)) \# get the arg spec for role \`baz\` from the locally installed \`foo.bar\` collection out, err \= ansible\_runner.get\_role\_argspec('baz', collection\='foo.bar') print("out: {}".format(out)) print("err: {}".format(err)) \# get the arg spec for role \`baz\` from the \`foo.bar\` collection installed in a container out, err \= ansible\_runner.get\_role\_argspec('baz', collection\='foo.bar', process\_isolation\=True, container\_image\='network-ee') print("out: {}".format(out)) print("err: {}".format(err)) Providing custom behavior and inputs[](https://docs.ansible.com/projects/runner/en/latest/python_interface/#providing-custom-behavior-and-inputs "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- **TODO** The helper methods are just one possible entrypoint, extending the classes used by these helper methods can allow a lot more custom behavior and functionality. Show: * How [`Runner Config`](https://docs.ansible.com/projects/runner/en/latest/ansible_runner.config/#ansible_runner.config.runner.RunnerConfig "ansible_runner.config.runner.RunnerConfig") is used and how overriding the methods and behavior can work * Show how custom cancel and status callbacks can be supplied. --- # Molecule Collection - Ansible Molecule [Skip to content](https://docs.ansible.com/projects/molecule/collection/#molecule-collection) [](https://github.com/ansible/molecule/blob/main/docs/collection.md "Edit this page") [](https://github.com/ansible/molecule/raw/main/docs/collection.md "View source of this page") Molecule Collection[¶](https://docs.ansible.com/projects/molecule/collection/#molecule-collection "Permanent link") ==================================================================================================================== [![CI](https://github.com/ansible/molecule/actions/workflows/tox.yml/badge.svg?event=push)](https://github.com/ansible/molecule/actions/workflows/tox.yml) [![Codecov](https://img.shields.io/codecov/c/github/ansible/molecule)](https://codecov.io/gh/ansible/molecule) `community.molecule` collection aims to help molecule users to write and maintain their molecule tests. This collection contains: * filters that can be used inside molecule testing playbooks * examples on how to use molecule for testing content with different type of infrastructure. External requirements[¶](https://docs.ansible.com/projects/molecule/collection/#external-requirements "Permanent link") ------------------------------------------------------------------------------------------------------------------------ Filters and modules provided do require molecule python package to be installed and they are not supposed to be used outside molecule testing playbooks. Release notes[¶](https://docs.ansible.com/projects/molecule/collection/#release-notes "Permanent link") -------------------------------------------------------------------------------------------------------- See the [changelog](https://github.com/ansible/molecule/tree/main/community.molecule/CHANGELOG.rst) . More information[¶](https://docs.ansible.com/projects/molecule/collection/#more-information "Permanent link") -------------------------------------------------------------------------------------------------------------- * [Ansible Developers](https://docs.ansible.com/developers.html) * [Ansible User guide](https://docs.ansible.com/users.html) * [Ansible Developer guide](https://docs.ansible.com/projects/ansible/latest/dev_guide/index.html) * [Ansible Collections Checklist](https://docs.ansible.com/projects/ansible/devel/community/collection_contributors/collection_requirements.html) * [Ansible Community code of conduct](https://docs.ansible.com/projects/ansible/latest/community/code_of_conduct.html) * [The Bullhorn (the Ansible Contributor newsletter)](https://forum.ansible.com/c/news/bullhorn/17) Licensing[¶](https://docs.ansible.com/projects/molecule/collection/#licensing "Permanent link") ------------------------------------------------------------------------------------------------ [MIT](https://github.com/ansible-collections/community.molecule/blob/main/LICENSE) Back to top --- # Creating a collection docsite - antsibull-docs – Ansible Documentation Build Scripts [Skip to content](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#creating-a-collection-docsite) Creating a collection docsite[¶](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#creating-a-collection-docsite "Permanent link") =================================================================================================================================================== antsibull-docs can be used to create a docsite for an individual collection. For example, take a look at [the community.crypto docsite built from the latest commit to the community.crypto repository](https://ansible-collections.github.io/community.crypto/branch/main/) . This document explains how you can build such a docsite with antsibull-docs, how you can lint collection documentation, and how you can use GitHub Actions to automate docsite building. Setting up development for a collection[¶](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#setting-up-development-for-a-collection "Permanent link") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- While antsibull-docs can download a collection it should generate documentation for, the main mode of operation is to use collections that are made available to ansible-core. If you just want to create documentation, you have to install ansible-core, antsibull-docs, and the collections you want to generate documentation for, or validate documentation of. To install ansible-core and antsibull-docs, you can use a [Python venv](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment) . In short, this looks like: `[](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-0-1) $ python -m venv ~/antsibull-demo-venv [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-0-2) $ . ~/antsibull-demo-venv/bin/activate [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-0-3) $ python -m pip install ansible-core antsibull-docs` To install collections, you can either use [`ansible-galaxy collection install`](https://docs.ansible.com/projects/ansible/latest/collections_guide/collections_installing.html) , or you can provide the collection repositories in a path structure that allows ansible-core to access them. If you work on collections, the second approach is usually preferred. One way of doing this is create a directory structure `ansible_collections//` for a collection `.` and point Ansible's [`ANSIBLE_COLLECTIONS_PATH`](https://docs.ansible.com/projects/ansible/latest/reference_appendices/config.html#collections-paths) to the directory containing `ansible_collections`. Then you can directly use the collection in Ansible. For example, if you want to store the collection tree in `~/collections/`, and you want to work on say `community.crypto`, which is stored in the [ansible-collections/community.crypto GitHub repository](https://github.com/ansible-collections/community.crypto/) , you can clone it as follows: `[](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-1-1) $ mkdir -p ~/collections/ansible_collections/community [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-1-2) $ export ANSIBLE_COLLECTIONS_PATH=~/collections [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-1-3) $ git clone git@github.com:ansible-collections/community.crypto.git ~/collections/ansible_collections/community/crypto` With `ANSIBLE_COLLECTIONS_PATH` set up you can use modules and plugins from the collection directly: `[](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-2-1) $ ansible localhost -m community.crypto.crypto_info [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-2-2) [WARNING]: No inventory was parsed, only implicit localhost is available [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-2-3) localhost | SUCCESS => { [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-2-4) "changed": false, [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-2-5) ... [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-2-6) }` In many cases you want to clone your fork instead of the collection's main repository itself, and only add the main repository as another remote. Please refer to your favorite Source Control Management tool/workflow on how to set up the environment. The important part is to check out the collection into the right path structure. Using that path structure, you can also run other tools like `ansible-test`: `[](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-3-1) $ cd ~/collections/ansible_collections/community/crypto [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-3-2) $ ansible-test sanity --docker -v` Finally, you can use `ansible-doc` to directly look at plugin, module, and role documentation using the command line: `[](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-4-1) # List modules and filter plugins: [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-4-2) $ ansible-doc --type module --list community.crypto [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-4-3) $ ansible-doc --type filter --list community.crypto [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-4-4) [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-4-5) # Show documentation of modules and filters: [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-4-6) $ ansible-doc --type module community.crypto.crypto_info [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-4-7) $ ansible-doc --type filter community.crypto.gpg_fingerprint` antsibull-docs internally uses `ansible-doc` and its JSON output to extract collection documentation. Linting collection docs[¶](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#linting-collection-docs "Permanent link") --------------------------------------------------------------------------------------------------------------------------------------- While the [`validate-modules` sanity test](https://docs.ansible.com/projects/ansible/latest/dev_guide/testing/sanity/validate-modules.html) provided by `ansible-test` already does some validation of module and plugin documentation, it does not check filter and test plugins, for example, and does not check cross-references to other plugins, modules, and roles. antsibull-docs provides the `lint-collection-docs` subcommand that allows you to extensively validate collection documentation, including extra documentation and collection-level links (see the corresponding sections below). The basic usage is as follows: `[](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-5-1) $ cd ~/collections/ansible_collections/community/crypto [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-5-2) $ antsibull-docs lint-collection-docs --plugin-docs .` This subcommand has multiple options which allow to control validation. The most important options are: * `--plugin-docs`: whether to validate schemas and markup of modules, plugins, and roles included in the collection. By default, this is not run (for backwards compatibility). We recommend to always specify this. * `--check-extra-docs-refs`: whether references in `:anscollection:`, `:ansplugin`, `:ansopt:`, `:ansoptref:`, `:ansretval:`, `:ansretvalref:` roles used in extra documentation should be checked. * `--validate-collection-refs {self,dependent,all}`: Specify how to validate inter-plugin/module/role and inter-collection references in plugin/module/role documentation (if `--plugin-docs` is specified) and extra docs (if `--check-extra-docs-refs` is specified`). This covers Ansible markup, like`M(foo.bar.baz)`or`O(foo.bar.baz#module:parameter=value)`, and other links such as`seealso`sections. If set to`self`, only references to the same collection are validated. If set to`dependent`, only references to the collection itself and collections it (transitively) depends on are validated, including references to ansible-core (as`ansible.builtin`). If set to`all\`, all references to other collections are validated. If collections are referenced that are not installed and that are in scope, references to them will not be reported. Reporting these can be enabled by specifying `--disallow-unknown-collection-refs`. * `--skip-rstcheck`: by default, when specifying `--plugin-docs`, antsibull-docs generates RST documentation for module/plugin/role docs and runs [`rstcheck`](https://rstcheck.readthedocs.io/) on these. This step is usually not necessary, since it will mostly point out errors in antsibull-docs' RST generation code, and will slow down linting especially for large collections. * `--disallow-semantic-markup`: If you want to avoid semantic markup in Ansible markup, for example for collections whose documentation must render OK with older versions of ansible-doc or Automation Hub, you can use this parameter to make antsibull-docs report all markup that is not supported. Semantic markup is supported by ansible-doc since ansible-core 2.15.0. Note In antsibull-docs 3.0.0, the defaults for some of the above options will change: * `--plugin-docs` will become the default; you need to specify `--no-plugin-docs` to not check plugin docs. * `--check-extra-docs-refs` will become the default; you need to specify `--no-check-extra-docs-refs` to not check extra docs references. * `--skip-rstcheck` will become the default; you need to speicyf `--no-skip-rstcheck` to check the generated plugin documentation RST files. We suggest that you already explicitly provide the `--no-XXX` variants now for features you do not want to use, respectively to enable plugin RST checking (for `--no-skip-rstcheck`). Then the scope of the linting command will not change once antsibull-docs 3.0.0 is released. Note The most extensive validation is achieved by running the following command: `[](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-6-1) $ antsibull-docs lint-collection-docs --plugin-docs --skip-rstcheck \ [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-6-2) --validate-collection-refs=all \ [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-6-3) --disallow-unknown-collection-refs \ [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-6-4) --check-extra-docs-refs \ [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-6-5) .` When successfully validating, the exit code will be `0`, otherwise it will be non-zero. In case it is non-zero, validation errors are shown in the format `:::` as follows: `[](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-7-1) plugins/modules/crypto_info.py:0:0: DOCUMENTATION -> description[2]: M(foo.bar.baz): a reference to the collection foo.bar is not allowed` This tells you that in file `plugins/modules/crypto_info.py`'s `DOCUMENTATION`, you have a broken reference `M(foo.bar.baz)` in the second paragraph of the top-level `description` key. The same output format is also used by ansible-test. Building a docsite[¶](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#building-a-docsite "Permanent link") ----------------------------------------------------------------------------------------------------------------------------- The simplest way to set up a Sphinx docsite is to use antsibull-docs' `sphinx-init` subcommand: `[](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-8-1) # Create a subdirectory which should contain the docsite: [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-8-2) $ mkdir built-docs [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-8-3) [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-8-4) # Create a Sphinx project for the collection community.crypto in there: [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-8-5) $ antsibull-docs sphinx-init --use-current --squash-hierarchy community.crypto --dest-dir built-docs [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-8-6) [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-8-7) # Install requirements for the docsite build [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-8-8) # (if you don't have an active venv, create one!) [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-8-9) $ cd built-docs [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-8-10) $ python -m pip install -r requirements.txt [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-8-11) [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-8-12) # Build the docsite by: [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-8-13) # 1. running antsibull-docs to create the RST files for the collection, [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-8-14) # 2. running Sphinx to compile everything to HTML [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-8-15) $ ./build.sh [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-8-16) [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-8-17) # Open the built HTML docsite in a browser like Firefox: [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-8-18) $ firefox build/html/index.html` The `sphinx-init` subcommand has quite a few configuration options: * If you built a docsite for a single collection, it's a good idea to specify `--squash-hierarchy` as in the above example. This avoids the unnecessary tree structure. * `--use-current` controls whether the collection should be assumed to be installed (if `--use-current` is specified), or whether antsibull-docs should install it itself temporarily (if `--use-current` is not specified). We recommend to install collections yourself and always specify `--use-current`. * You can use `--lenient` (configure Sphinx to not be too strict) and `--fail-on-error` (if any parsing or schema valiation errors happen, fail instead of creating error pages) to control building. For use in CI, use `--fail-on-error` to make sure that all errors are raised early. When trying to successfully build the docsite, `--lenient` is helpful to avoid Sphinx being too strict on errors. * `--index-rst-source` can be used to copy a provided file to `rst/index.rst` instead of generating a default `rst/index.rst` file. * `--sphinx-theme` can be used to select a different Sphinx theme. The default is the [`sphinx-ansible-theme`](https://pypi.org/project/sphinx-ansible-theme/) . * `--intersphinx` can be used to add intersphinx config entries to allow to use RST references to more external documentation. Refer to the [intersphinx documentation](https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html) for more information. * `--project`, `--copyright`, `--title`, `--html-short-title`, `--extra-conf`, `--extra-html-context`, and `--extra-html-theme-options` can be used to add specific configuration entries to the Sphinx configuration `conf.py`. Configuring the docsite[¶](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#configuring-the-docsite "Permanent link") --------------------------------------------------------------------------------------------------------------------------------------- Generally, configuration is done with a `docs/docsite/config.yml` YAML file. The format and options are as follows: ``[](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-9-1) --- [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-9-2) # Whether the collection uses flatmapping to flatten subdirectories in [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-9-3) # `plugins/*/`. [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-9-4) flatmap: false [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-9-5) [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-9-6) # List of environment variables that are defined by `.. envvar::` directives [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-9-7) # in the extra docsite RST files. [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-9-8) envvar_directives: [] [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-9-9) [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-9-10) # Changelog configuration (added in antsibull-docs 2.10.0) [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-9-11) changelog: [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-9-12) # Whether to write the changelog (taken from changelogs/changelog.yaml, see the [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-9-13) # antsibull-changelog documentation for more information) and link to it from the [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-9-14) # collection's index page. [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-9-15) write_changelog: false [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-9-16) [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-9-17) # Configuration for 'antsibull-docs ansible-output' [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-9-18) # (See documentation for ansible-output for more information.) [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-9-19) ansible_output: [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-9-20) # Insert definitions into 'env' for every ansible-output-data directive [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-9-21) global_env: [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-9-22) ANSIBLE_STDOUT_CALLBACK: community.general.tasks_only [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-9-23) ANSIBLE_COLLECTIONS_TASKS_ONLY_NUMBER_OF_COLUMNS: 80`` Most collections should use `envvar_directives`, `changelog`, and `ansible_output` only. The `flatmap` option applies to older versions of community.general and community.network and should be used for legacy collections only, not for new ones. Adding extra documentation[¶](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#adding-extra-documentation "Permanent link") --------------------------------------------------------------------------------------------------------------------------------------------- It is possible to add extra documentation in RST format to the docsite. This can for example be used to provide scenario guides. On the [community.crypto docsite](https://ansible-collections.github.io/community.crypto/branch/main/) , there are for example some how-tos in the "Scenario Guides" section. You need to provide the RST files in `docs/docsite/rst/`, and configure them in a YAML file `docs/docsite/extra-docs.yml`. See for example the [`extra-docs.yml` from community.crypto](https://github.com/ansible-collections/community.crypto/blob/main/docs/docsite/extra-docs.yml) for how this works: `[](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-10-1) --- [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-10-2) sections: [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-10-3) # We have one section labelled "Scenario Guides" [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-10-4) - title: Scenario Guides [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-10-5) toctree: [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-10-6) # List the filenames in docs/docsite/rst without [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-10-7) # the .rst extension here in the order you want [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-10-8) # them to appear: [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-10-9) - guide_selfsigned [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-10-10) - guide_ownca` Note In the RST files, you cannot chose labels freely, but have to prefix every label with `ansible_collections...docsite.`. This ensures that you cannot accidentally re-use labels that are used by other parts of the Ansible docsite. This can look as follows for community.crypto: ```[](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-11-1) .. _ansible_collections.community.crypto.docsite.guide_ownca: [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-11-2) [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-11-3) How to create a small CA [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-11-4) ======================== [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-11-5) [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-11-6) The :anscollection:`community.crypto collection ` [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-11-7) offers multiple modules that create private keys, certificate signing [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-11-8) requests, and certificates. This guide shows how to create your own [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-11-9) small CA and how to use it to sign certificates. [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-11-10) [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-11-11) In all examples, we assume that the CA's private key is password [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-11-12) protected, where the password is provided in the [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-11-13) ``secret_ca_passphrase`` variable. [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-11-14) [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-11-15) Set up the CA [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-11-16) ------------- [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-11-17) [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-11-18) Any certificate can be used as a CA certificate. You can create a [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-11-19) self-signed certificate (see [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-11-20) :ref:`ansible_collections.community.crypto.docsite.guide_selfsigned`), [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-11-21) use another CA certificate to sign a new certificate (using the [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-11-22) instructions below for signing a certificate), ask (and pay) a [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-11-23) commercial CA to sign your CA certificate, etc. [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-11-24) [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-11-25) ...``` If you want to reference modules, plugins, roles, their options and return values, see [the Ansible documentation's style guide](http://docs.testing.ansible.com/ansible/devel/dev_guide/style_guide/#adding-links-to-modules-and-plugins) . ### Special RST roles for extra documentation[¶](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#special-rst-roles-for-extra-documentation "Permanent link") Antsibull-docs provides several roles to reference Ansible content without having to manually compose the right RST labels for references. * `:ansval:`: format values. The syntax is as follows: `` [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-12-1) :ansval:`some value` `` * `:ansopt:`: format option names; reference options of a module, plugin, or role. The syntax is as follows: `` [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-13-1) An option with an optional value, without reference: [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-13-2) :ansopt:`option_name` [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-13-3) :ansopt:`option_name=value` [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-13-4) [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-13-5) An option with an option value, referencing an option of a plugin [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-13-6) (specified by its FQCN) and plugin type (module, lookup, filter, ...): [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-13-7) :ansopt:`namespace.name.plugin_name#plugin_type:option_name` [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-13-8) :ansopt:`namespace.name.plugin_name#plugin_type:option_name=value` [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-13-9) [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-13-10) For roles (plugin type "role"), you also have to specify the entrypoint [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-13-11) (usually "main"): [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-13-12) :ansopt:`namespace.name.role_name#role:entrypoint:option_name` [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-13-13) :ansopt:`namespace.name.role_name#role:entrypoint:option_name=value` [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-13-14) [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-13-15) Suboptions must be referenced by separating the different levels by dot: [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-13-16) :ansopt:`namespace.name.plugin#type:option.suboption.subsuboption=foo` [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-13-17) [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-13-18) You can use "[]" (with possible content) to indicate lists: [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-13-19) :ansopt:`namespace.name.plugin#type:option[].suboption[n-1].subsuboption["key"]=foo` `` * `:ansretval:`: format return values; reference return values of a module or plugin. Basically the syntax is identical to the one of `:ansopt:`, except that this references return values instead of options. * `:ansoptref:`: reference options of a module, plugin, or role. The syntax is as follows: `` [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-14-1) An option with an option value, referencing an option of a plugin [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-14-2) (specified by its FQCN) and plugin type (module, lookup, filter, ...): [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-14-3) :ansoptref:`Title ` [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-14-4) [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-14-5) For roles (plugin type "role"), you also have to specify the entrypoint [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-14-6) (usually "main"): [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-14-7) :ansoptref:`Title ` [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-14-8) [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-14-9) Suboptions must be referenced by separating the different levels by dot: [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-14-10) :ansoptref:`Title ` [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-14-11) [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-14-12) You can use "[]" (with possible content) to indicate lists [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-14-13) (these are ignored and not shown anywhere): [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-14-14) :ansoptref:`Title ` `` * `:ansretvalref:`: format return values; reference return values of a module or plugin. Basically the syntax is identical to the one of `:ansoptref:`, except that this references return values instead of options. * `:ansenvvar:`: format environment variables with possible assignment. The syntax is as follows: `` [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-15-1) Environment variable with optional value: [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-15-2) :ansenvvar:`FOO` [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-15-3) :ansenvvar:`FOO=bar` `` * `:ansenvvarref:`: format environment variables with possible assignment; reference the environment variable. The syntax is as follows: ``[](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-16-1) Environment variable with optional value: [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-16-2) :ansenvvarref:`FOO` [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-16-3) :ansenvvarref:`FOO=bar` [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-16-4) [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-16-5) A reference to the definition of "FOO" is added.`` * `:ansplugin:`: reference a plugin, module, or role / role entrypoint. The syntax is as follows: `` [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-17-1) Reference a plugin of a given type in a collection, with an optional title: [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-17-2) :ansplugin:`namespace.name.plugin_name#plugin_type` [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-17-3) :ansplugin:`Reference title ` [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-17-4) [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-17-5) For roles, you can also specify an entrypoint: [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-17-6) :ansplugin:`namespace.name.role_name#role:entrypoint` [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-17-7) :ansplugin:`Reference title ` `` * `:anscollection:`: reference a collection, or a specific section / page for a collection. The syntax is as follows: `` [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-18-1) Reference the collection's page: [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-18-2) :anscollection:`namespace.name` [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-18-3) :anscollection:`namespace.name#collection` [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-18-4) :anscollection:`namespace.name#plugins` [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-18-5) [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-18-6) Reference the communication section on the collection's page: [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-18-7) :anscollection:`namespace.name#communication` [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-18-8) [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-18-9) Reference the collection's changelog: [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-18-10) :anscollection:`namespace.name#changelog` [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-18-11) Reference the changelog section on the collection's page: [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-18-12) :anscollection:`namespace.name#changelog-section` [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-18-13) [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-18-14) Reference the plugin index on the collection's page: [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-18-15) :anscollection:`namespace.name#plugin-index` [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-18-16) [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-18-17) Reference the list of plugins of a given type on the collection's page: [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-18-18) :anscollection:`namespace.name#plugin-` [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-18-19) Concretely: [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-18-20) :anscollection:`namespace.name#plugin-module` [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-18-21) :anscollection:`namespace.name#plugin-lookup` [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-18-22) :anscollection:`namespace.name#plugin-role` `` Adding useful links to the docsite[¶](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#adding-useful-links-to-the-docsite "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------------------------- You can add general links of interest to your collection page and the plugin pages, like for example links pointing to how to submit a bug report, how to request a feature, or where to ask for help. You can also provide links to communication channels like the Ansible Forum, Matrix rooms, IRC channels, and mailing lists. These can be configured in `docs/docsite/links.yml`. A template showing what is available can be found below: ``[](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-1) --- [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-2) # This will make sure that plugin and module documentation gets Edit on GitHub links [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-3) # that allow users to directly create a PR for this plugin or module in GitHub's UI. [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-4) # Remove this section if the collection repository is not on GitHub, or if you do not want this [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-5) # functionality for your collection. [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-6) edit_on_github: [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-7) repository: ansible-collections/community.REPO_NAME [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-8) branch: main [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-9) # If your collection root (the directory containing galaxy.yml) does not coincide with your [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-10) # repository's root, you have to specify the path to the collection root here. For example, [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-11) # if the collection root is in a subdirectory ansible_collections/community/REPO_NAME [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-12) # in your repository, you have to set path_prefix to 'ansible_collections/community/REPO_NAME'. [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-13) path_prefix: '' [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-14) [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-15) # Here you can add arbitrary extra links. Please keep the number of links down to a [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-16) # minimum! Also please keep the description short, since this will be the text put on [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-17) # a button. [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-18) # [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-19) # Also note that some links are automatically added from information in galaxy.yml. [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-20) # The following are automatically added: [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-21) # 1. A link to the issue tracker (if `issues` is specified); [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-22) # 2. A link to the homepage (if `homepage` is specified and does not equal the [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-23) # `documentation` or `repository` link); [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-24) # 3. A link to the collection's repository (if `repository` is specified). [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-25) [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-26) extra_links: [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-27) - description: Report an issue [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-28) url: https://github.com/ansible-collections/community.REPO_NAME/issues/new/choose [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-29) [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-30) # Specify communication channels for your collection. We suggest to not specify more [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-31) # than one place for communication per communication tool to avoid confusion. [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-32) communication: [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-33) forums: [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-34) - topic: Ansible Forum [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-35) # The following URL directly points to the "Get Help" section [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-36) url: https://forum.ansible.com/c/help/6/none [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-37) matrix_rooms: [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-38) - topic: General usage and support questions [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-39) room: '#users:ansible.im' [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-40) irc_channels: [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-41) # The IRC channels are only mentioned as examples and [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-42) # should not be used except in very specific circumstances. [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-43) - topic: General usage and support questions [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-44) network: Libera [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-45) channel: '#ansible' [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-46) mailing_lists: [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-47) # The mailing lists are only mentioned as examples and [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-48) # should not be used except in very specific circumstances. [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-49) # Please note that the ansible-project group used as an example [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-50) # below is read-only and will soon vanish completely. [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-51) - topic: Ansible Project List [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-52) url: https://groups.google.com/g/ansible-project [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-53) # You can also add a `subscribe` field with an URI that allows to subscribe [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-54) # to the mailing list. For lists on https://groups.google.com/ a subscribe link is [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-19-55) # automatically generated.`` Publishing a docsite with GitHub Actions[¶](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#publishing-a-docsite-with-github-actions "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The [ansible-community/github-docs-build GitHub repository](https://github.com/ansible-community/github-docs-build) provides actions and shared workflows that can be used to: * Build a collection docsite when pushing to the `main` branch, and uploading it for example to GitHub pages; * Build a collection docsite during PRs, add a PR comment which shows the differences to the current documentation, and optionally push the PR docsite to GitHub pages so contributors can quickly see how their modified documentation looks like. These are documented in detail in the [repository's Wiki](https://github.com/ansible-community/github-docs-build/wiki) . Please refer to the Wiki for more information. If you want to see this in action, you can take a look at the community.crypto collection: * [Workflow for building documentation on push to `main` and `stable-*` branches](https://github.com/ansible-collections/community.crypto/blob/main/.github/workflows/docs-push.yml) * [Workflow for PR documentation](https://github.com/ansible-collections/community.crypto/blob/main/.github/workflows/docs-pr.yml) Generating RST files for inclusion in the collection repository[¶](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#generating-rst-files-for-inclusion-in-the-collection-repository "Permanent link") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Some collections include RST files for every module, plugin, and role they include in `docs/`. Traditionally, `collection_prep_add_docs` from the [ansible-network/collection\_prep GitHub repository](https://github.com/ansible-network/collection_prep) was used for this, which [appears to be unmaintained](https://github.com/ansible-network/collection_prep/issues/91) . antsibull-docs now can also generate such files with the `collection-plugins` subcommand. This can be done as follows: `[](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-20-1) $ cd ~/collections/ansible_collections/community/crypto [](https://docs.ansible.com/projects/antsibull-docs/collection-docs/#__codelineno-20-2) $ antsibull-docs collection-plugins --dest-dir docs/ --output-format simplified-rst --use-current --fqcn-plugin-names community.crypto` It is not clear to me why some collections chose to include these RST files in their repository. I would recommend not to do that, but instead provide a rendered docsite. If users want to read documentation using only the installed collection, they have a better experience using the `ansible-doc` command line tool, or building a HTML version of the docsite themselves and looking at it in a browser. --- # antsibull-changelog Release Notes - antsibull-changelog – Ansible Changelog Tool [Skip to content](https://docs.ansible.com/projects/antsibull-changelog/changelog/#ansible-changelog-tool-release-notes) Ansible Changelog Tool Release Notes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#ansible-changelog-tool-release-notes "Permanent link") ================================================================================================================================================================ v0.35.0[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#v0350 "Permanent link") ---------------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#release-summary "Permanent link") Feature release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#minor-changes "Permanent link") * Antsibull-changelog now also depends on antsibull-docs-parser ([https://github.com/ansible-community/antsibull-changelog/pull/213](https://github.com/ansible-community/antsibull-changelog/pull/213) ). * Declare support for Python 3.14 ([https://github.com/ansible-community/antsibull-changelog/pull/207](https://github.com/ansible-community/antsibull-changelog/pull/207) ). * Process Ansible markup in plugin/module/role `short_description` ([https://github.com/ansible-community/antsibull-changelog/issues/207](https://github.com/ansible-community/antsibull-changelog/issues/207) , [https://github.com/ansible-community/antsibull-changelog/pull/213](https://github.com/ansible-community/antsibull-changelog/pull/213) ). v0.34.0[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#v0340 "Permanent link") ---------------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#release-summary_1 "Permanent link") Feature release for antsibull-build. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#minor-changes_1 "Permanent link") * The `RSTDocumentRenderer` API now allows to configure section underlines. This is needed to fix the Ansible 12 porting guide ([https://github.com/ansible-community/antsibull-changelog/pull/203](https://github.com/ansible-community/antsibull-changelog/pull/203) ). v0.33.0[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#v0330 "Permanent link") ---------------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#release-summary_2 "Permanent link") Maintenance release for fixing / deprecating certain boolean options. ### Breaking Changes / Porting Guide[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#breaking-changes-porting-guide "Permanent link") * The `--strict` option of the `lint-changelog-yaml` subcommand no longer expects a parameter. It now matches what was documented ([https://github.com/ansible-community/antsibull-changelog/issues/195](https://github.com/ansible-community/antsibull-changelog/issues/195) , [https://github.com/ansible-community/antsibull-changelog/pull/196](https://github.com/ansible-community/antsibull-changelog/pull/196) ). ### Deprecated Features[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#deprecated-features "Permanent link") * The boolean valued options `--is-collection` and `--collection-flatmap` will likely change to proper flags (`--flag` and _\--no-flag\`_ instead of `--flag true`/`--flag false`) in the near future. If you are using these options and want them to not change, or have other suggestions, please [create an issue in the antsibull-changelog repository](https://github.com/ansible-community/antsibull-changelog/issues/new) ([https://github.com/ansible-community/antsibull-changelog/pull/199](https://github.com/ansible-community/antsibull-changelog/pull/199) ). v0.32.0[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#v0320 "Permanent link") ---------------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#release-summary_3 "Permanent link") Feature release. ### Major Changes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#major-changes "Permanent link") * The new configuration setting `output` allows to configure more precisely which changelog files are generated and how they are formatted ([https://github.com/ansible-community/antsibull-changelog/issues/190](https://github.com/ansible-community/antsibull-changelog/issues/190) , [https://github.com/ansible-community/antsibull-changelog/pull/194](https://github.com/ansible-community/antsibull-changelog/pull/194) ). ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#minor-changes_2 "Permanent link") * Antsibull-changelog now depends on Pydantic 2 ([https://github.com/ansible-community/antsibull-changelog/pull/193](https://github.com/ansible-community/antsibull-changelog/pull/193) ). * Antsibull-changelog now uses Pydantic to parse and validate the config. This means that validation is more strict than before and might reject configs that were incorrect, but still got accepted somehow ([https://github.com/ansible-community/antsibull-changelog/pull/193](https://github.com/ansible-community/antsibull-changelog/pull/193) ). ### Breaking Changes / Porting Guide[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#breaking-changes-porting-guide_1 "Permanent link") * When using antsibull-changelog as a library, `ChangelogConfig`'s constructor should no longer be called directly. Instead, use the class method `ChangelogConfig.parse()`, which has the same signature than the previous constructor, except that `ignore_is_other_project` now must be a keyword parameter ([https://github.com/ansible-community/antsibull-changelog/pull/193](https://github.com/ansible-community/antsibull-changelog/pull/193) ). * When using antsibull-changelog as a library, `rendering.changelog.generate_changelog()` now needs a `ChangelogOutput` object instead of the `document_format: TextFormat` parameter, and the `config` and `changelog_path` parameters have been removed ([https://github.com/ansible-community/antsibull-changelog/pull/194](https://github.com/ansible-community/antsibull-changelog/pull/194) ). * When using the `--output` argument for `antsibull-changelog generate`, the generated changelog's title will not contain any parts of the version number. If you need this, [please create an issue](https://github.com/ansible-community/antsibull-changelog/issues/new) ([https://github.com/ansible-community/antsibull-changelog/pull/194](https://github.com/ansible-community/antsibull-changelog/pull/194) ). ### Deprecated Features[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#deprecated-features_1 "Permanent link") * The configuration settings `changelog_filename_template`, `changelog_filename_version_depth`, and `output_formats` are deprecated and will eventually be removed. Use the new setting `output` instead. Note that there are no runtime warnings right now. If the time to remove them comes nearer, there will be runtime warnings for a longer time first before they are actually removed ([https://github.com/ansible-community/antsibull-changelog/pull/194](https://github.com/ansible-community/antsibull-changelog/pull/194) ). ### Removed Features (previously deprecated)[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#removed-features-previously-deprecated "Permanent link") * Python API: remove `antsibull_changelog.rst` module ([https://github.com/ansible-community/antsibull-changelog/pull/183](https://github.com/ansible-community/antsibull-changelog/pull/183) ). * Python API: remove constructor arguments `plugins` and `fragments` from class `ChangelogGenerator` in `antsibull_changelog.rendering.changelog` ([https://github.com/ansible-community/antsibull-changelog/pull/183](https://github.com/ansible-community/antsibull-changelog/pull/183) ). * Python API: remove method `ChangelogEntry.add_section_content`, class `ChangelogGenerator`, and function `generate_changelog` from `antsibull_changelog.changelog_generator` ([https://github.com/ansible-community/antsibull-changelog/pull/183](https://github.com/ansible-community/antsibull-changelog/pull/183) ). * When using antsibull-changelog as a library, the fields `changelog_filename_template`, `changelog_filename_version_depth`, and `output_formats` are no longer available in `ChangelogConfig`. Use `output` instead ([https://github.com/ansible-community/antsibull-changelog/pull/194](https://github.com/ansible-community/antsibull-changelog/pull/194) ). v0.31.2[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#v0312 "Permanent link") ---------------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#release-summary_4 "Permanent link") Bugfix release. ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#bugfixes "Permanent link") * When linting found RST problems with rstcheck, the error messages were reduced to a single letter ([https://github.com/ansible-community/antsibull-changelog/pull/188](https://github.com/ansible-community/antsibull-changelog/pull/188) ). v0.31.1[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#v0311 "Permanent link") ---------------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#release-summary_5 "Permanent link") Bugfix release for ansible-core. ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#bugfixes_1 "Permanent link") * Fix `namespace` extraction for ansible-core modules ([https://github.com/ansible-community/antsibull-changelog/issues/184](https://github.com/ansible-community/antsibull-changelog/issues/184) , [https://github.com/ansible-community/antsibull-changelog/pull/185](https://github.com/ansible-community/antsibull-changelog/pull/185) ). v0.31.0[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#v0310 "Permanent link") ---------------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#release-summary_6 "Permanent link") Feature release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#minor-changes_3 "Permanent link") * Add `--strict` parameter to the `lint-changelog-yaml` subcommand to also check for extra fields that should not be there ([https://github.com/ansible-community/antsibull-changelog/pull/182](https://github.com/ansible-community/antsibull-changelog/pull/182) ). * Declare support for Python 3.13 ([https://github.com/ansible-community/antsibull-changelog/pull/180](https://github.com/ansible-community/antsibull-changelog/pull/180) ). * Python API: allow to extract extra data when loading changelog files, and allow to insert extra data when saving ([https://github.com/ansible-community/antsibull-changelog/pull/181](https://github.com/ansible-community/antsibull-changelog/pull/181) ). * Python API: allow to preprocess changelog.yaml before linting ([https://github.com/ansible-community/antsibull-changelog/pull/181](https://github.com/ansible-community/antsibull-changelog/pull/181) ). ### Breaking Changes / Porting Guide[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#breaking-changes-porting-guide_2 "Permanent link") * More internal code related to the old changelog format has been removed. This only potentially affects other projects which consume antsibull-changelog as a library. The sister antsibull projects antsibull-build and antsibull-docs might only be affected in older versions. **Users of the antsibull-changelog CLI tool are not affected by this change** ([https://github.com/ansible-community/antsibull-changelog/pull/179](https://github.com/ansible-community/antsibull-changelog/pull/179) ). v0.30.0[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#v0300 "Permanent link") ---------------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#release-summary_7 "Permanent link") Feature release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#minor-changes_4 "Permanent link") * Allow to configure the used VCS in `changelogs/config.yml`. Valid choices are `none` (default), `git`, or `auto`. If set to `git`, or `auto` detects that the project is part of a Git repository, only non-ignored files will be copied to a temporary directory when trying to load information on Ansible modules, plugins and roles ([https://github.com/ansible-community/antsibull-changelog/issues/172](https://github.com/ansible-community/antsibull-changelog/issues/172) , [https://github.com/ansible-community/antsibull-changelog/pull/175](https://github.com/ansible-community/antsibull-changelog/pull/175) ). * Antsibull-changelog now depends on the new package antsibull-docutils. This should not have any visible impact, expect potentially improved MarkDown output ([https://github.com/ansible-community/antsibull-changelog/pull/174](https://github.com/ansible-community/antsibull-changelog/pull/174) ). * Antsibull-changelog now depends on the new project antsibull-fileutils ([https://github.com/ansible-community/antsibull-changelog/pull/176](https://github.com/ansible-community/antsibull-changelog/pull/176) ). * If you are using [argcomplete](https://pypi.org/project/argcomplete/) global completion, you can now tab-complete `antsibull-changelog` command lines. See [Activating global completion](https://pypi.org/project/argcomplete/#activating-global-completion) in the argcomplete README for how to enable tab completion globally. This will also tab-complete Ansible commands such as `ansible-playbook` and `ansible-test` ([https://github.com/ansible-community/antsibull-changelog/pull/173](https://github.com/ansible-community/antsibull-changelog/pull/173) ). v0.29.0[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#v0290 "Permanent link") ---------------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#release-summary_8 "Permanent link") Feature release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#minor-changes_5 "Permanent link") * Add a `reformat` command that reformats `changelogs/changelog.yaml` to the current settings of `changelogs/config.yaml` ([https://github.com/ansible-community/antsibull-changelog/pull/169](https://github.com/ansible-community/antsibull-changelog/pull/169) ). * Adds a new configuration option `changelog_sort`. This option allows sorting of changelog entries in `changelogs/changelog.yaml` ([https://github.com/ansible-community/antsibull-changelog/pull/165](https://github.com/ansible-community/antsibull-changelog/pull/165) ). * Replaces numbers with constants for return codes ([https://github.com/ansible-community/antsibull-changelog/issues/77](https://github.com/ansible-community/antsibull-changelog/issues/77) ). ### Removed Features (previously deprecated)[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#removed-features-previously-deprecated_1 "Permanent link") * Removes support for the deprecated classic changelog format. `changes_format` must now be present and set to `combined` for ansible-core usage, and the value `classic` is no longer allowed ([https://github.com/ansible-community/antsibull-changelog/issues/137](https://github.com/ansible-community/antsibull-changelog/issues/137) ). ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#bugfixes_2 "Permanent link") * Remove Python version check that was checking for Python >= 3.6 (instead of >= 3.9). This check is not really necessary since `pyproject.toml` declares `requires-python`, and old enough Python versions where pip does not know about `requires-python` will not load antsibull-changelog due to syntax errors anyway ([https://github.com/ansible-community/antsibull-changelog/pull/167](https://github.com/ansible-community/antsibull-changelog/pull/167) ). v0.28.0[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#v0280 "Permanent link") ---------------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#release-summary_9 "Permanent link") Feature release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#minor-changes_6 "Permanent link") * There is now an option `changelog_nice_yaml` to prepend the YAML document start marker `---` to the header of the `changelogs/changelog.yaml` file, and to increases indentation level on list items. This makes the file pass ansible-lint ([https://github.com/ansible-community/antsibull-changelog/issues/91](https://github.com/ansible-community/antsibull-changelog/issues/91) , [https://github.com/ansible-community/antsibull-changelog/issues/152](https://github.com/ansible-community/antsibull-changelog/issues/152) , [https://github.com/ansible-community/antsibull-changelog/pull/160](https://github.com/ansible-community/antsibull-changelog/pull/160) ). v0.27.0[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#v0270 "Permanent link") ---------------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#release-summary_10 "Permanent link") Feature release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#minor-changes_7 "Permanent link") * Adds period where needed at end of new plugin short descriptions. Controlled by the `add_plugin_period` option in the config file ([https://github.com/ansible-community/antsibull-changelog/issues/87](https://github.com/ansible-community/antsibull-changelog/issues/87) , [https://github.com/ansible-community/antsibull-changelog/pull/162](https://github.com/ansible-community/antsibull-changelog/pull/162) ). v0.26.0[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#v0260 "Permanent link") ---------------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#release-summary_11 "Permanent link") Feature release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#minor-changes_8 "Permanent link") * The Markdown output format is now compatible with [python-markdown](https://python-markdown.github.io/) and [mkdocs](https://www.mkdocs.org/) , as long as the [pymdownx.escapeall](https://facelessuser.github.io/pymdown-extensions/extensions/escapeall/) extension is enabled ([https://github.com/ansible-community/antsibull-changelog/pull/153](https://github.com/ansible-community/antsibull-changelog/pull/153) ). v0.25.0[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#v0250 "Permanent link") ---------------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#release-summary_12 "Permanent link") Bugfix and feature release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#minor-changes_9 "Permanent link") * Add `--version` flag to print package version and exit ([https://github.com/ansible-community/antsibull-changelog/pull/147](https://github.com/ansible-community/antsibull-changelog/pull/147) ). ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#bugfixes_3 "Permanent link") * When multiple output formats are defined and `antsibull-changelog generate` is used with both `--output` and `--output-format`, an error was displayed that `--output-format` must be specified ([https://github.com/ansible-community/antsibull-changelog/issues/149](https://github.com/ansible-community/antsibull-changelog/issues/149) , [https://github.com/ansible-community/antsibull-changelog/pull/151](https://github.com/ansible-community/antsibull-changelog/pull/151) ). v0.24.0[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#v0240 "Permanent link") ---------------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#release-summary_13 "Permanent link") Feature release which now allows to output MarkDown. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#minor-changes_10 "Permanent link") * Allow automatically retrieving package version for hatch projects with the `hatch version` command ([https://github.com/ansible-community/antsibull-changelog/pull/141](https://github.com/ansible-community/antsibull-changelog/pull/141) ). * Allow to render changelogs as MarkDown. The output formats written can be controlled with the `output_formats` option in the config file ([https://github.com/ansible-community/antsibull-changelog/pull/139](https://github.com/ansible-community/antsibull-changelog/pull/139) ). * Officially support Python 3.12 ([https://github.com/ansible-community/antsibull-changelog/pull/134](https://github.com/ansible-community/antsibull-changelog/pull/134) ). ### Deprecated Features[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#deprecated-features_2 "Permanent link") * Some code in `antsibull_changelog.changelog_entry` has been deprecated, and the `antsibull_changelog.rst` module has been deprecated completely. If you use them in your own code, please take a look at the [PR deprecating them](https://github.com/ansible-community/antsibull-changelog/pull/139) for information on how to stop using them ([https://github.com/ansible-community/antsibull-changelog/pull/139](https://github.com/ansible-community/antsibull-changelog/pull/139) ). v0.23.0[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#v0230 "Permanent link") ---------------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#release-summary_14 "Permanent link") Feature release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#minor-changes_11 "Permanent link") * Allow to generate changelog for a specific version ([https://github.com/ansible-community/antsibull-changelog/pull/130](https://github.com/ansible-community/antsibull-changelog/pull/130) ). * Allow to generate only the last entry without preamble with the `generate` command ([https://github.com/ansible-community/antsibull-changelog/pull/131](https://github.com/ansible-community/antsibull-changelog/pull/131) ). * Allow to write `generate` output to a user-provided file ([https://github.com/ansible-community/antsibull-changelog/pull/131](https://github.com/ansible-community/antsibull-changelog/pull/131) ). v0.22.0[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#v0220 "Permanent link") ---------------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#release-summary_15 "Permanent link") New feature release ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#minor-changes_12 "Permanent link") * Add `antsibull-changelog-lint` and `antsibull-changelog-lint-changelog-yaml` pre-commit.com hooks ([https://github.com/ansible-community/antsibull-changelog/pull/125](https://github.com/ansible-community/antsibull-changelog/pull/125) ). * Add `toml` extra to pull in a toml parser to use to guess the version based on `pyproject.toml` ([https://github.com/ansible-community/antsibull-changelog/pull/126](https://github.com/ansible-community/antsibull-changelog/pull/126) ). v0.21.0[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#v0210 "Permanent link") ---------------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#release-summary_16 "Permanent link") Maintenance release with a deprecation. ### Deprecated Features[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#deprecated-features_3 "Permanent link") * Support for `classic` changelogs is deprecated and will be removed soon. If you need to build changelogs for Ansible 2.9 or before, please use an older version ([https://github.com/ansible-community/antsibull-changelog/pull/123](https://github.com/ansible-community/antsibull-changelog/pull/123) ). v0.20.0[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#v0200 "Permanent link") ---------------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#release-summary_17 "Permanent link") Bugfix and maintenance release using a new build system. ### Major Changes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#major-changes_1 "Permanent link") * Change pyproject build backend from `poetry-core` to `hatchling`. `pip install antsibull` works exactly the same as before, but some users may be affected depending on how they build/install the project ([https://github.com/ansible-community/antsibull-changelog/pull/109](https://github.com/ansible-community/antsibull-changelog/pull/109) ). ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#bugfixes_4 "Permanent link") * When releasing ansible-core and only one of `--version` and `--codename` is supplied, error out instead of ignoring the supplied value ([https://github.com/ansible-community/antsibull-changelog/issues/104](https://github.com/ansible-community/antsibull-changelog/issues/104) , [https://github.com/ansible-community/antsibull-changelog/pull/105](https://github.com/ansible-community/antsibull-changelog/pull/105) ). v0.19.0[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#v0190 "Permanent link") ---------------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#release-summary_18 "Permanent link") Feature release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#minor-changes_13 "Permanent link") * Allow to extract other project versions for JavaScript / TypeScript projects from `package.json` ([https://github.com/ansible-community/antsibull-changelog/pull/100](https://github.com/ansible-community/antsibull-changelog/pull/100) ). * Allow to extract other project versions for Python projects from PEP 621 conformant `pyproject.toml` ([https://github.com/ansible-community/antsibull-changelog/pull/100](https://github.com/ansible-community/antsibull-changelog/pull/100) ). * Support Python 3.11's `tomllib` to load `pyproject.toml` ([https://github.com/ansible-community/antsibull-changelog/issues/101](https://github.com/ansible-community/antsibull-changelog/issues/101) , [https://github.com/ansible-community/antsibull-changelog/pull/102](https://github.com/ansible-community/antsibull-changelog/pull/102) ). * Use more specific exceptions than `Exception` for some cases in internal code ([https://github.com/ansible-community/antsibull-changelog/pull/103](https://github.com/ansible-community/antsibull-changelog/pull/103) ). v0.18.0[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#v0180 "Permanent link") ---------------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#release-summary_19 "Permanent link") Maintenance release that drops support for older Python versions. ### Breaking Changes / Porting Guide[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#breaking-changes-porting-guide_3 "Permanent link") * Drop support for Python 3.6, 3.7, and 3.8 ([https://github.com/ansible-community/antsibull-changelog/pull/93](https://github.com/ansible-community/antsibull-changelog/pull/93) ). v0.17.0[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#v0170 "Permanent link") ---------------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#release-summary_20 "Permanent link") Feature release for ansible-core. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#minor-changes_14 "Permanent link") * Only allow a `trival` section in the ansible-core/ansible-base changelog when explicitly configured ([https://github.com/ansible-community/antsibull-changelog/pull/90](https://github.com/ansible-community/antsibull-changelog/pull/90) ). v0.16.0[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#v0160 "Permanent link") ---------------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#release-summary_21 "Permanent link") Feature and bugfix release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#minor-changes_15 "Permanent link") * Allow to extract other project versions for Python poetry projects from `pyproject.toml` ([https://github.com/ansible-community/antsibull-changelog/pull/80](https://github.com/ansible-community/antsibull-changelog/pull/80) ). * The files in the source repository now follow the [REUSE Specification](https://reuse.software/spec/) . The only exceptions are changelog fragments in `changelogs/fragments/` ([https://github.com/ansible-community/antsibull-changelog/pull/82](https://github.com/ansible-community/antsibull-changelog/pull/82) ). ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#bugfixes_5 "Permanent link") * Mark rstcheck 4.x and 5.x as compatible. Support rstcheck 6.x as well ([https://github.com/ansible-community/antsibull-changelog/pull/81](https://github.com/ansible-community/antsibull-changelog/pull/81) ). v0.15.0[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#v0150 "Permanent link") ---------------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#release-summary_22 "Permanent link") Feature release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#minor-changes_16 "Permanent link") * Add `changelogs/changelog.yaml` file format linting subcommand that was previously part of antsibull-lint ([https://github.com/ansible-community/antsibull-changelog/pull/76](https://github.com/ansible-community/antsibull-changelog/pull/76) , [https://github.com/ansible-community/antsibull/issues/410](https://github.com/ansible-community/antsibull/issues/410) ). v0.14.0[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#v0140 "Permanent link") ---------------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#release-summary_23 "Permanent link") Feature release that will speed up the release process with ansible-core 2.13. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#minor-changes_17 "Permanent link") * The internal `changelog.yaml` linting API allows to use `packaging.version.Version` for version numbers instead of semantic versioning ([https://github.com/ansible-community/antsibull-changelog/pull/73](https://github.com/ansible-community/antsibull-changelog/pull/73) ). * Use the new `--metadata-dump` option for ansible-core 2.13+ to quickly dump and extract all module/plugin `version_added` values for the collection ([https://github.com/ansible-community/antsibull-changelog/pull/72](https://github.com/ansible-community/antsibull-changelog/pull/72) ). v0.13.0[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#v0130 "Permanent link") ---------------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#release-summary_24 "Permanent link") This release makes changelog building more reliable. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#minor-changes_18 "Permanent link") * Always lint fragments before releasing ([https://github.com/ansible-community/antsibull-changelog/issues/65](https://github.com/ansible-community/antsibull-changelog/issues/65) , [https://github.com/ansible-community/antsibull-changelog/pull/67](https://github.com/ansible-community/antsibull-changelog/pull/67) ). ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#bugfixes_6 "Permanent link") * Fix issues with module namespaces when symlinks appear in the path to the temp directory ([https://github.com/ansible-community/antsibull-changelog/issues/68](https://github.com/ansible-community/antsibull-changelog/issues/68) , [https://github.com/ansible-community/antsibull-changelog/pull/69](https://github.com/ansible-community/antsibull-changelog/pull/69) ). * Stop mentioning `galaxy.yaml` instead of `galaxy.yml` in some error messages ([https://github.com/ansible-community/antsibull-changelog/pull/66](https://github.com/ansible-community/antsibull-changelog/pull/66) ). v0.12.0[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#v0120 "Permanent link") ---------------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#release-summary_25 "Permanent link") New feature release which supports other projects than ansible-core and Ansible collections. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#minor-changes_19 "Permanent link") * Support changelogs for other projects than ansible-core/-base and Ansible collections ([https://github.com/ansible-community/antsibull-changelog/pull/60](https://github.com/ansible-community/antsibull-changelog/pull/60) ). ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#bugfixes_7 "Permanent link") * Fix prerelease collapsing when `use_semantic_versioning` is set to `true` for ansible-core. v0.11.0[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#v0110 "Permanent link") ---------------------------------------------------------------------------------------------------- ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#minor-changes_20 "Permanent link") * When using ansible-core 2.11 or newer, will now detect new roles with argument spec. We only consider the `main` entrypoint of roles. ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#bugfixes_8 "Permanent link") * When subdirectories of `modules` are used in ansible-base/ansible-core, the wrong module name was passed to `ansible-doc` when `--use-ansible-doc` was not used. v0.10.0[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#v0100 "Permanent link") ---------------------------------------------------------------------------------------------------- ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#minor-changes_21 "Permanent link") * The new `--cummulative-release` option for `antsibull-changelog release` allows to add all plugins and objects to a release since whose `version_added` is later than the previous release version (or ancestor if there was no previous release), and at latest the current release version. This is needed for major releases of `community.general` and similarly organized collections. * Will now print a warning when a release is made where the no `prelude_section_name` section (default: `release_summary`) appears. ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#bugfixes_9 "Permanent link") * Make sure that the plugin caching inside ansible-base/-core works without `--use-ansible-doc`. v0.9.0[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#v090 "Permanent link") -------------------------------------------------------------------------------------------------- ### Major Changes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#major-changes_2 "Permanent link") * Add support for reporting new playbooks and roles in collections. * Add support for special changelog fragment sections which add new plugins and/or objects to the changelog for this version. This is mainly useful for `test` and `filter` plugins, and for `playbook` and `role` objects, which are not yet automatically detected and mentioned in `changelogs/changelog.yaml` or the generated RST changelog. The format of these sections and their content is as follows: `[](https://docs.ansible.com/projects/antsibull-changelog/changelog/#__codelineno-0-1) --- [](https://docs.ansible.com/projects/antsibull-changelog/changelog/#__codelineno-0-2) add plugin.filter: [](https://docs.ansible.com/projects/antsibull-changelog/changelog/#__codelineno-0-3) - name: to_time_unit [](https://docs.ansible.com/projects/antsibull-changelog/changelog/#__codelineno-0-4) description: Converts a time expression to a given unit [](https://docs.ansible.com/projects/antsibull-changelog/changelog/#__codelineno-0-5) - name: to_seconds [](https://docs.ansible.com/projects/antsibull-changelog/changelog/#__codelineno-0-6) description: Converts a time expression to seconds [](https://docs.ansible.com/projects/antsibull-changelog/changelog/#__codelineno-0-7) add object.role: [](https://docs.ansible.com/projects/antsibull-changelog/changelog/#__codelineno-0-8) - name: nginx [](https://docs.ansible.com/projects/antsibull-changelog/changelog/#__codelineno-0-9) description: The most awesome nginx installation role ever [](https://docs.ansible.com/projects/antsibull-changelog/changelog/#__codelineno-0-10) add object.playbook: [](https://docs.ansible.com/projects/antsibull-changelog/changelog/#__codelineno-0-11) - name: wipe_server [](https://docs.ansible.com/projects/antsibull-changelog/changelog/#__codelineno-0-12) description: Totally wipes a server` For every entry, a list of plugins (section `add plugin.xxx`) or objects (section `add object.xxx`) of the given type (`filter`, `test` for plugins, `playbook`, `role` for objects) will be added. Every plugin or object has a short name as well as a short description. These fields correspond to the module/plugin name and the `short_description` field of the `DOCUMENTATION` block of modules and documentable plugins. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#minor-changes_22 "Permanent link") * Add `--update-existing` option for `antsibull-changelog release`, which allows to update the current release's release date and (if relevant) codename instead of simply reporting that the release already exists. ### Breaking Changes / Porting Guide[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#breaking-changes-porting-guide_4 "Permanent link") * The new option `prevent_known_fragments` with default value being the value of `keep_fragments` allows to control whether fragments with names that already appeared in the past are ignored or not. The new behavior happens if `keep_fragments=false`, and is less surprising to users (see [https://github.com/ansible-community/antsibull-changelog/issues/46](https://github.com/ansible-community/antsibull-changelog/issues/46) ). Changelogs with `keep_fragments=true`, like the ansible-base/ansible-core changelog, are not affected. v0.8.1[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#v081 "Permanent link") -------------------------------------------------------------------------------------------------- ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#bugfixes_10 "Permanent link") * Fixed error on generating changelogs when using the trivial section. v0.8.0[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#v080 "Permanent link") -------------------------------------------------------------------------------------------------- ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#minor-changes_23 "Permanent link") * Allow to not save a changelog on release when using API. * Allow to sanitize changelog data on load/save. This means that unknown information will be removed, and bad information will be stripped. This will be enabled in newly created changelog configs, but is disabled for backwards compatibility. v0.7.0[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#v070 "Permanent link") -------------------------------------------------------------------------------------------------- ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#minor-changes_24 "Permanent link") * A new config option, `ignore_other_fragment_extensions` allows for configuring whether only `.yaml` and `.yml` files are used (as mandated by the `ansible-test sanity --test changelog` test). The default value for existing configurations is `false`, and for new configurations `true`. * Allow to use semantic versioning also for Ansible-base with the `use_semantic_versioning` configuration setting. * Refactoring changelog generation code to provide all preludes (release summaries) in changelog entries, and provide generic functionality to extract a grouped list of versions. These changes are mainly for the antsibull project. v0.6.0[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#v060 "Permanent link") -------------------------------------------------------------------------------------------------- ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#minor-changes_25 "Permanent link") * New changelog configurations place the `CHANGELOG.rst` file by default in the top-level directory, and not in `changelogs/`. * The config option `archive_path_template` allows to move fragments into an archive directory when `keep_fragments` is set to `false`. * The option `use_fqcn` (set to `true` in new configurations) allows to use FQCN for new plugins and modules. v0.5.0[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#v050 "Permanent link") -------------------------------------------------------------------------------------------------- ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#minor-changes_26 "Permanent link") * The internal changelog generator code got more flexible to help antsibull generate Ansible porting guides. v0.4.0[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#v040 "Permanent link") -------------------------------------------------------------------------------------------------- ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#minor-changes_27 "Permanent link") * Allow to enable or disable flatmapping via `config.yaml`. ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#bugfixes_11 "Permanent link") * Fix bad module namespace detection when collection was symlinked into Ansible's collection search path. This also allows to add releases to collections which are not installed in a way that Ansible finds them. v0.3.1[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#v031 "Permanent link") -------------------------------------------------------------------------------------------------- ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#bugfixes_12 "Permanent link") * Do not fail when `changelogs/fragments` does not exist. Simply assume there are no fragments in that case. * Improve behavior when `changelogs/config.yaml` is not a dictionary, or does not contain `sections`. * Improve error message when `--is-collection` is specified and `changelogs/config.yaml` cannot be found, or when the `lint` subcommand is used. v0.3.0[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#v030 "Permanent link") -------------------------------------------------------------------------------------------------- ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#minor-changes_28 "Permanent link") * Allow to pass path to ansible-doc binary via `--ansible-doc-bin`. * Changelog generator can be ran via `python -m antsibull_changelog`. * Use `ansible-doc` instead of `/path/to/checkout/bin/ansible-doc` when being run in ansible-base checkouts. v0.2.1[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#v021 "Permanent link") -------------------------------------------------------------------------------------------------- ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#bugfixes_13 "Permanent link") * Allow to enumerate plugins/modules with ansible-doc by specifying `--use-ansible-doc`. v0.2.0[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#v020 "Permanent link") -------------------------------------------------------------------------------------------------- ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#minor-changes_29 "Permanent link") * Added more testing. * Fix internal API for ACD changelog generation (pruning and concatenation of changelogs). * Improve error handling. * Improve reStructuredText creation when new modules with and without namespace exist at the same time. * Title generation improved (remove superfluous space). * Use PyYAML C loader/dumper if available. * `lint` subcommand no longer requires specification whether it is run inside a collection or not (if usual indicators are absent). v0.1.0[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#v010 "Permanent link") -------------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-changelog/changelog/#release-summary_26 "Permanent link") Initial release as antsibull-changelog. The Ansible Changelog Tool has originally been developed by @mattclay in [the ansible/ansible](https://github.com/ansible/ansible/blob/stable-2.9/packaging/release/changelogs/changelog.py) repository for Ansible itself. It has been extended in [felixfontein/ansible-changelog](https://github.com/felixfontein/ansible-changelog/) and [ansible-community/antsibull](https://github.com/ansible-community/antsibull/) to work with collections, until it was moved to its current location [ansible-community/antsibull-changelog](https://github.com/ansible-community/antsibull-changelog/) . --- # antsibull-nox – Antsibull Nox Helper [Skip to content](https://docs.ansible.com/projects/antsibull-nox/#antsibull-nox) antsibull-nox[¶](https://docs.ansible.com/projects/antsibull-nox/#antsibull-nox "Permanent link") ================================================================================================== [![Discuss on Matrix at #antsibull:ansible.com](https://img.shields.io/matrix/antsibull:ansible.com.svg?server_fqdn=ansible-accounts.ems.host&label=Discuss%20on%20Matrix%20at%20%23antsibull:ansible.com&logo=matrix)](https://matrix.to/#/#antsibull:ansible.com) [![Nox badge](https://github.com/ansible-community/antsibull-nox/workflows/nox/badge.svg?event=push&branch=main)](https://github.com/ansible-community/antsibull-nox/actions?query=workflow%3A%22nox%22+branch%3Amain) [![Codecov badge](https://img.shields.io/codecov/c/github/ansible-community/antsibull-nox)](https://codecov.io/gh/ansible-community/antsibull-nox) A nox helper library for Ansible collections. antsibull-nox is covered by the [Ansible Code of Conduct](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html) . To see how antsibull-nox changes, please look at the [antsibull-nox changelog](https://github.com/ansible-community/antsibull-nox/blob/main/CHANGELOG.md) . Note Need help or want to discuss the project? See our [Community guide](https://docs.ansible.com/projects/antsibull-nox/community/) to learn how to join the conversation! Usage[¶](https://docs.ansible.com/projects/antsibull-nox/#usage "Permanent link") ---------------------------------------------------------------------------------- Check out the following pages for more information: * [Introduction](https://docs.ansible.com/projects/antsibull-nox/introduction/) * [Getting started](https://docs.ansible.com/projects/antsibull-nox/getting-started/) * [Running nox in CI](https://docs.ansible.com/projects/antsibull-nox/nox-in-ci/) * [Config file reference](https://docs.ansible.com/projects/antsibull-nox/config-file/) * [noxfile reference](https://docs.ansible.com/projects/antsibull-nox/reference/) * [Troubleshooting](https://docs.ansible.com/projects/antsibull-nox/troubleshooting/) License[¶](https://docs.ansible.com/projects/antsibull-nox/#license "Permanent link") -------------------------------------------------------------------------------------- Unless otherwise noted in the code, it is licensed under the terms of the GNU General Public License v3 or, at your option, later. See [LICENSES/GPL-3.0-or-later.txt](https://github.com/ansible-community/antsibull-nox/tree/main/LICENSE) for a copy of the license. The repository follows the [REUSE Specification](https://reuse.software/spec/) for declaring copyright and licensing information. The only exception are changelog fragments in `changelog/fragments/`. --- # FAQ - Ansible Molecule [Skip to content](https://docs.ansible.com/projects/molecule/faq/#faq) [](https://github.com/ansible/molecule/blob/main/docs/faq.md "Edit this page") [](https://github.com/ansible/molecule/raw/main/docs/faq.md "View source of this page") FAQ[¶](https://docs.ansible.com/projects/molecule/faq/#faq "Permanent link") ============================================================================= Why is my idempotence action failing?[¶](https://docs.ansible.com/projects/molecule/faq/#why-is-my-idempotence-action-failing "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------------ It is important to understand that Molecule does not do anything further than the default functionality of Ansible when determining if your tasks are idempotent or not. Molecule will simply run the converge action twice and check against Ansible's standard output. Therefore, if you are seeing idempotence failures, it is typically related to the underlying Ansible report and not Molecule. If you are facing idempotence failures and intend to raise a bug on our issue tracker, please first manually run `molecule converge` twice and confirm that Ansible itself is reporting task idempotence (changed=0). Why does Molecule make so many shell calls?[¶](https://docs.ansible.com/projects/molecule/faq/#why-does-molecule-make-so-many-shell-calls "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------------------------ Ansible provides a Python API. However, it is not intended for [direct consumption](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_api.html) . We wanted to focus on making Molecule useful, so our efforts were spent consuming Ansible's CLI. Since we already consume Ansible's CLI, we decided to call additional binaries through their respective CLI. Why does Molecule only support specific Ansible versions?[¶](https://docs.ansible.com/projects/molecule/faq/#why-does-molecule-only-support-specific-ansible-versions "Permanent link") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- We can only test against a limited number of Ansible versions and often we rely on bugfixes that were fixed only in recent versions of Ansible. Why are playbooks used to provision instances?[¶](https://docs.ansible.com/projects/molecule/faq/#why-are-playbooks-used-to-provision-instances "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------------------------------ Simplicity. Ansible already supports numerous cloud providers. Too much time was spent in Molecule v1, re-implementing a feature that already existed in the core Ansible modules. Why not using Ansible's python API instead of playbooks?[¶](https://docs.ansible.com/projects/molecule/faq/#why-not-using-ansibles-python-api-instead-of-playbooks "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- This was [evaluated](https://github.com/kireledan/molecule/tree/playbook_proto) early on. It was a toss-up. It would provide simplicity in some situations and complexity in others. Developers know and understand playbooks. Decided against a more elegant and sexy solution. Why are there multiple scenario directories and molecule.yml files?[¶](https://docs.ansible.com/projects/molecule/faq/#why-are-there-multiple-scenario-directories-and-moleculeyml-files "Permanent link") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Again, simplicity. Rather than defining an all encompassing config file opted to normalize. Molecule simply loops through each scenario applying the scenario's molecule.yml. Are there similar tools to Molecule?[¶](https://docs.ansible.com/projects/molecule/faq/#are-there-similar-tools-to-molecule "Permanent link") ---------------------------------------------------------------------------------------------------------------------------------------------- * Ansible's own [Testing Strategies](https://docs.ansible.com/projects/ansible/latest/reference_appendices/test_strategies.html) * [RoleSpec](https://github.com/nickjj/rolespec) Can I run Molecule processes in parallel?[¶](https://docs.ansible.com/projects/molecule/faq/#can-i-run-molecule-processes-in-parallel "Permanent link") -------------------------------------------------------------------------------------------------------------------------------------------------------- Please see [parallel-usage-example](https://docs.ansible.com/projects/molecule/guides/parallel/) for usage. Can I specify random instance IDs in my molecule.yml?[¶](https://docs.ansible.com/projects/molecule/faq/#can-i-specify-random-instance-ids-in-my-moleculeyml "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- This depends on the CI provider but the basic recipe is as follows. Setup your `molecule.yml` to look like this: `[](https://docs.ansible.com/projects/molecule/faq/#__codelineno-0-1) platforms: [](https://docs.ansible.com/projects/molecule/faq/#__codelineno-0-2) - name: "instance-${INSTANCE_UUID}"` Then in your CI provider environment, for example, Gitlab CI, setup: `[](https://docs.ansible.com/projects/molecule/faq/#__codelineno-1-1) variables: [](https://docs.ansible.com/projects/molecule/faq/#__codelineno-1-2) INSTANCE_UUID: "$CI_JOB_ID"` Where `CI_JOB_ID` is the random variable that Gitlab provides. Molecule will resolve the `INSTANCE_UUID` environment variable when creating and looking up the instance name. You can confirm all is in working order by running `molecule list`. Where can I configure my `roles-path` and `collections-paths`?[¶](https://docs.ansible.com/projects/molecule/faq/#where-can-i-configure-my-roles-path-and-collections-paths "Permanent link") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- As of molecule v6, users are expected to make use of [`ansible.cfg`](https://docs.ansible.com/projects/ansible/latest/reference_appendices/config.html) file to alter them when needed. Does Molecule support monorepos?[¶](https://docs.ansible.com/projects/molecule/faq/#does-molecule-support-monorepos "Permanent link") -------------------------------------------------------------------------------------------------------------------------------------- Yes, roles contained in a [monorepo](https://en.wikipedia.org/wiki/Monorepo) with other roles are automatically picked up. See [this page](https://docs.ansible.com/projects/molecule/guides/monolith/) for more information. How can I add development/testing-only dependencies?[¶](https://docs.ansible.com/projects/molecule/faq/#how-can-i-add-developmenttesting-only-dependencies "Permanent link") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Sometimes, it's desirable to only run a dependency role when developing your role with molecule, but not impose a hard dependency on the role itself; for example when you rely on one of its side effects. This can be achieved by an approach like this in your role's `meta/main.yml`: `[](https://docs.ansible.com/projects/molecule/faq/#__codelineno-2-1) --- [](https://docs.ansible.com/projects/molecule/faq/#__codelineno-2-2) dependencies: [](https://docs.ansible.com/projects/molecule/faq/#__codelineno-2-3) - role: [](https://docs.ansible.com/projects/molecule/faq/#__codelineno-2-4) when: lookup('env', 'MOLECULE_FILE')` How can I execute molecule playbooks inside of an execution-environment?[¶](https://docs.ansible.com/projects/molecule/faq/#how-can-i-execute-molecule-playbooks-inside-of-an-execution-environment "Permanent link") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- By default, Molecule uses ansible-playbook to execute the playbooks. However, it has the ability to test playbooks inside of an execution-environment using ansible-navigator as executor backend. This is done by setting `ansible_navigator` as the backend in `executor` section of `molecule.yml`. (Note: This feature is experimental and under development). `[](https://docs.ansible.com/projects/molecule/faq/#__codelineno-3-1) --- [](https://docs.ansible.com/projects/molecule/faq/#__codelineno-3-2) executor: [](https://docs.ansible.com/projects/molecule/faq/#__codelineno-3-3) backend: ansible-navigator [](https://docs.ansible.com/projects/molecule/faq/#__codelineno-3-4) provisioner: [](https://docs.ansible.com/projects/molecule/faq/#__codelineno-3-5) name: ansible` Back to top --- # Configuration - Ansible Navigator Documentation [Skip to content](https://docs.ansible.com/projects/navigator/settings/#the-ansible-navigator-settings-file) [](https://github.com/ansible/ansible-navigator/blob/main/docs/settings.md "Edit this page") ansible-navigator settings[¶](https://docs.ansible.com/projects/navigator/settings/#ansible-navigator-settings "Permanent link") ================================================================================================================================= The ansible-navigator settings file[¶](https://docs.ansible.com/projects/navigator/settings/#the-ansible-navigator-settings-file "Permanent link") --------------------------------------------------------------------------------------------------------------------------------------------------- Settings for `ansible-navigator` can be provided on the command line, set using an environment variable or specified in a settings file. The settings file name and path can be specified with an environment variable or it can be placed in one of two default directories. Currently the following are checked and the first match is used: * `ANSIBLE_NAVIGATOR_CONFIG` (settings file path environment variable if set) * `./ansible-navigator.` (project directory) (**NOTE:** no dot in the file name) * `~/.ansible-navigator.` (home directory) (**NOTE:** note the dot in the file name) Note * The settings file can be in `JSON` or `YAML` format. * For settings in `JSON` format, the extension must be `.json`. * For settings in `YAML` format, the extension must be `.yml` or `.yaml`. * The project and home directories can only contain one settings file each. * If more than one settings file is found in either directory, it will result in an error. You can copy the example settings file below into one of those paths to start your `ansible-navigator` settings file. Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-1) # # cspell:ignore cmdline, workdir [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-2) --- [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-3) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-4) # [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-5) # ansible: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-6) # config: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-7) # help: False [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-8) # path: /tmp/ansible.cfg [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-9) # cmdline: "--forks 15" [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-10) # doc: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-11) # help: False [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-12) # plugin: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-13) # name: shell [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-14) # type: become [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-15) # inventory: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-16) # help: False [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-17) # entries: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-18) # - /tmp/test_inventory.yml [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-19) # playbook: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-20) # help: False [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-21) # path: /tmp/test_playbook.yml [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-22) # [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-23) # ansible-builder: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-24) # help: False [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-25) # workdir: /tmp/ [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-26) # [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-27) # ansible-lint: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-28) # config: ~/ansible-lint.yml [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-29) # lintables: ~/myproject/ [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-30) # [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-31) # ansible-runner: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-32) # artifact-dir: /tmp/test1 [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-33) # rotate-artifacts-count: 10 [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-34) # timeout: 300 [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-35) # job-events: False [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-36) # [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-37) # app: run [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-38) # [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-39) # collection-doc-cache-path: /tmp/cache.db [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-40) # [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-41) # color: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-42) # enable: False [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-43) # osc4: False [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-44) # [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-45) # editor: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-46) # command: vim_from_setting [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-47) # console: False [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-48) # [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-49) # enable-prompts: False [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-50) # [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-51) # exec: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-52) # shell: False [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-53) # command: /bin/foo [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-54) # [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-55) # execution-environment: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-56) # container-engine: podman [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-57) # enabled: False [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-58) # environment-variables: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-59) # pass: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-60) # - ONE [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-61) # - TWO [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-62) # - THREE [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-63) # set: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-64) # KEY1: VALUE1 [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-65) # KEY2: VALUE2 [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-66) # KEY3: VALUE3 [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-67) # image: test_image:latest [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-68) # pull: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-69) # arguments: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-70) # - "--tls-verify=false" [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-71) # policy: never [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-72) # volume-mounts: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-73) # - src: "/tmp" [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-74) # dest: "/test1" [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-75) # options: "Z" [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-76) # container-options: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-77) # - "--net=host" [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-78) # [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-79) # format: json [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-80) # [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-81) # images: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-82) # details: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-83) # - ansible_version [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-84) # - python_version [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-85) # [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-86) # inventory-columns: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-87) # - ansible_network_os [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-88) # - ansible_network_cli_ssh_type [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-89) # - ansible_connection [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-90) # [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-91) logging: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-92) level: critical [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-93) # append: False [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-94) # file: /tmp/log.txt [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-95) # [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-96) # mode: stdout [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-97) # [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-98) # playbook-artifact: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-99) # enable: True [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-100) # replay: /tmp/test_artifact.json [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-101) # save-as: /tmp/test_artifact.json [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-102) # [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-103) # settings: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-104) # effective: False [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-105) # sample: False [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-106) # schema: json [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-107) # sources: False [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-108) # [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-0-109) # time-zone: Japan` The following table describes all available settings. General parameters[¶](https://docs.ansible.com/projects/navigator/settings/#general-parameters "Permanent link") ----------------------------------------------------------------------------------------------------------------- ansible-runner-artifact-dir [¶](https://docs.ansible.com/projects/navigator/settings/#ansible-runner-artifact-dir) The directory path to store artifacts generated by ansible-runner **Added in version:** v1.0 **Default:** No default value set **CLI:** `--rad` or `--ansible-runner-artifact-dir` **ENV:** ANSIBLE\_NAVIGATOR\_ANSIBLE\_RUNNER\_ARTIFACT\_DIR Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-1-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-1-2) ansible-runner: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-1-3) artifact-dir:` ansible-runner-rotate-artifacts-count [¶](https://docs.ansible.com/projects/navigator/settings/#ansible-runner-rotate-artifacts-count) Keep ansible-runner artifact directories, for last n runs, if set to 0 artifact directories won't be deleted **Added in version:** v1.0 **Default:** No default value set **CLI:** `--rac` or `--ansible-runner-rotate-artifacts-count` **ENV:** ANSIBLE\_NAVIGATOR\_ANSIBLE\_RUNNER\_ROTATE\_ARTIFACTS\_COUNT Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-2-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-2-2) ansible-runner: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-2-3) rotate-artifacts-count:` ansible-runner-timeout [¶](https://docs.ansible.com/projects/navigator/settings/#ansible-runner-timeout) The timeout value after which ansible-runner will forcefully stop the execution **Added in version:** v1.0 **Default:** No default value set **CLI:** `--rt` or `--ansible-runner-timeout` **ENV:** ANSIBLE\_NAVIGATOR\_ANSIBLE\_RUNNER\_TIMEOUT Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-3-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-3-2) ansible-runner: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-3-3) timeout:` ansible-runner-write-job-events [¶](https://docs.ansible.com/projects/navigator/settings/#ansible-runner-write-job-events) Write ansible-runner job\_events in the artifact directory **Added in version:** v2.3 **Choices:** 'True' or 'False' **Default:** False **CLI:** `--rwje` or `--ansible-runner-write-job-events` **ENV:** ANSIBLE\_NAVIGATOR\_ANSIBLE\_RUNNER\_WRITE\_JOB\_EVENTS Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-4-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-4-2) ansible-runner: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-4-3) job-events:` app [¶](https://docs.ansible.com/projects/navigator/settings/#app) Subcommands **Added in version:** v1.0 **Choices:** 'builder', 'collections', 'config', 'doc', 'exec', 'images', 'inventory', 'lint', 'replay', 'run', 'settings' or 'welcome' **Default:** welcome **CLI:** positional **ENV:** ANSIBLE\_NAVIGATOR\_APP Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-5-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-5-2) app:` cmdline [¶](https://docs.ansible.com/projects/navigator/settings/#cmdline) Extra parameters passed to the underlying ansible command (e.g. ansible-playbook, ansible-doc, etc) **Added in version:** v1.0 **Default:** No default value set **CLI:** positional **ENV:** ANSIBLE\_NAVIGATOR\_CMDLINE Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-6-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-6-2) ansible: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-6-3) cmdline:` collection-doc-cache-path [¶](https://docs.ansible.com/projects/navigator/settings/#collection-doc-cache-path) The path to collection doc cache **Added in version:** v1.0 **Default:** ~/.cache/ansible-navigator/collection\_doc\_cache.db **CLI:** `--cdcp` or `--collection-doc-cache-path` **ENV:** ANSIBLE\_NAVIGATOR\_COLLECTION\_DOC\_CACHE\_PATH Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-7-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-7-2) collection-doc-cache-path:` container-engine [¶](https://docs.ansible.com/projects/navigator/settings/#container-engine) Specify the container engine (auto=podman then docker) **Added in version:** v1.0 **Choices:** 'auto', 'podman' or 'docker' **Default:** auto **CLI:** `--ce` or `--container-engine` **ENV:** ANSIBLE\_NAVIGATOR\_CONTAINER\_ENGINE Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-8-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-8-2) execution-environment: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-8-3) container-engine:` container-options [¶](https://docs.ansible.com/projects/navigator/settings/#container-options) Extra parameters passed to the container engine command **Added in version:** v2.0 **Default:** No default value set **CLI:** `--co` or `--container-options` **ENV:** ANSIBLE\_NAVIGATOR\_CONTAINER\_OPTIONS Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-9-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-9-2) execution-environment: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-9-3) container-options:` display-color [¶](https://docs.ansible.com/projects/navigator/settings/#display-color) Enable the use of color for mode interactive and stdout **Added in version:** v1.0 **Choices:** 'True' or 'False' **Default:** True **CLI:** `--dc` or `--display-color` **ENV:** NO\_COLOR Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-10-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-10-2) color: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-10-3) enable:` editor-command [¶](https://docs.ansible.com/projects/navigator/settings/#editor-command) Specify the editor command **Added in version:** v1.0 **Default:** vi +{line\_number} {filename} **CLI:** `--ecmd` or `--editor-command` **ENV:** ANSIBLE\_NAVIGATOR\_EDITOR\_COMMAND Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-11-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-11-2) editor: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-11-3) command:` editor-console [¶](https://docs.ansible.com/projects/navigator/settings/#editor-console) Specify if the editor is console based **Added in version:** v1.0 **Choices:** 'True' or 'False' **Default:** True **CLI:** `--econ` or `--editor-console` **ENV:** ANSIBLE\_NAVIGATOR\_EDITOR\_CONSOLE Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-12-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-12-2) editor: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-12-3) console:` execution-environment [¶](https://docs.ansible.com/projects/navigator/settings/#execution-environment) Enable or disable the use of an execution environment **Added in version:** v1.0 **Choices:** 'True' or 'False' **Default:** True **CLI:** `--ee` or `--execution-environment` **ENV:** ANSIBLE\_NAVIGATOR\_EXECUTION\_ENVIRONMENT Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-13-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-13-2) execution-environment: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-13-3) enabled:` execution-environment-image [¶](https://docs.ansible.com/projects/navigator/settings/#execution-environment-image) Specify the name of the execution environment image **Added in version:** v1.0 **Default:** None **CLI:** `--eei` or `--execution-environment-image` **ENV:** ANSIBLE\_NAVIGATOR\_EXECUTION\_ENVIRONMENT\_IMAGE Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-14-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-14-2) execution-environment: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-14-3) image:` execution-environment-volume-mounts [¶](https://docs.ansible.com/projects/navigator/settings/#execution-environment-volume-mounts) Specify volume to be bind mounted within an execution environment (--eev /home/user/test:/home/user/test:Z) **Added in version:** v1.0 **Default:** No default value set **CLI:** `--eev` or `--execution-environment-volume-mounts` **ENV:** ANSIBLE\_NAVIGATOR\_EXECUTION\_ENVIRONMENT\_VOLUME\_MOUNTS Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-15-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-15-2) execution-environment: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-15-3) volume-mounts:` log-append [¶](https://docs.ansible.com/projects/navigator/settings/#log-append) Specify if log messages should be appended to an existing log file, otherwise a new log file will be created per session **Added in version:** v1.0 **Choices:** 'True' or 'False' **Default:** True **CLI:** `--la` or `--log-append` **ENV:** ANSIBLE\_NAVIGATOR\_LOG\_APPEND Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-16-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-16-2) logging: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-16-3) append:` log-file [¶](https://docs.ansible.com/projects/navigator/settings/#log-file) Specify the full path for the ansible-navigator log file **Added in version:** v1.0 **Default:** ./ansible-navigator.log **CLI:** `--lf` or `--log-file` **ENV:** ANSIBLE\_NAVIGATOR\_LOG\_FILE Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-17-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-17-2) logging: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-17-3) file:` log-level [¶](https://docs.ansible.com/projects/navigator/settings/#log-level) Specify the ansible-navigator log level **Added in version:** v1.0 **Choices:** 'debug', 'info', 'warning', 'error' or 'critical' **Default:** warning **CLI:** `--ll` or `--log-level` **ENV:** ANSIBLE\_NAVIGATOR\_LOG\_LEVEL Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-18-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-18-2) logging: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-18-3) level:` mode [¶](https://docs.ansible.com/projects/navigator/settings/#mode) Specify the user-interface mode **Added in version:** v1.0 **Choices:** 'stdout' or 'interactive' **Default:** interactive **CLI:** `-m` or `--mode` **ENV:** ANSIBLE\_NAVIGATOR\_MODE Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-19-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-19-2) mode:` osc4 [¶](https://docs.ansible.com/projects/navigator/settings/#osc4) Enable or disable terminal color changing support with OSC 4 **Added in version:** v1.0 **Choices:** 'True' or 'False' **Default:** True **CLI:** `--osc4` or `--osc4` **ENV:** ANSIBLE\_NAVIGATOR\_OSC4 Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-20-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-20-2) color: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-20-3) osc4:` pass-environment-variable [¶](https://docs.ansible.com/projects/navigator/settings/#pass-environment-variable) Specify an existing environment variable to be passed through to and set within the execution environment (--penv MY\_VAR) **Added in version:** v1.0 **Default:** No default value set **CLI:** `--penv` or `--pass-environment-variable` **ENV:** ANSIBLE\_NAVIGATOR\_PASS\_ENVIRONMENT\_VARIABLES Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-21-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-21-2) execution-environment: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-21-3) environment-variables: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-21-4) pass:` pull-arguments [¶](https://docs.ansible.com/projects/navigator/settings/#pull-arguments) Specify any additional parameters that should be added to the pull command when pulling an execution environment from a container registry. e.g. --pa='--tls-verify=false' **Added in version:** v2.0 **Default:** No default value set **CLI:** `--pa` or `--pull-arguments` **ENV:** ANSIBLE\_NAVIGATOR\_PULL\_ARGUMENTS Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-22-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-22-2) execution-environment: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-22-3) pull: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-22-4) arguments:` pull-policy [¶](https://docs.ansible.com/projects/navigator/settings/#pull-policy) Specify the image pull policy always:Always pull the image, missing:Pull if not locally available, never:Never pull the image, tag:if the image tag is 'latest', always pull the image, otherwise pull if not locally available **Added in version:** v1.0 **Choices:** 'always', 'missing', 'never' or 'tag' **Default:** tag **CLI:** `--pp` or `--pull-policy` **ENV:** ANSIBLE\_NAVIGATOR\_PULL\_POLICY Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-23-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-23-2) execution-environment: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-23-3) pull: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-23-4) policy:` set-environment-variable [¶](https://docs.ansible.com/projects/navigator/settings/#set-environment-variable) Specify an environment variable and a value to be set within the execution environment (--senv MY\_VAR=42) **Added in version:** v1.0 **Default:** No default value set **CLI:** `--senv` or `--set-environment-variable` **ENV:** ANSIBLE\_NAVIGATOR\_SET\_ENVIRONMENT\_VARIABLES Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-24-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-24-2) execution-environment: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-24-3) environment-variables: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-24-4) set:` time-zone [¶](https://docs.ansible.com/projects/navigator/settings/#time-zone) Specify the IANA time zone to use or 'local' to use the system time zone **Added in version:** v2.0 **Default:** UTC **CLI:** `--tz` or `--time-zone` **ENV:** TZ Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-25-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-25-2) time-zone:` [¶](https://docs.ansible.com/projects/navigator/settings/#_1 "Permanent link") ------------------------------------------------------------------------------- ### Subcommand: builder[¶](https://docs.ansible.com/projects/navigator/settings/#subcommand-builder "Permanent link") help-builder [¶](https://docs.ansible.com/projects/navigator/settings/#help-builder) Help options for ansible-builder command in stdout mode **Added in version:** v2.0 **Choices:** 'True' or 'False' **Default:** False **CLI:** `--hb` or `--help-builder` **ENV:** ANSIBLE\_NAVIGATOR\_HELP\_BUILDER Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-26-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-26-2) ansible-builder: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-26-3) help:` workdir [¶](https://docs.ansible.com/projects/navigator/settings/#workdir) Specify the path that contains ansible-builder manifest files **Added in version:** v2.0 **Default:** . **CLI:** `--bwd` or `--workdir` **ENV:** ANSIBLE\_NAVIGATOR\_WORKDIR Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-27-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-27-2) ansible-builder: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-27-3) workdir:` [¶](https://docs.ansible.com/projects/navigator/settings/#_2 "Permanent link") ------------------------------------------------------------------------------- ### Subcommand: collections[¶](https://docs.ansible.com/projects/navigator/settings/#subcommand-collections "Permanent link") format [¶](https://docs.ansible.com/projects/navigator/settings/#format) Specify the format for stdout output. **Added in version:** v2.3 **Choices:** 'json' or 'yaml' **Default:** yaml **CLI:** `--fmt` or `--format` **ENV:** ANSIBLE\_NAVIGATOR\_FORMAT Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-28-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-28-2) format:` [¶](https://docs.ansible.com/projects/navigator/settings/#_3 "Permanent link") ------------------------------------------------------------------------------- ### Subcommand: config[¶](https://docs.ansible.com/projects/navigator/settings/#subcommand-config "Permanent link") config [¶](https://docs.ansible.com/projects/navigator/settings/#config) Specify the path to the ansible configuration file **Added in version:** v1.0 **Default:** No default value set **CLI:** `-c` or `--config` **ENV:** ANSIBLE\_CONFIG Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-29-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-29-2) ansible: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-29-3) config: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-29-4) path:` help-config [¶](https://docs.ansible.com/projects/navigator/settings/#help-config) Help options for ansible-config command in stdout mode **Added in version:** v1.0 **Choices:** 'True' or 'False' **Default:** False **CLI:** `--hc` or `--help-config` **ENV:** ANSIBLE\_NAVIGATOR\_HELP\_CONFIG Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-30-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-30-2) ansible: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-30-3) config: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-30-4) help:` [¶](https://docs.ansible.com/projects/navigator/settings/#_4 "Permanent link") ------------------------------------------------------------------------------- ### Subcommand: doc[¶](https://docs.ansible.com/projects/navigator/settings/#subcommand-doc "Permanent link") help-doc [¶](https://docs.ansible.com/projects/navigator/settings/#help-doc) Help options for ansible-doc command in stdout mode **Added in version:** v1.0 **Choices:** 'True' or 'False' **Default:** False **CLI:** `--hd` or `--help-doc` **ENV:** ANSIBLE\_NAVIGATOR\_HELP\_DOC Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-31-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-31-2) ansible: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-31-3) doc: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-31-4) help:` plugin-name [¶](https://docs.ansible.com/projects/navigator/settings/#plugin-name) Specify the plugin name **Added in version:** v1.0 **Default:** No default value set **CLI:** positional **ENV:** ANSIBLE\_NAVIGATOR\_PLUGIN\_NAME Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-32-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-32-2) ansible: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-32-3) doc: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-32-4) plugin: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-32-5) name:` plugin-type [¶](https://docs.ansible.com/projects/navigator/settings/#plugin-type) Specify the plugin type, 'become', 'cache', 'callback', 'cliconf', 'connection', 'filter', 'httpapi', 'inventory', 'keyword', 'lookup', 'module', 'netconf', 'role', 'shell', 'strategy', 'test' or 'vars' **Added in version:** v1.0 **Choices:** 'become', 'cache', 'callback', 'cliconf', 'connection', 'filter', 'httpapi', 'inventory', 'keyword', 'lookup', 'module', 'netconf', 'role', 'shell', 'strategy', 'test' or 'vars' **Default:** module **CLI:** `-t` or `--type` **ENV:** ANSIBLE\_NAVIGATOR\_PLUGIN\_TYPE Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-33-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-33-2) ansible: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-33-3) doc: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-33-4) plugin: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-33-5) type:` [¶](https://docs.ansible.com/projects/navigator/settings/#_5 "Permanent link") ------------------------------------------------------------------------------- ### Subcommand: exec[¶](https://docs.ansible.com/projects/navigator/settings/#subcommand-exec "Permanent link") exec-command [¶](https://docs.ansible.com/projects/navigator/settings/#exec-command) Specify the command to run within the execution environment **Added in version:** v2.0 **Default:** /bin/bash **CLI:** positional **ENV:** ANSIBLE\_NAVIGATOR\_EXEC\_COMMAND Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-34-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-34-2) exec: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-34-3) command:` exec-shell [¶](https://docs.ansible.com/projects/navigator/settings/#exec-shell) Specify the exec command should be run in a shell **Added in version:** v2.0 **Choices:** 'True' or 'False' **Default:** True **CLI:** `--exshell` or `--exec-shell` **ENV:** ANSIBLE\_NAVIGATOR\_EXEC\_SHELL Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-35-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-35-2) exec: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-35-3) shell:` [¶](https://docs.ansible.com/projects/navigator/settings/#_6 "Permanent link") ------------------------------------------------------------------------------- ### Subcommand: images[¶](https://docs.ansible.com/projects/navigator/settings/#subcommand-images "Permanent link") format [¶](https://docs.ansible.com/projects/navigator/settings/#format) Specify the format for stdout output. **Added in version:** v2.3 **Choices:** 'json' or 'yaml' **Default:** yaml **CLI:** `--fmt` or `--format` **ENV:** ANSIBLE\_NAVIGATOR\_FORMAT Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-36-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-36-2) format:` images-details [¶](https://docs.ansible.com/projects/navigator/settings/#images-details) Provide detailed information about the selected execution environment image **Added in version:** v2.0 **Choices:** 'ansible\_collections', 'ansible\_version', 'everything', 'os\_release', 'python\_packages', 'python\_version', 'redhat\_release' or 'system\_packages' **Default:** \['everything'\] **CLI:** `-d` or `--details` **ENV:** ANSIBLE\_NAVIGATOR\_IMAGES\_DETAILS Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-37-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-37-2) images: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-37-3) details:` [¶](https://docs.ansible.com/projects/navigator/settings/#_7 "Permanent link") ------------------------------------------------------------------------------- ### Subcommand: inventory[¶](https://docs.ansible.com/projects/navigator/settings/#subcommand-inventory "Permanent link") help-inventory [¶](https://docs.ansible.com/projects/navigator/settings/#help-inventory) Help options for ansible-inventory command in stdout mode **Added in version:** v1.0 **Choices:** 'True' or 'False' **Default:** False **CLI:** `--hi` or `--help-inventory` **ENV:** ANSIBLE\_NAVIGATOR\_HELP\_INVENTORY Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-38-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-38-2) ansible: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-38-3) inventory: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-38-4) help:` inventory [¶](https://docs.ansible.com/projects/navigator/settings/#inventory) Specify an inventory file path or comma separated host list **Added in version:** v1.0 **Default:** No default value set **CLI:** `-i` or `--inventory` **ENV:** ANSIBLE\_INVENTORY Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-39-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-39-2) ansible: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-39-3) inventory: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-39-4) entries:` inventory-column [¶](https://docs.ansible.com/projects/navigator/settings/#inventory-column) Specify a host attribute to show in the inventory view **Added in version:** v1.0 **Default:** No default value set **CLI:** `--ic` or `--inventory-column` **ENV:** ANSIBLE\_NAVIGATOR\_INVENTORY\_COLUMNS Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-40-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-40-2) inventory-columns:` [¶](https://docs.ansible.com/projects/navigator/settings/#_8 "Permanent link") ------------------------------------------------------------------------------- ### Subcommand: lint[¶](https://docs.ansible.com/projects/navigator/settings/#subcommand-lint "Permanent link") lint-config [¶](https://docs.ansible.com/projects/navigator/settings/#lint-config) Specify the path to the ansible-lint configuration file **Added in version:** v2.0 **Default:** No default value set **CLI:** `--lic` or `--lint-config` **ENV:** ANSIBLE\_LINT\_CONFIG Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-41-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-41-2) ansible-lint: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-41-3) config:` lintables [¶](https://docs.ansible.com/projects/navigator/settings/#lintables) Path to files on which to run ansible-lint **Added in version:** v2.0 **Default:** No default value set **CLI:** positional **ENV:** ANSIBLE\_NAVIGATOR\_LINTABLES Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-42-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-42-2) ansible-lint: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-42-3) lintables:` [¶](https://docs.ansible.com/projects/navigator/settings/#_9 "Permanent link") ------------------------------------------------------------------------------- ### Subcommand: replay[¶](https://docs.ansible.com/projects/navigator/settings/#subcommand-replay "Permanent link") playbook-artifact-replay [¶](https://docs.ansible.com/projects/navigator/settings/#playbook-artifact-replay) Specify the path for the playbook artifact to replay **Added in version:** v1.0 **Default:** No default value set **CLI:** positional **ENV:** ANSIBLE\_NAVIGATOR\_PLAYBOOK\_ARTIFACT\_REPLAY Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-43-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-43-2) playbook-artifact: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-43-3) replay:` [¶](https://docs.ansible.com/projects/navigator/settings/#_10 "Permanent link") -------------------------------------------------------------------------------- ### Subcommand: run[¶](https://docs.ansible.com/projects/navigator/settings/#subcommand-run "Permanent link") enable-prompts [¶](https://docs.ansible.com/projects/navigator/settings/#enable-prompts) Enable prompts for password and in playbooks. This will set mode to stdout and disable playbook artifact creation **Added in version:** v2.3 **Choices:** 'True' or 'False' **Default:** False **CLI:** `--ep` or `--enable-prompts` **ENV:** ANSIBLE\_NAVIGATOR\_ENABLE\_PROMPTS Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-44-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-44-2) enable-prompts:` help-playbook [¶](https://docs.ansible.com/projects/navigator/settings/#help-playbook) Help options for ansible-playbook command in stdout mode **Added in version:** v1.0 **Choices:** 'True' or 'False' **Default:** False **CLI:** `--hp` or `--help-playbook` **ENV:** ANSIBLE\_NAVIGATOR\_HELP\_PLAYBOOK Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-45-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-45-2) ansible: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-45-3) playbook: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-45-4) help:` inventory [¶](https://docs.ansible.com/projects/navigator/settings/#inventory) Specify an inventory file path or comma separated host list **Added in version:** v1.0 **Default:** No default value set **CLI:** `-i` or `--inventory` **ENV:** ANSIBLE\_INVENTORY Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-46-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-46-2) ansible: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-46-3) inventory: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-46-4) entries:` inventory-column [¶](https://docs.ansible.com/projects/navigator/settings/#inventory-column) Specify a host attribute to show in the inventory view **Added in version:** v1.0 **Default:** No default value set **CLI:** `--ic` or `--inventory-column` **ENV:** ANSIBLE\_NAVIGATOR\_INVENTORY\_COLUMNS Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-47-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-47-2) inventory-columns:` playbook [¶](https://docs.ansible.com/projects/navigator/settings/#playbook) Specify the playbook name **Added in version:** v1.0 **Default:** No default value set **CLI:** positional **ENV:** ANSIBLE\_NAVIGATOR\_PLAYBOOK Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-48-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-48-2) ansible: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-48-3) playbook: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-48-4) path:` playbook-artifact-enable [¶](https://docs.ansible.com/projects/navigator/settings/#playbook-artifact-enable) Enable or disable the creation of artifacts for completed playbooks. Note: not compatible with '--mode stdout' when playbooks require user input **Added in version:** v1.0 **Choices:** 'True' or 'False' **Default:** True **CLI:** `--pae` or `--playbook-artifact-enable` **ENV:** ANSIBLE\_NAVIGATOR\_PLAYBOOK\_ARTIFACT\_ENABLE Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-49-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-49-2) playbook-artifact: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-49-3) enable:` playbook-artifact-save-as [¶](https://docs.ansible.com/projects/navigator/settings/#playbook-artifact-save-as) Specify the name for artifacts created from completed playbooks. The following placeholders are available: {playbook\_dir}, {playbook\_name}, {playbook\_status}, and {time\_stamp} **Added in version:** v1.0 **Default:** {playbook\_dir}/{playbook\_name}-artifact-{time\_stamp}.json **CLI:** `--pas` or `--playbook-artifact-save-as` **ENV:** ANSIBLE\_NAVIGATOR\_PLAYBOOK\_ARTIFACT\_SAVE\_AS Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-50-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-50-2) playbook-artifact: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-50-3) save-as:` [¶](https://docs.ansible.com/projects/navigator/settings/#_11 "Permanent link") -------------------------------------------------------------------------------- ### Subcommand: settings[¶](https://docs.ansible.com/projects/navigator/settings/#subcommand-settings "Permanent link") settings-effective [¶](https://docs.ansible.com/projects/navigator/settings/#settings-effective) Show the effective settings. Defaults, CLI parameters, environment variables, and the settings file will be combined **Added in version:** v2.0 **Default:** False **CLI:** `--se` or `--effective` **ENV:** ANSIBLE\_NAVIGATOR\_SETTINGS\_EFFECTIVE Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-51-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-51-2) settings: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-51-3) effective:` settings-sample [¶](https://docs.ansible.com/projects/navigator/settings/#settings-sample) Generate a sample settings file **Added in version:** v2.0 **Default:** False **CLI:** `--gs` or `--sample` **ENV:** ANSIBLE\_NAVIGATOR\_SETTINGS\_SAMPLE Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-52-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-52-2) settings: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-52-3) sample:` settings-schema [¶](https://docs.ansible.com/projects/navigator/settings/#settings-schema) Generate a schema for the settings file ('json'= draft-07 JSON Schema) **Added in version:** v2.0 **Choices:** 'json' **Default:** json **CLI:** `--ss` or `--schema` **ENV:** ANSIBLE\_NAVIGATOR\_SETTINGS\_SCHEMA Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-53-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-53-2) settings: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-53-3) schema:` settings-sources [¶](https://docs.ansible.com/projects/navigator/settings/#settings-sources) Show the source of each current settings entry **Added in version:** v2.0 **Default:** False **CLI:** `--so` or `--sources` **ENV:** ANSIBLE\_NAVIGATOR\_SETTINGS\_SOURCES Settings `[](https://docs.ansible.com/projects/navigator/settings/#__codelineno-54-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-54-2) settings: [](https://docs.ansible.com/projects/navigator/settings/#__codelineno-54-3) sources:` --- # Introduction to Ansible Runner — Ansible Runner Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/runner/en/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Runner Documentation](https://docs.ansible.com/projects/runner/en/stable/) * [](https://docs.ansible.com/projects/runner/en/latest/) * Introduction to Ansible Runner * [View page source](https://docs.ansible.com/projects/runner/en/latest/_sources/intro.rst.txt) * * * Introduction to Ansible Runner[](https://docs.ansible.com/projects/runner/en/latest/intro/#introduction-to-ansible-runner "Link to this heading") =================================================================================================================================================== **Runner** is intended to be most useful as part of automation and tooling that needs to invoke Ansible and consume its results. Most of the parameterization of the **Ansible** command line is also available on the **Runner** command line but **Runner** also can rely on an input interface that is mapped onto a directory structure, an example of which can be seen in [the source tree](https://github.com/ansible/ansible-runner/tree/devel/demo) . Further sections in this document refer to the configuration and layout of that hierarchy. This isn’t the only way to interface with **Runner** itself. The Python module interface allows supplying these details as direct module parameters in many forms, and the command line interface allows supplying them directly as arguments, mimicking the behavior of `ansible-playbook`. Having the directory structure **does** allow gathering the inputs from elsewhere and preparing them for consumption by **Runner**, then the tooling can come along and inspect the results after the run. This is best seen in the way Ansible **AWX** uses **Runner** where most of the content comes from the database (and other content-management components) but ultimately needs to be brought together in a single place when launching the **Ansible** task. Runner Input Directory Hierarchy[](https://docs.ansible.com/projects/runner/en/latest/intro/#runner-input-directory-hierarchy "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------- This directory contains all necessary inputs. Here’s a view of the [demo directory](https://github.com/ansible/ansible-runner/tree/devel/demo) showing an active configuration. Note that not everything is required. Defaults will be used or values will be omitted if they are not provided. . ├── env │   ├── envvars │   ├── extravars │   ├── passwords │   ├── cmdline │   ├── settings │   └── ssh\_key ├── inventory │   └── hosts └── project    ├── test.yml └── roles └── testrole ├── defaults ├── handlers ├── meta ├── README.md ├── tasks ├── tests └── vars The `env` directory[](https://docs.ansible.com/projects/runner/en/latest/intro/#the-env-directory "Link to this heading") --------------------------------------------------------------------------------------------------------------------------- The **env** directory contains settings and sensitive files that inform certain aspects of the invocation of the **Ansible** process, an example of which can be found in [the demo env directory](https://github.com/ansible/ansible-runner/tree/devel/demo/env) . Each of these files can also be represented by a named pipe providing a bit of an extra layer of security. The formatting and expectation of these files differs slightly depending on what they are representing. `env/envvars`[](https://docs.ansible.com/projects/runner/en/latest/intro/#env-envvars "Link to this heading") --------------------------------------------------------------------------------------------------------------- Note For an example see [the demo envvars](https://github.com/ansible/ansible-runner/blob/devel/demo/env/envvars) . **Ansible Runner** will inherit the environment of the launching shell. This file (which can be in json or yaml format) represents the environment variables that will be added to the environment at run-time: \--- TESTVAR: exampleval `env/extravars`[](https://docs.ansible.com/projects/runner/en/latest/intro/#env-extravars "Link to this heading") ------------------------------------------------------------------------------------------------------------------- Note For an example see [the demo extravars](https://github.com/ansible/ansible-runner/blob/devel/demo/env/extravars) . **Ansible Runner** gathers the extra vars provided here and supplies them to the **Ansible Process** itself. This file can be in either json or yaml format: \--- ansible\_connection: local test: val `env/passwords`[](https://docs.ansible.com/projects/runner/en/latest/intro/#env-passwords "Link to this heading") ------------------------------------------------------------------------------------------------------------------- Note For an example see [the demo passwords](https://github.com/ansible/ansible-runner/blob/devel/demo/env/passwords) . Warning We expect this interface to change/simplify in the future but will guarantee backwards compatibility. The goal is for the user of **Runner** to not have to worry about the format of certain prompts emitted from **Ansible** itself. In particular, vault passwords need to become more flexible. **Ansible** itself is set up to emit passwords to certain prompts, these prompts can be requested (`-k` for example to prompt for the connection password). Likewise, prompts can be emitted via [vars\_prompt](https://docs.ansible.com/projects/ansible/latest/user_guide/playbooks_prompts.html) and also [Ansible Vault](https://docs.ansible.com/projects/ansible/latest/index.html#vault-ids-and-multiple-vault-passwords) . In order for **Runner** to respond with the correct password, it needs to be able to match the prompt and provide the correct password. This is currently supported by providing a yaml or json formatted file with a regular expression and a value to emit, for example: \--- "^SSH password:\\\\s\*?$": "some\_password" "^BECOME password.\*:\\\\s\*?$": "become\_password" `env/cmdline`[](https://docs.ansible.com/projects/runner/en/latest/intro/#env-cmdline "Link to this heading") --------------------------------------------------------------------------------------------------------------- Warning Current **Ansible Runner** does not validate the command line arguments passed using this method so it is up to the playbook writer to provide a valid set of options. The command line options provided by this method are lower priority than the ones set by **Ansible Runner**. For instance, this will not override `inventory` or `limit` values. **Ansible Runner** gathers command line options provided here as a string and supplies them to the **Ansible Process** itself. This file should contain the arguments to be added, for example: \--tags one,two \--skip\-tags three \-u ansible \--become `env/ssh_key`[](https://docs.ansible.com/projects/runner/en/latest/intro/#env-ssh-key "Link to this heading") --------------------------------------------------------------------------------------------------------------- Note Currently only a single ssh key can be provided via this mechanism but this is set to [change soon](https://github.com/ansible/ansible-runner/issues/51) . This file should contain the ssh private key used to connect to the host(s). **Runner** detects when a private key is provided and will wrap the call to **Ansible** in ssh-agent. `env/settings` - Settings for Runner itself[](https://docs.ansible.com/projects/runner/en/latest/intro/#env-settings-settings-for-runner-itself "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The **settings** file is a little different than the other files provided in this section in that its contents are meant to control **Runner** directly. * `idle_timeout`: `600` If no output is detected from ansible in this number of seconds the execution will be terminated. * `job_timeout`: `3600` The maximum amount of time to allow the job to run for, exceeding this and the execution will be terminated. * `pexpect_timeout`: `10` Number of seconds for the internal pexpect command to wait to block on input before continuing * `pexpect_use_poll`: `True` Use `poll()` function for communication with child processes instead of `select()`. `select()` is used when the value is set to `False`. `select()` has a known limitation of using only up to 1024 file descriptors. * `suppress_output_file`: `False` Allow output from ansible to not be streamed to the `stdout` or `stderr` files inside of the artifacts directory. * `suppress_ansible_output`: `False` Allow output from ansible to not be printed to the screen. * `fact_cache`: `'fact_cache'` The directory relative to `artifacts` where `jsonfile` fact caching will be stored. Defaults to `fact_cache`. This is ignored if `fact_cache_type` is different than `jsonfile`. * `fact_cache_type`: `'jsonfile'` The type of fact cache to use. Defaults to `jsonfile`. ### Process Isolation Settings for Runner[](https://docs.ansible.com/projects/runner/en/latest/intro/#process-isolation-settings-for-runner "Link to this heading") The process isolation settings are meant to control the process isolation feature of **Runner**. * `process_isolation`: `False` Enable limiting what directories on the filesystem the playbook run has access to. * `process_isolation_executable`: `bwrap` Path to the executable that will be used to provide filesystem isolation. * `process_isolation_path`: `/tmp` Path that an isolated playbook run will use for staging. * `process_isolation_hide_paths`: `None` Path or list of paths on the system that should be hidden from the playbook run. * `process_isolation_show_paths`: `None` Path or list of paths on the system that should be exposed to the playbook run. * `process_isolation_ro_paths`: `None` Path or list of paths on the system that should be exposed to the playbook run as read-only. These settings instruct **Runner** to execute **Ansible** tasks inside a container environment. For information about building execution environments, see [ansible-builder](https://docs.ansible.com/projects/builder/en/latest/) . To execute **Runner** with an execution environment: `ansible-runner run --container-image my-execution-environment:latest --process-isolation -p playbook.yml .` See `ansible-runner -h` for other container-related options. Inventory[](https://docs.ansible.com/projects/runner/en/latest/intro/#inventory "Link to this heading") --------------------------------------------------------------------------------------------------------- The **Runner** `inventory` location under the private data dir has the same expectations as inventory provided directly to ansible itself. It can be either a single file or script or a directory containing static inventory files or scripts. This inventory is automatically loaded and provided to **Ansible** when invoked and can be further overridden on the command line or via the `ANSIBLE_INVENTORY` environment variable to specify the hosts directly. Giving an absolute path for the inventory location is best practice, because relative paths are interpreted relative to the `current working directory` which defaults to the `project` directory. Project[](https://docs.ansible.com/projects/runner/en/latest/intro/#project "Link to this heading") ----------------------------------------------------------------------------------------------------- The **Runner** `project` directory is the playbook root containing playbooks and roles that those playbooks can consume directly. This is also the directory that will be set as the `current working directory` when launching the **Ansible** process. Modules[](https://docs.ansible.com/projects/runner/en/latest/intro/#modules "Link to this heading") ----------------------------------------------------------------------------------------------------- **Runner** has the ability to execute modules directly using Ansible ad-hoc mode. Roles[](https://docs.ansible.com/projects/runner/en/latest/intro/#roles "Link to this heading") ------------------------------------------------------------------------------------------------- **Runner** has the ability to execute [Roles](https://docs.ansible.com/projects/ansible/latest/user_guide/playbooks_reuse_roles.html) directly without first needing a playbook to reference them. This directory holds roles used for that. Behind the scenes, **Runner** will generate a playbook and invoke the `Role`. Runner Artifacts Directory Hierarchy[](https://docs.ansible.com/projects/runner/en/latest/intro/#runner-artifacts-directory-hierarchy "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------- This directory will contain the results of **Runner** invocation grouped under an `identifier` directory. This identifier can be supplied to **Runner** directly and if not given, an identifier will be generated as a [UUID](https://docs.python.org/3/library/uuid.html#uuid.uuid4) . This is how the directory structure looks from the top level: . ├── artifacts │   └── identifier ├── env ├── inventory ├── profiling\_data ├── project └── roles The artifact directory itself contains a particular structure that provides a lot of extra detail from a running or previously-run invocation of Ansible/Runner: . ├── artifacts │   └── 37f639a3-1f4f-4acb-abee-ea1898013a25 │   ├── fact\_cache │   │   └── localhost │   ├── job\_events │   │   ├── 1-34437b34-addd-45ae-819a-4d8c9711e191.json │   │   ├── 2-8c164553-8573-b1e0-76e1-000000000006.json │   │   ├── 3-8c164553-8573-b1e0-76e1-00000000000d.json │   │   ├── 4-f16be0cd-99e1-4568-a599-546ab80b2799.json │   │   ├── 5-8c164553-8573-b1e0-76e1-000000000008.json │   │   ├── 6-981fd563-ec25-45cb-84f6-e9dc4e6449cb.json │   │   └── 7-01c7090a-e202-4fb4-9ac7-079965729c86.json │   ├── rc │   ├── status │   └── stdout The **rc** file contains the actual return code from the **Ansible** process. The **status** file contains one of three statuses suitable for displaying: * success: The **Ansible** process finished successfully * failed: The **Ansible** process failed * timeout: The **Runner** timeout (see [env/settings - Settings for Runner itself](https://docs.ansible.com/projects/runner/en/latest/intro/#runnersettings) ) The **stdout** file contains the actual stdout as it appears at that moment. Runner Artifact Job Events (Host and Playbook Events)[](https://docs.ansible.com/projects/runner/en/latest/intro/#runner-artifact-job-events-host-and-playbook-events "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- **Runner** gathers the individual task and playbook events that are emitted as part of the **Ansible** run. This is extremely helpful if you don’t want to process or read the stdout returned from **Ansible** as it contains much more detail and status than just the plain stdout. It does some of the heavy lifting of assigning order to the events and stores them in json format under the `job_events` artifact directory. It also takes it a step further than normal **Ansible** callback plugins in that it will store the `stdout` associated with the event alongside the raw event data (along with stdout line numbers). It also generates dummy events for stdout that didn’t have corresponding host event data: { "uuid": "8c164553-8573-b1e0-76e1-000000000008", "parent\_uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "counter": 5, "stdout": "\\r\\nTASK \[debug\] \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*", "start\_line": 5, "end\_line": 7, "event": "playbook\_on\_task\_start", "event\_data": { "playbook": "test.yml", "playbook\_uuid": "34437b34-addd-45ae-819a-4d8c9711e191", "play": "all", "play\_uuid": "8c164553-8573-b1e0-76e1-000000000006", "play\_pattern": "all", "task": "debug", "task\_uuid": "8c164553-8573-b1e0-76e1-000000000008", "task\_action": "debug", "task\_path": "\\/home\\/mjones\\/ansible\\/ansible-runner\\/demo\\/project\\/test.yml:3", "task\_args": "msg=Test!", "name": "debug", "is\_conditional": false, "pid": 10640 }, "pid": 10640, "created": "2018-06-07T14:54:58.410605" } If the playbook runs to completion without getting killed, the last event will always be the `stats` event: { "uuid": "01c7090a-e202-4fb4-9ac7-079965729c86", "counter": 7, "stdout": "\\r\\nPLAY RECAP \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\\r\\n\\u001b\[0;32mlocalhost,\\u001b\[0m : \\u001b\[0;32mok=2 \\u001b\[0m changed=0 unreachable=0 failed=0 \\r\\n",\ "start\_line": 10,\ "end\_line": 14,\ "event": "playbook\_on\_stats",\ "event\_data": {\ "playbook": "test.yml",\ "playbook\_uuid": "34437b34-addd-45ae-819a-4d8c9711e191",\ "changed": {\ \ },\ "dark": {\ \ },\ "failures": {\ \ },\ "ok": {\ "localhost,": 2\ },\ "processed": {\ "localhost,": 1\ },\ "skipped": {\ \ },\ "artifact\_data": {\ \ },\ "pid": 10640\ },\ "pid": 10640,\ "created": "2018-06-07T14:54:58.424603"\ }\ \ Note\ \ The **Runner module interface** presents a programmatic interface to these events that allow getting the final status and performing host filtering of task events.\ \ Runner Profiling Data Directory[](https://docs.ansible.com/projects/runner/en/latest/intro/#runner-profiling-data-directory "Link to this heading")\ \ -----------------------------------------------------------------------------------------------------------------------------------------------------\ \ If resource profiling is enabled for **Runner** the `profiling_data` directory will be populated with a set of files containing the profiling data:\ \ .\ ├── profiling\_data\ │   ├── 0-34437b34-addd-45ae-819a-4d8c9711e191-cpu.json\ │   ├── 0-34437b34-addd-45ae-819a-4d8c9711e191-memory.json\ │   ├── 0-34437b34-addd-45ae-819a-4d8c9711e191-pids.json\ │   ├── 1-8c164553-8573-b1e0-76e1-000000000006-cpu.json\ │   ├── 1-8c164553-8573-b1e0-76e1-000000000006-memory.json\ │   └── 1-8c164553-8573-b1e0-76e1-000000000006-pids.json\ \ Each file is in [JSON text format](https://tools.ietf.org/html/rfc7464#section-2.2)\ . Each line of the file will begin with a record separator (RS), continue with a JSON dictionary, and conclude with a line feed (LF) character. The following provides an example of what the resource files may look like. Note that that since the RS and LF are control characters, they are not actually printed below:\ \ \==> 0\-525400c9\-c704\-29a6\-4107\-00000000000c\-cpu.json <==\ {"timestamp": 1568977988.6844425, "task\_name": "Gathering Facts", "task\_uuid": "525400c9-c704-29a6-4107-00000000000c", "value": 97.12799768097156}\ {"timestamp": 1568977988.9394386, "task\_name": "Gathering Facts", "task\_uuid": "525400c9-c704-29a6-4107-00000000000c", "value": 94.17538298892688}\ {"timestamp": 1568977989.1901696, "task\_name": "Gathering Facts", "task\_uuid": "525400c9-c704-29a6-4107-00000000000c", "value": 64.38272588006255}\ {"timestamp": 1568977989.4594045, "task\_name": "Gathering Facts", "task\_uuid": "525400c9-c704-29a6-4107-00000000000c", "value": 83.77387744259856}\ \ \==> 0\-525400c9\-c704\-29a6\-4107\-00000000000c\-memory.json <==\ {"timestamp": 1568977988.4281094, "task\_name": "Gathering Facts", "task\_uuid": "525400c9-c704-29a6-4107-00000000000c", "value": 36.21484375}\ {"timestamp": 1568977988.6842303, "task\_name": "Gathering Facts", "task\_uuid": "525400c9-c704-29a6-4107-00000000000c", "value": 57.87109375}\ {"timestamp": 1568977988.939303, "task\_name": "Gathering Facts", "task\_uuid": "525400c9-c704-29a6-4107-00000000000c", "value": 66.60546875}\ {"timestamp": 1568977989.1900482, "task\_name": "Gathering Facts", "task\_uuid": "525400c9-c704-29a6-4107-00000000000c", "value": 71.4609375}\ {"timestamp": 1568977989.4592078, "task\_name": "Gathering Facts", "task\_uuid": "525400c9-c704-29a6-4107-00000000000c", "value": 38.25390625}\ \ \==> 0\-525400c9\-c704\-29a6\-4107\-00000000000c\-pids.json <==\ {"timestamp": 1568977988.4284189, "task\_name": "Gathering Facts", "task\_uuid": "525400c9-c704-29a6-4107-00000000000c", "value": 5}\ {"timestamp": 1568977988.6845856, "task\_name": "Gathering Facts", "task\_uuid": "525400c9-c704-29a6-4107-00000000000c", "value": 6}\ {"timestamp": 1568977988.939547, "task\_name": "Gathering Facts", "task\_uuid": "525400c9-c704-29a6-4107-00000000000c", "value": 8}\ {"timestamp": 1568977989.1902773, "task\_name": "Gathering Facts", "task\_uuid": "525400c9-c704-29a6-4107-00000000000c", "value": 13}\ {"timestamp": 1568977989.4593227, "task\_name": "Gathering Facts", "task\_uuid": "525400c9-c704-29a6-4107-00000000000c", "value": 6}\ \ * Resource profiling data is grouped by playbook task.\ \ * For each task, there will be three files, corresponding to cpu, memory and pid count data.\ \ * Each file contains a set of data points collected over the course of a playbook task.\ \ * If a task executes quickly and the polling rate for a given metric is large enough, it is possible that no profiling data may be collected during the task’s execution. If this is the case, no data file will be created. --- # User Guide - Ansible Development Tools Documentation [Skip to content](https://docs.ansible.com/projects/dev-tools/user-guide/#user-guide) [](https://github.com/ansible/ansible-dev-tools/blob/main/docs/user-guide/index.md "Edit this page") [](https://github.com/ansible/ansible-dev-tools/raw/main/docs/user-guide/index.md "View source of this page") User Guide[¶](https://docs.ansible.com/projects/dev-tools/user-guide/#user-guide "Permanent link") =================================================================================================== This guide aims to help the user to perform common operations like testing collections, roles within a collection using two or more tools within ansible dev tools ecosystem. [Ansible Ecosystem](https://docs.ansible.com/ecosystem.html) is a collection of projects or tools which lets you expand automation to varying set of use cases. * [Building a Collection](https://docs.ansible.com/projects/dev-tools/user-guide/building-collection/) * [Testing a role within a collection](https://docs.ansible.com/projects/dev-tools/user-guide/testing/) * [Ensure content best practices](https://docs.ansible.com/projects/dev-tools/user-guide/content-best-practices/) * [Content CI GitHub action setup](https://docs.ansible.com/projects/dev-tools/user-guide/ci-setup/) * [Content Release GitHub action setup](https://docs.ansible.com/projects/dev-tools/user-guide/content-release/) Back to top --- # noxfile reference - antsibull-nox – Antsibull Nox Helper [Skip to content](https://docs.ansible.com/projects/antsibull-nox/reference/#noxfile-reference) noxfile Reference[¶](https://docs.ansible.com/projects/antsibull-nox/reference/#noxfile-reference "Permanent link") ==================================================================================================================== This document assumes some basic familiarity with Nox and `noxfile.py` files. If you want more information on these, take a look at the following resources: * [Nox tutorial](https://nox.thea.codes/en/stable/tutorial.html) ; * [Nox configuration and API](https://nox.thea.codes/en/stable/config.html) . You might also want to read [Getting Started](https://docs.ansible.com/projects/antsibull-nox/getting-started/) first if you haven't already done so. Basic noxfile structure[¶](https://docs.ansible.com/projects/antsibull-nox/reference/#basic-noxfile-structure "Permanent link") -------------------------------------------------------------------------------------------------------------------------------- A basic `noxfile.py` using antsibull-nox looks as follows: ``[](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-0-1) # The following metadata allows Python runners and nox to install the required [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-0-2) # dependencies for running this Python script: [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-0-3) # [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-0-4) # /// script [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-0-5) # dependencies = ["nox>=2025.02.09", "antsibull-nox"] [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-0-6) # /// [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-0-7) [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-0-8) import sys [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-0-9) [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-0-10) import nox [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-0-11) [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-0-12) [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-0-13) # We try to import antsibull-nox, and if that doesn't work, provide a more useful [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-0-14) # error message to the user. [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-0-15) try: [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-0-16) import antsibull_nox [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-0-17) except ImportError: [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-0-18) print("You need to install antsibull-nox in the same Python environment as nox.") [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-0-19) sys.exit(1) [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-0-20) [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-0-21) [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-0-22) antsibull_nox.load_antsibull_nox_toml() [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-0-23) [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-0-24) [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-0-25) ... here you can call antsibull_nox functions to define additional sessions ... [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-0-26) [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-0-27) [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-0-28) # Allow to run the noxfile with `python noxfile.py`, `pipx run noxfile.py`, or similar. [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-0-29) # Requires nox >= 2025.02.09 [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-0-30) if __name__ == "__main__": [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-0-31) nox.main()`` Loading the `antsibull-nox.toml` configuration[¶](https://docs.ansible.com/projects/antsibull-nox/reference/#loading-the-antsibull-noxtoml-configuration "Permanent link") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You should always add the `antsibull_nox.load_antsibull_nox_toml()` function call as shown in the example above. It loads the `antsibull-nox.toml` configuration file, loads its configuration options, and adds all sessions configured in there. Adding own tests that need to import from the collection structure[¶](https://docs.ansible.com/projects/antsibull-nox/reference/#adding-own-tests-that-need-to-import-from-the-collection-structure "Permanent link") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Some collections need additional, specific tests for collection-specific properties. These can usually be added as regular Nox sessions by defining a function and decorating it with `@nox.session()`. In some cases, though, these tests need to be able to import code from the collection, or need to be able to run `ansible-doc` or other tools on the collection that expect the collection to be part of an `ansible_collections` tree structure. For this, antsibull-nox provides a powerful helper function `antsibull_nox.sessions.prepare_collections()` which prepares an `ansible_collections` tree structure in the session's temporary directory. The tree structure can optionally also be part of `site-packages`, to make it importable in Python code. The function `antsibull_nox.sessions.prepare_collections()` accepts the following parameters: * `session: nox.Session` (positional argument, **required**): The Nox session object. * `install_in_site_packages: bool` (keyword argument, **required**): Whether to install the `ansible_collections` tree in `site-packages`. If set to `True`, Python code can import code from the collections. If set to `False`, Python code can **not** import code. * `install_out_of_tree: bool` (keyword argument, default `False`): Whether to install the `ansible_collections` tree in `$TEMP` instead of the nox session directory. Setting this to `True` is not allowed if `install_in_site_packages=True`. This is necessary when running tools like `ansible-doc` against the tree that do not accept nested `ansible_collections` directory structures, where `ansible_collections` is found below `ansible_collections//` for a collection `.`. * `extra_deps_files: list[str | os.PathLike] | None` (default `None`): Paths to [collection requirements files](https://docs.ansible.com/ansible/devel/collections_guide/collections_installing.html#install-multiple-collections-with-a-requirements-file) whose collections should be copied into the tree structure. * `extra_collections: list[str] | None` (default `None`): An explicit list of collections (form `.`) that should be copied into the tree structure. * `copy_repo_structure: bool` (default `False`): Copy the repository structure (if detected) of the current collection. This requires that the collection's root directory is the repository's root. The function returns `antsibull_nox.sessions.CollectionSetup | None`. If the return value is `None`, the `ansible_collections` tree was not created for some reason. Otherwise, an `antsibull_nox.sessions.CollectionSetup` object is returned, which has the following properties: * `collections_root: Path`: The path of the `ansible_collections` directory where all dependent collections are installed. Is currently identical to `current_root`, but that might change or depend on options in the future. * `current_place: Path`: The directory in which the `ansible_collections` directory can be found, as well as in which `ansible_collections//` points to a copy of the current collection. * `current_root: Path`: The path of the ansible\_collections directory that contains the current collection. The following is always true: `[](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-1-1) current_root == current_place / "ansible_collections"` * `current_collection: antsibull_nox.collection.CollectionData`: Data on the current collection (as in the repository). The object contains the following properties: * `collections_root_path: Path | None`: Identical to `current_root` above. * `path: Path`: The path where the collection repository is. * `namespace: str`: The collection's namespace, as found in `galaxy.yml`. * `name: str`: The collection's name, as found in `galaxy.yml`. * `full_name: str`: The collection's full name. The following is always true: `[](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-2-1) full_name = namespace + "." + name` * `version: str | None`: The collection's version, as found in `galaxy.yml`. If not present in `galaxy.yml`, will be `None`. * `dependencies: dict[str, str]`: The collection's dependencies, as found in `galaxy.yml`. * `current: bool`: Always `true`. * `current_path: Path`: The path of the current collection inside the collection tree below `current_root`. The following is always true: `[](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-3-1) current_path == current_root / current_collection.namespace / current_collection.name` ### Example code[¶](https://docs.ansible.com/projects/antsibull-nox/reference/#example-code "Permanent link") This example is from `community.dns`. The `update-docs-fragments.py` script updates some docs fragments with information from module utils to ensure that both data sources are in sync. To be able to do this, the script needs to import the module utils. Because of that, we set `install_in_site_packages=True`. `[](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-4-1) import os [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-4-2) [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-4-3) # Put this in the try/except at the top of the noxfile.py: [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-4-4) import antsibull_nox.sessions [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-4-5) [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-4-6) [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-4-7) # Whether the noxfile is running in CI: [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-4-8) # https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#default-environment-variables [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-4-9) # https://docs.gitlab.com/ci/variables/predefined_variables/#predefined-variables [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-4-10) # https://docs.travis-ci.com/user/environment-variables/#default-environment-variables [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-4-11) IN_CI = os.environ.get("CI") == "true" [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-4-12) [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-4-13) [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-4-14) @nox.session(name="update-docs-fragments") [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-4-15) def update_docs_fragments(session: nox.Session) -> None: [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-4-16) session.install(session, "ansible-core") [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-4-17) prepare = antsibull_nox.sessions.prepare_collections( [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-4-18) session, install_in_site_packages=True [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-4-19) ) [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-4-20) if not prepare: [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-4-21) return [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-4-22) data = ["python", "update-docs-fragments.py"] [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-4-23) if IN_CI: [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-4-24) data.append("--lint") [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-4-25) session.run(*data)` Run ansible-test[¶](https://docs.ansible.com/projects/antsibull-nox/reference/#run-ansible-test "Permanent link") ------------------------------------------------------------------------------------------------------------------ antsibull-nox provides several ways to run ansible-core's testing tool `ansible-test` directly from nox. It knows which Python versions every ansible-core release supports and picks an installed version of Python for every ansible-test session if possible, or picks the highest supported Python version for the ansible-core release is no installed Python is found. Most sessions can be directly added from the configuration file. See [the configuration file reference for more details](https://docs.ansible.com/projects/antsibull-nox/config-file/#run-ansible-test) . If you need to add more or very specific integration test sessions, you can use the low-level functions mentioned below. ### Adding an explicit ansible-test session[¶](https://docs.ansible.com/projects/antsibull-nox/reference/#adding-an-explicit-ansible-test-session "Permanent link") `antsibull_nox.add_ansible_test_session()` is a low-level function used by all other functions in this section to add a session running ansible-test. It assumes that the command run uses Docker isolation, and thus only needs one Python version - preferably one available locally - to run. It accepts the following parameters: * `name: str` (**required**): The name of the session. * `description: str | None` (**required**): The session's description. Will be shown when running `nox --list`. * `extra_deps_files: list[str | os.PathLike] | None` (default: `None`): Additional collection dependency files to read and ensure that these collections (and their dependencies) are present. For example, `["tests/integration/requirements.yml"]`. * `ansible_test_params: list[str]` (**required**): The parameters to pass to `ansible-test`. For example, `["integration", "--docker", "ubuntu2404", "-v", "--color"]`. * `add_posargs: bool` (default `True`): Whether to append positional arguments provided to `nox` to the `ansible-test` command. * `default: bool` (**required**): Whether the session should be made default. This means that when a user just runs `nox` without specifying sessions, this session will run. * `ansible_core_version: str | AnsibleCoreVersion` (**required**): The ansible-core version to install. Can be a version string like `"2.18"`, or one of the special identifiers `"devel"` and `"milestone"`. * `ansible_core_source: t.Literal["git", "pypi"]` (default `"git"`): The source where to install ansible-core from. For `"devel"` and `"milestone"`, always `git` will be used. * `ansible_core_repo_name: str | None` (default `None`): Allows to override the repository name when `ansible_core_source == "git"`. By default `"ansible/ansible"` or `"ansible-community/eol-ansible"` are used, depending on `ansible_core_version`. * `ansible_core_branch_name: str | None` (default `None`): Allows to override the branch name when `ansible_core_source == "git"`. * `handle_coverage: t.Literal["never", "always", "auto"]` (default: `"auto"`): Whether to run `ansible-test coverage xml` after running the `ansible-test` command. If set to `"auto"`, will check whether `--coverage` was passed to `ansible-test`. * `register_name: str | None` (default: `None`): Register session under this name. Should be one of `"sanity"`, `"units"`, and `"integration"`. It will then appear under that name for `antsibull_nox.add_matrix_generator()`. * `register_extra_data: dict[str, t.Any] | None` (default: `None`): Supply additional data when registering a session. Values that are used by the shared workflow are `display-name` (shown to the user) and `gha-container` (used for `runs-on`). * `register_tags: Sequence[str] | None` (default: `None`): A sequence of tags. Will be added to the register extra data as `tags`. This can be used to filter by tags in the matrix generation. * `callback_before: Callable[[], None] | None` (default `None`): Callback that will be run before `ansible-test` is run in the temporary directory. Can be used to set-up files like `tests/integration/integration_config.yml`. * `callback_after: Callable[[], None] | None` (default `None`): Callback that will be run after `ansible-test` is run in the temporary directory. * `support_cd: bool` (default `False`): Whether this ansible-test call supports [change detection](https://docs.ansible.com/projects/antsibull-nox/change-detection/) . In case change detection is enabled, `--changed --base-branch ` will be passed after `ansible_test_params`. Note that setting this to `True` will fail if the configuration file has not been loaded before calling `antsibull_nox.add_ansible_test_session()`. ### Example code[¶](https://docs.ansible.com/projects/antsibull-nox/reference/#example-code_1 "Permanent link") This adds a session called `ansible-test-integration-devel-ubuntu2404` that runs integration tests with ansible-core's development branch using its Ubuntu 24.04 container. `[](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-5-1) antsibull_nox.add_ansible_test_session( [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-5-2) name="ansible-test-integration-devel-ubuntu2404", [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-5-3) description="Run Ubuntu 24.04 integration tests with ansible-core devel", [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-5-4) extra_deps_files=["tests/integration/requirements.yml"], [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-5-5) ansible_test_params=["integration", "--docker", "ubuntu2404", "-v", "--color"], [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-5-6) default=False, [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-5-7) ansible_core_version="devel", [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-5-8) register_name="integration", [](https://docs.ansible.com/projects/antsibull-nox/reference/#__codelineno-5-9) )` --- # Using docker containers - Ansible Molecule [Skip to content](https://docs.ansible.com/projects/molecule/examples/docker/#using-docker-containers) [](https://github.com/ansible/molecule/blob/main/docs/examples/docker.md "Edit this page") [](https://github.com/ansible/molecule/raw/main/docs/examples/docker.md "View source of this page") Using docker containers[¶](https://docs.ansible.com/projects/molecule/examples/docker/#using-docker-containers "Permanent link") ================================================================================================================================= Note This example demonstrates the use of a pre-ansible-native configuration. For ansible-native examples see the [Using podman containers](https://docs.ansible.com/projects/molecule/examples/podman/) or [Ansible native inventory](https://docs.ansible.com/projects/molecule/examples/ansible_native_inventory/) examples. Below you can see a scenario that is using docker containers as test hosts. When you run `molecule test --scenario-name docker` the `create`, `converge` and `destroy` steps will be run one after another. This example is using Ansible playbooks and it does not need any molecule plugins to run. You can fully control which test requirements you need to be installed. Config playbook[¶](https://docs.ansible.com/projects/molecule/examples/docker/#config-playbook "Permanent link") ----------------------------------------------------------------------------------------------------------------- molecule.yml `[](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-0-1) dependency: [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-0-2) name: galaxy [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-0-3) options: [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-0-4) requirements-file: requirements.yml [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-0-5) platforms: [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-0-6) - name: molecule-ubuntu [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-0-7) image: ubuntu:18.04` requirements.yml `[](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-1-1) collections: [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-1-2) - name: community.docker [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-1-3) version: ">=3.10.4"` Create playbook[¶](https://docs.ansible.com/projects/molecule/examples/docker/#create-playbook "Permanent link") ----------------------------------------------------------------------------------------------------------------- create.yml `[](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-1) - name: Create [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-2) hosts: localhost [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-3) gather_facts: false [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-4) vars: [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-5) molecule_inventory: [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-6) all: [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-7) hosts: {} [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-8) molecule: {} [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-9) tasks: [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-10) - name: Create a container [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-11) community.docker.docker_container: [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-12) name: "{{ item.name }}" [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-13) image: "{{ item.image }}" [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-14) state: started [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-15) command: sleep 1d [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-16) log_driver: json-file [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-17) register: result [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-18) loop: "{{ molecule_yml.platforms }}" [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-19) [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-20) - name: Print some info [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-21) ansible.builtin.debug: [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-22) msg: "{{ result.results }}" [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-23) [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-24) - name: Fail if container is not running [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-25) when: > [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-26) item.container.State.ExitCode != 0 or [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-27) not item.container.State.Running [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-28) ansible.builtin.include_tasks: [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-29) file: tasks/create-fail.yml [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-30) loop: "{{ result.results }}" [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-31) loop_control: [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-32) label: "{{ item.container.Name }}" [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-33) [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-34) - name: Add container to molecule_inventory [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-35) vars: [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-36) inventory_partial_yaml: | [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-37) all: [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-38) children: [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-39) molecule: [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-40) hosts: [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-41) "{{ item.name }}": [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-42) ansible_connection: community.docker.docker [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-43) ansible.builtin.set_fact: [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-44) molecule_inventory: > [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-45) {{ molecule_inventory | combine(inventory_partial_yaml | from_yaml, recursive=true) }} [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-46) loop: "{{ molecule_yml.platforms }}" [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-47) loop_control: [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-48) label: "{{ item.name }}" [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-49) [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-50) - name: Dump molecule_inventory [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-51) ansible.builtin.copy: [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-52) content: | [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-53) {{ molecule_inventory | to_yaml }} [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-54) dest: "{{ molecule_ephemeral_directory }}/inventory/molecule_inventory.yml" [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-55) mode: "0600" [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-56) [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-57) - name: Force inventory refresh [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-58) ansible.builtin.meta: refresh_inventory [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-59) [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-60) - name: Fail if molecule group is missing [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-61) ansible.builtin.assert: [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-62) that: "'molecule' in groups" [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-63) fail_msg: | [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-64) molecule group was not found inside inventory groups: {{ groups }} [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-65) run_once: true # noqa: run-once[task] [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-66) [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-67) # we want to avoid errors like "Failed to create temporary directory" [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-68) - name: Validate that inventory was refreshed [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-69) hosts: molecule [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-70) gather_facts: false [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-71) tasks: [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-72) - name: Check uname [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-73) ansible.builtin.raw: uname -a [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-74) register: result [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-75) changed_when: false [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-76) [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-77) - name: Display uname info [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-78) ansible.builtin.debug: [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-2-79) msg: "{{ result.stdout }}"` tasks/create-fail.yml `[](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-3-1) - name: Retrieve container log [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-3-2) ansible.builtin.command: [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-3-3) cmd: >- [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-3-4) {% raw %} [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-3-5) docker logs [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-3-6) {% endraw %} [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-3-7) {{ item.stdout_lines[0] }} [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-3-8) changed_when: false [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-3-9) register: logfile_cmd [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-3-10) [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-3-11) - name: Display container log [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-3-12) ansible.builtin.fail: [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-3-13) msg: "{{ logfile_cmd.stderr }}"` Converge playbook[¶](https://docs.ansible.com/projects/molecule/examples/docker/#converge-playbook "Permanent link") --------------------------------------------------------------------------------------------------------------------- converge.yml `[](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-4-1) - name: Fail if molecule group is missing [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-4-2) hosts: localhost [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-4-3) tasks: [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-4-4) - name: Print some info [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-4-5) ansible.builtin.debug: [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-4-6) msg: "{{ groups }}" [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-4-7) [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-4-8) - name: Assert group existence [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-4-9) ansible.builtin.assert: [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-4-10) that: "'molecule' in groups" [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-4-11) fail_msg: | [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-4-12) molecule group was not found inside inventory groups: {{ groups }} [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-4-13) [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-4-14) - name: Converge [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-4-15) hosts: molecule [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-4-16) # We disable gather facts because it would fail due to our container not [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-4-17) # having python installed. This will not prevent use from running 'raw' [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-4-18) # commands. Most molecule users are expected to use containers that already [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-4-19) # have python installed in order to avoid notable delays installing it. [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-4-20) gather_facts: false [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-4-21) tasks: [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-4-22) - name: Check uname [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-4-23) ansible.builtin.raw: uname -a [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-4-24) register: result [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-4-25) changed_when: false [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-4-26) [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-4-27) - name: Print some info [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-4-28) ansible.builtin.assert: [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-4-29) that: result.stdout is ansible.builtin.search("^Linux")` Destroy playbook[¶](https://docs.ansible.com/projects/molecule/examples/docker/#destroy-playbook "Permanent link") ------------------------------------------------------------------------------------------------------------------- destroy.yml `[](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-5-1) - name: Destroy molecule containers [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-5-2) hosts: molecule [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-5-3) gather_facts: false [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-5-4) tasks: [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-5-5) - name: Stop and remove container [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-5-6) delegate_to: localhost [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-5-7) community.docker.docker_container: [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-5-8) name: "{{ inventory_hostname }}" [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-5-9) state: absent [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-5-10) auto_remove: true [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-5-11) [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-5-12) - name: Remove dynamic molecule inventory [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-5-13) hosts: localhost [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-5-14) gather_facts: false [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-5-15) tasks: [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-5-16) - name: Remove dynamic inventory file [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-5-17) ansible.builtin.file: [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-5-18) path: "{{ molecule_ephemeral_directory }}/inventory/molecule_inventory.yml" [](https://docs.ansible.com/projects/molecule/examples/docker/#__codelineno-5-19) state: absent` Back to top --- # Frequently asked questions - Ansible Navigator Documentation [Skip to content](https://docs.ansible.com/projects/navigator/faq/#execution-environments) [](https://github.com/ansible/ansible-navigator/blob/main/docs/faq.md "Edit this page") Frequently asked questions[¶](https://docs.ansible.com/projects/navigator/faq/#frequently-asked-questions "Permanent link") ============================================================================================================================ * [Execution environments](https://docs.ansible.com/projects/navigator/faq/#execution-environments) * [What is an execution environment?](https://docs.ansible.com/projects/navigator/faq/#what-is-an-execution-environment) * [The ansible.cfg file](https://docs.ansible.com/projects/navigator/faq/#the-ansiblecfg-file) * [Where should the ansible.cfg file go when using an execution environment?](https://docs.ansible.com/projects/navigator/faq/#where-should-the-ansiblecfg-file-go-when-using-an-execution-environment) * [Where should the ansible.cfg file go when not using an execution environment?](https://docs.ansible.com/projects/navigator/faq/#where-should-the-ansiblecfg-file-go-when-not-using-an-execution-environment) * [Placement of ansible collections](https://docs.ansible.com/projects/navigator/faq/#placement-of-ansible-collections) * [Where should ansible collections be placed when using an execution environment?](https://docs.ansible.com/projects/navigator/faq/#where-should-ansible-collections-be-placed-when-using-an-execution-environment) * [Where should ansible collections be placed when not using an execution environment?](https://docs.ansible.com/projects/navigator/faq/#where-should-ansible-collections-be-placed-when-not-using-an-execution-environment) * [ansible-navigator settings](https://docs.ansible.com/projects/navigator/faq/#ansible-navigator-settings) * [What is the order in which configuration settings are applied?](https://docs.ansible.com/projects/navigator/faq/#what-is-the-order-in-which-configuration-settings-are-applied) * [Why does ansible-navigator change the terminal colors or look terrible?](https://docs.ansible.com/projects/navigator/faq/#why-does-ansible-navigator-change-the-terminal-colors-or-look-terrible) * [How can I change the colors used by ansible-navigator](https://docs.ansible.com/projects/navigator/faq/#how-can-i-change-the-colors-used-by-ansible-navigator) * [What's with all these site-artifact-2021-06-02T16:02:33.911259+00:00.json files in the playbook directory?](https://docs.ansible.com/projects/navigator/faq/#whats-with-all-these-site-artifact-2021-06-02t1602339112590000json-files-in-the-playbook-directory) * [Why does vi open when I use :open?](https://docs.ansible.com/projects/navigator/faq/#why-does-vi-open-when-i-use-open) * [How do I define volume mounts using an environment variable?](https://docs.ansible.com/projects/navigator/faq/#how-do-i-define-volume-mounts-using-an-environment-variable) * [How can tls-verify be disabled when an execution environment image is being pulled?](https://docs.ansible.com/projects/navigator/faq/#how-can-tls-verify-be-disabled-when-an-execution-environment-image-is-being-pulled) * [SSH keys](https://docs.ansible.com/projects/navigator/faq/#ssh-keys) * [How do I use my SSH keys with an execution environment?](https://docs.ansible.com/projects/navigator/faq/#how-do-i-use-my-ssh-keys-with-an-execution-environment) * [Compatibility with ansible-\* utilities](https://docs.ansible.com/projects/navigator/faq/#compatibility-with-ansible-utilities) * [Why does the playbook hang when vars\_prompt, pause/prompt or --ask-pass is used?](https://docs.ansible.com/projects/navigator/faq/#why-does-the-playbook-hang-when-vars_prompt-pauseprompt-or-ask-pass-is-used) * [How can I use ansible-test without having it locally installed?](https://docs.ansible.com/projects/navigator/faq/#how-can-i-use-ansible-test-without-having-it-locally-installed) * [How do I use ansible-playbook parameters like --forks 15?](https://docs.ansible.com/projects/navigator/faq/#how-do-i-use-ansible-playbook-parameters-like-forks-15) * [How can I use syntax-check with ansible-navigator?](https://docs.ansible.com/projects/navigator/faq/#how-can-i-use-syntax-check-with-ansible-navigator) * [How can I use a vault password with ansible-navigator?](https://docs.ansible.com/projects/navigator/faq/#how-can-i-use-a-vault-password-with-ansible-navigator) * [Other](https://docs.ansible.com/projects/navigator/faq/#other) * [How can complex commands be run inside an execution-environment?](https://docs.ansible.com/projects/navigator/faq/#how-can-complex-commands-be-run-inside-an-execution-environment) * [Why did I get an error about /dev/mqueue missing?](https://docs.ansible.com/projects/navigator/faq/#why-did-i-get-an-error-about-devmqueue-missing) * [Something didn't work, how can I troubleshoot it?](https://docs.ansible.com/projects/navigator/faq/#something-didnt-work-how-can-i-troubleshoot-it) Execution environments[¶](https://docs.ansible.com/projects/navigator/faq/#execution-environments "Permanent link") -------------------------------------------------------------------------------------------------------------------- ### What is an execution environment?[¶](https://docs.ansible.com/projects/navigator/faq/#what-is-an-execution-environment "Permanent link") An execution environment is a container image serving as an Ansible control node. See the [Getting started with Execution Environments guide](https://docs.ansible.com/ansible/devel/getting_started_ee/index.html) for details. The `ansible.cfg` file[¶](https://docs.ansible.com/projects/navigator/faq/#the-ansiblecfg-file "Permanent link") ----------------------------------------------------------------------------------------------------------------- ### Where should the `ansible.cfg` file go when using an execution environment?[¶](https://docs.ansible.com/projects/navigator/faq/#where-should-the-ansiblecfg-file-go-when-using-an-execution-environment "Permanent link") The easiest place to have the `ansible.cfg` is in the project directory adjacent to the playbook. The playbook directory is automatically mounted in the execution environment and the `ansible.cfg` file will be found. If the `ansible.cfg` file is in another directory, the `ANSIBLE_CONFIG` variable needs to be set and the directory specified as a custom volume mount. (See the [settings guide](https://docs.ansible.com/projects/navigator/settings/) for `execution-environment-volume-mounts`) ### Where should the `ansible.cfg` file go when not using an execution environment?[¶](https://docs.ansible.com/projects/navigator/faq/#where-should-the-ansiblecfg-file-go-when-not-using-an-execution-environment "Permanent link") Ansible will look for the `ansible.cfg` in the typical locations when not using an execution-environment. (See the ansible docs for the possibilities) Placement of ansible collections[¶](https://docs.ansible.com/projects/navigator/faq/#placement-of-ansible-collections "Permanent link") ---------------------------------------------------------------------------------------------------------------------------------------- ### Where should ansible collections be placed when using an execution environment?[¶](https://docs.ansible.com/projects/navigator/faq/#where-should-ansible-collections-be-placed-when-using-an-execution-environment "Permanent link") The easiest place to have ansible collections is in the project directory, in a playbook adjacent collections directory. (eg `ansible-galaxy collection install ansible.utils -p ./collections`). The playbook directory is automatically mounted in the execution environment and the collections should be found. Another option is to build the collections into an execution environment using [ansible builder](https://ansible-builder.readthedocs.io/en/latest/) . This was done to help playbook developers author playbooks that are production ready, as both ansible controller and awx support playbook adjacent collection directories. If the collections are in another directory, the `ANSIBLE_COLLECTIONS_PATH` variable needs to be set and the directory specified as a custom volume mount. (See the [settings guide](https://docs.ansible.com/projects/navigator/settings/) for `execution-environment-volume-mounts`) ### Where should ansible collections be placed when not using an execution environment?[¶](https://docs.ansible.com/projects/navigator/faq/#where-should-ansible-collections-be-placed-when-not-using-an-execution-environment "Permanent link") When not using an execution environment, ansible will look in the default locations for collections. For more information about these, check out the [collections guide](https://docs.ansible.com/ansible/latest/user_guide/collections_using.html) . `ansible-navigator` settings[¶](https://docs.ansible.com/projects/navigator/faq/#ansible-navigator-settings "Permanent link") ------------------------------------------------------------------------------------------------------------------------------ ### What is the order in which configuration settings are applied?[¶](https://docs.ansible.com/projects/navigator/faq/#what-is-the-order-in-which-configuration-settings-are-applied "Permanent link") The configuration system of ansible-navigator pulls in settings from various sources and applies them hierarchically in the following order (where the last applied changes are the most prevalent): 1. Default internal values 2. Values from a [settings file](https://docs.ansible.com/projects/navigator/settings/) 3. Values from environment variables 4. Flags and arguments specified on the command line 5. While issuing `:` commands within the text-based user interface (TUI) ### Why does `ansible-navigator` change the terminal colors or look terrible?[¶](https://docs.ansible.com/projects/navigator/faq/#why-does-ansible-navigator-change-the-terminal-colors-or-look-terrible "Permanent link") `ansible-navigator` queries the terminal for its OSC4 compatibility. OSC4, 10, 11, 104, 110, 111 indicate the terminal supports color changing and reverting. It is possible that the terminal is misrepresenting its ability. OSC4 detection can be disabled by setting `--osc4 false`. (See the [settings guide](https://docs.ansible.com/projects/navigator/settings/) for how to handle this with an environment variable or in the settings file) ### How can I change the colors used by `ansible-navigator`[¶](https://docs.ansible.com/projects/navigator/faq/#how-can-i-change-the-colors-used-by-ansible-navigator "Permanent link") Full theme support should come in a later release, for now, try `--osc4 false`. This will cause `ansible-navigator` to use the terminal's defined colors. (See the [settings guide](https://docs.ansible.com/projects/navigator/settings/) for how to handle this with an environment variable or in the settings file) ### What's with all these `site-artifact-2021-06-02T16:02:33.911259+00:00.json` files in the playbook directory?[¶](https://docs.ansible.com/projects/navigator/faq/#whats-with-all-these-site-artifact-2021-06-02t1602339112590000json-files-in-the-playbook-directory "Permanent link") `ansible-navigator` creates a playbook artifact for every playbook run. These can be helpful for reviewing the outcome of automation after it is complete, sharing and troubleshooting with a colleague, or keeping for compliance or change-control purposes. The playbook artifact file contains the detailed information about every play and task, as well as the stdout from the playbook run. Playbook artifacts can be review with `ansible-navigator replay ` or `:replay ` while in an ansible-navigator session. All playbook artifacts can be reviewed with both `--mode stdout` and `--mode interactive`, depending on the desired view. Playbook artifacts writing can be disabled and the default file naming convention changed as well.(See the [settings guide](https://docs.ansible.com/projects/navigator/settings/) for additional information) ### Why does `vi` open when I use `:open`?[¶](https://docs.ansible.com/projects/navigator/faq/#why-does-vi-open-when-i-use-open "Permanent link") `ansible-navigator` will open anything showing in the terminal in the default editor. The default is set to either `vi +{line_number} {filename}` or the current value of the `EDITOR` environment variable. Related to this is the `editor-console` setting which indicates if the editor is console/terminal based. Here are examples of alternate settings that may be useful: `[](https://docs.ansible.com/projects/navigator/faq/#__codelineno-0-1) # emacs [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-0-2) ansible-navigator: [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-0-3) editor: [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-0-4) command: emacs -nw +{line_number} {filename} [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-0-5) console: true` `[](https://docs.ansible.com/projects/navigator/faq/#__codelineno-1-1) # vscode [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-1-2) ansible-navigator: [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-1-3) editor: [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-1-4) command: code -g {filename}:{line_number} [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-1-5) console: false` `[](https://docs.ansible.com/projects/navigator/faq/#__codelineno-2-1) #pycharm [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-2-2) ansible-navigator: [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-2-3) editor: [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-2-4) command: charm --line {line_number} {filename} [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-2-5) console: false` ### How do I define volume mounts using an environment variable?[¶](https://docs.ansible.com/projects/navigator/faq/#how-do-i-define-volume-mounts-using-an-environment-variable "Permanent link") Because the definition of a volume mount may contain the `:` these need to be delimited with a `;`. `[](https://docs.ansible.com/projects/navigator/faq/#__codelineno-3-1) $ export ANSIBLE_NAVIGATOR_EXECUTION_ENVIRONMENT_VOLUME_MOUNTS /tmp/1:/tmp/1\;/tmp/2:/tmp/2:Z [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-3-2) $ ansible-navigator exec [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-3-3) bash-4.4# ls /tmp/1 [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-3-4) file.txt` ### How can `tls-verify` be disabled when an execution environment image is being pulled?[¶](https://docs.ansible.com/projects/navigator/faq/#how-can-tls-verify-be-disabled-when-an-execution-environment-image-is-being-pulled "Permanent link") Although disabling TLS verification is not recommended, it may be necessary in lab and non-production environments. The pull policy parameters can be provided on the command line or in the settings file. `[](https://docs.ansible.com/projects/navigator/faq/#__codelineno-4-1) $ ansible-navigator --pull-arguments=--tls-verify=false` `[](https://docs.ansible.com/projects/navigator/faq/#__codelineno-5-1) ansible-navigator: [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-5-2) execution-environment: [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-5-3) pull: [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-5-4) arguments: [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-5-5) - "--tls-verify=false"` SSH keys[¶](https://docs.ansible.com/projects/navigator/faq/#ssh-keys "Permanent link") ---------------------------------------------------------------------------------------- ### How do I use my SSH keys with an execution environment?[¶](https://docs.ansible.com/projects/navigator/faq/#how-do-i-use-my-ssh-keys-with-an-execution-environment "Permanent link") The simplest way to use SSH keys with an execution environment is to use `ssh-agent` and use default key names. Register keys as needed if they do not use one of the default key names. (`~/.ssh/id_rsa`, `~/.ssh/id_dsa`, `~/.ssh/id_ecdsa`, `~/.ssh/id_ed25519`, and `~/.ssh/identity`. (eg `ssh-add ~/.ssh/my_key`). `ansible-navigator` will automatically setup and enable the use of `ssh-agent` within the execution environment by volume mounting the SSH authentication socket path and setting the SSH\_AUTH\_SOCK environment variable. (eg `-v /run/user/1000/keyring/:/run/user/1000/keyring/ -e SSH_AUTH_SOCK=/run/user/1000/keyring/ssh` (as seen in the `ansible-navigator` log file when using an execution environment and `--log-level debug`) The use of `ssh-agent` results in the simplest configuration and eliminates issues with SSH key passphrases when using `ansible-navigator` with execution environments. Additionally, `ansible-navigator` will automatically volume mount the user's SSH keys into the execution environment in 2 different locations to assist users not running `ssh-agent`. 1. For compatibility with SSH connections using OpenSSH, the keys are mounted into the home directory of the default user within the execution environment as specified by the user's entry in the execution environment's `/etc/passwd` file. When using OpenSSH without `ssh-agent`, only keys using the default names (`id_rsa`, `id_dsa`, `id_ecdsa`, `id_ed25519`, and `id_xmss`) will be used. The use of `ansible_ssh_private_key_file` will enable the use of non-default named keys. `-v /home/current_user/.ssh/:/root/.ssh/` (as seen in the `ansible-navigator` log file when using an execution environment and `--log-level debug`) 1. For compatibility with SSH connections using `paramiko`, the keys are mounted into the home directory of the default user within the execution environment as specified by the `HOME` environment variable within the execution environment. When using `paramiko` without `ssh-agent`, only key using default names (`id_rsa`, `id_dsa` or `id_ecdsa`, and `id_ed25519`) will by used. The use of `ansible_ssh_private_key_file` will enable the use of non-default named keys. `-v /home/current_user/.ssh/:/home/runner/.ssh/` (as seen in the `ansible-navigator` log file when using an execution environment and `--log-level debug`) Note: When using `ansible_ssh_private_key_file` with execution environments, the path to the key needs to reference it's location after being volume mounted to the execution environment. (eg `/home/runner/.ssh/key_name` or `/root/.ssh/key_name`). It may be convenient to specify the path to the key as `~/.ssh/key_name` which will resolve to the user's home directory with or without the use of an execution environment. Compatibility with `ansible-*` utilities[¶](https://docs.ansible.com/projects/navigator/faq/#compatibility-with-ansible-utilities "Permanent link") ---------------------------------------------------------------------------------------------------------------------------------------------------- ### Why does the playbook hang when `vars_prompt`, `pause/prompt` or `--ask-pass` is used?[¶](https://docs.ansible.com/projects/navigator/faq/#why-does-the-playbook-hang-when-vars_prompt-pauseprompt-or-ask-pass-is-used "Permanent link") By default `ansible-navigator` runs the playbook in the same manner that ansible controller and AWX would run the playbook. This was done to help playbook developers author playbooks that would be ready for production. If the use of `vars_prompt`, `pause\prompt` or `--ask-pass` can not be avoided, use the `enable-prompts` parameter that disables `playbook-artifact` creation and sets the mode to `stdout` causing `ansible-navigator` to run the playbook in a manner that is compatible with `ansible-playbook` and allows for user interaction. `[](https://docs.ansible.com/projects/navigator/faq/#__codelineno-6-1) $ ansible-navigator run site.yml --enable-prompts --ask-pass` ### How can I use `ansible-test` without having it locally installed?[¶](https://docs.ansible.com/projects/navigator/faq/#how-can-i-use-ansible-test-without-having-it-locally-installed "Permanent link") The `ansible-test` utility can be used from within an execution environment using the `exec` subcommand. `[](https://docs.ansible.com/projects/navigator/faq/#__codelineno-7-1) $ cd ./collections/ansible_collections/ansible/utils/ [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-7-2) $ ansible-navigator exec -- ansible-test sanity --python 3.10` ### How do I use `ansible-playbook` parameters like `--forks 15`?[¶](https://docs.ansible.com/projects/navigator/faq/#how-do-i-use-ansible-playbook-parameters-like-forks-15 "Permanent link") All parameters not directly used by `ansible-navigator` will be passed to the `ansible-playbook` command. These can be provided inline after the `ansible-navigator` parameters or delimited by a `--` `[](https://docs.ansible.com/projects/navigator/faq/#__codelineno-8-1) $ ansible-navigator run site.yml --forks 15 [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-8-2) $ ansible-navigator run site.yml -- --forks 15` ### How can I use syntax-check with `ansible-navigator`?[¶](https://docs.ansible.com/projects/navigator/faq/#how-can-i-use-syntax-check-with-ansible-navigator "Permanent link") To check for basic syntax errors in an Ansible playbook, one can use `ansible-navigator run` command to validate the syntax of a playbook. This also allows user to specify an EE while validating the syntax. `[](https://docs.ansible.com/projects/navigator/faq/#__codelineno-9-1) $ ansible-navigator run site.yml -m stdout --syntax-check` In case of any failure in syntax validation, a syntax error is reported with the output that includes the approximate location of the syntax issue in the playbook. ### How can I use a vault password with `ansible-navigator`?[¶](https://docs.ansible.com/projects/navigator/faq/#how-can-i-use-a-vault-password-with-ansible-navigator "Permanent link") The following options provide a vault password to `ansible-navigator` when using the text-based user interface (TUI). **Please ensure these do not conflict with your enterprise security standards. Do not add password files to source control.** 1. Store the vault password **securely** on the local file system You can create an encrypted file with your tool of choice, gpg, openssl, etc. But note that gpg is better because you can leverage the gpg-agent in order to not have to introduce your password all the time. Then you create a shell script that runs the decrypt command, eg: `[](https://docs.ansible.com/projects/navigator/faq/#__codelineno-10-1) cat < ~/bin/vault.sh [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-10-2) #!/bin/sh [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-10-3) [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-10-4) gpg -d /path/to/encrypted_file.asc [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-10-5) EOF [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-10-6) chmod +x ~/bin/vault.sh` Add a simple shellscript to your project: `[](https://docs.ansible.com/projects/navigator/faq/#__codelineno-11-1) cat < vault.sh [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-11-2) #!/bin/sh [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-11-3) [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-11-4) echo $ANSIBLE_VAULT_PASSWORD [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-11-5) EOF [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-11-6) chmod +x vault.sh` Now you can export `ANSIBLE_VAULT_PASSWORD` with the result of that script and set `ANSIBLE_VAULT_PASSWORD_FILE` to this script as you run ansible-navigator: `[](https://docs.ansible.com/projects/navigator/faq/#__codelineno-12-1) ANSIBLE_VAULT_PASSWORD="$( ~/bin/vault.sh )" ansible-navigator run --senv=ANSIBLE_VAULT_PASSWORD_FILE=vault.sh --penv=ANSIBLE_VAULT_PASSWORD (...)` It won't even display your password in ps for other users. 1. Store the vault password (clear text, insecurely) on the local file system `[](https://docs.ansible.com/projects/navigator/faq/#__codelineno-13-1) $ touch ~/.vault_password [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-13-2) $ chmod 600 ~/.vault_password [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-13-3) # The leading space here is necessary to keep the command out of the command history [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-13-4) $ echo my_password >> ~/.vault_password [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-13-5) # Link the password file into the current working directory [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-13-6) $ ln ~/.vault_password . [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-13-7) # Set the environment variable to the location of the file [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-13-8) $ export ANSIBLE_VAULT_PASSWORD_FILE=.vault_password [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-13-9) # Pass the variable into the execution-environment [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-13-10) $ ansible-navigator run --pass-environment-variable ANSIBLE_VAULT_PASSWORD_FILE site.yml` 1. Store the vault password in an environment variable This is a less secure version of the first option. Chances are that your environment prohibits saving passwords in clear text on disk. If you are subject to such a rule, then this will obviously include any command history file your shell saves to disk. In case you use bash, you can leverage [HISTCONTROL](https://www.gnu.org/software/bash/manual/html_node/Bash-Variables.html#index-HISTCONTROL) and an [environment](https://www.gnu.org/software/bash/manual/html_node/Environment.html) variable as shown in the following example. `[](https://docs.ansible.com/projects/navigator/faq/#__codelineno-14-1) $ touch ~/.vault_password.sh [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-14-2) $ chmod 700 ~/.vault_password.sh [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-14-3) $ echo -e '#!/bin/sh\necho ${ANSIBLE_VAULT_PASSWORD}' >> ~/.vault_password.sh [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-14-4) # Link the password file into the current working directory [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-14-5) $ ln ~/.vault_password.sh . [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-14-6) # The leading space here is necessary to keep the command out of the command history [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-14-7) # by using an environment variable prefixed with ANSIBLE it will automatically get passed [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-14-8) # into the execution environment [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-14-9) $ HISTCONTROL=ignorespace [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-14-10) $ export ANSIBLE_VAULT_PASSWORD=my_password [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-14-11) # Set the environment variable to the location of the file when executing ansible-navigator [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-14-12) $ ANSIBLE_VAULT_PASSWORD_FILE=.vault_password.sh ansible-navigator run site.yml` Additional information about `ansible-vault` can be found [here](https://docs.ansible.com/ansible/latest/user_guide/vault.html) Other[¶](https://docs.ansible.com/projects/navigator/faq/#other "Permanent link") ---------------------------------------------------------------------------------- ### How can complex commands be run inside an execution-environment?[¶](https://docs.ansible.com/projects/navigator/faq/#how-can-complex-commands-be-run-inside-an-execution-environment "Permanent link") The easiest way to pass complex commands to an execution environment is by using the `--` delimiter. Everything after the `--` will be passed into the execution-environment. `[](https://docs.ansible.com/projects/navigator/faq/#__codelineno-15-1) $ ansible-navigator exec -- ansible --version | head -n 1 | awk -F '\\[|\\]|\\s' '{print $4}' [](https://docs.ansible.com/projects/navigator/faq/#__codelineno-15-2) 2.12.4rc1.post0` ### Why did I get an error about `/dev/mqueue` missing?[¶](https://docs.ansible.com/projects/navigator/faq/#why-did-i-get-an-error-about-devmqueue-missing "Permanent link") Although the `/dev/mqueue` directory is not used by `ansible-navigator`, it is currently required when using `podman`. Not all operating systems have a `/dev/mqueue` directory by default. Please reference the documentation for your operating system related to POSIX message queues, or simply create the directory. ### Something didn't work, how can I troubleshoot it?[¶](https://docs.ansible.com/projects/navigator/faq/#something-didnt-work-how-can-i-troubleshoot-it "Permanent link") `ansible-navigator` has reasonable logging messages, debug logging can be enabled with `--log-level debug`. If you think you might have found a bug, please [log an issue](https://github.com/ansible/ansible-navigator/issues/new/choose) and include the details from the log file. --- # Release notes - antsibull-nox – Antsibull Nox Helper [Skip to content](https://docs.ansible.com/projects/antsibull-nox/changelog/#antsibull-nox-helper-release-notes) Antsibull Nox Helper Release Notes[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#antsibull-nox-helper-release-notes "Permanent link") ====================================================================================================================================================== v1.6.0[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#v160 "Permanent link") -------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#release-summary "Permanent link") Feature and bugfix release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#minor-changes "Permanent link") * Allow to run commands before executing nox in shared workflows ([https://github.com/ansible-community/antsibull-nox/pull/188](https://github.com/ansible-community/antsibull-nox/pull/188) ). * Always show tracebacks in case of errors for ansible-core 2.19+ in integration tests. Showing these has been turned off by default in ansible-core 2.19, which is great for intentional errors, but makes debugging unintentional ones (like plugin crashes) hard to debug since you do not see where the error comes from ([https://github.com/ansible-community/antsibull-nox/pull/190](https://github.com/ansible-community/antsibull-nox/pull/190) ). * Antsibull-nox's ansible-core `devel` and `milestone` branch versions have been updated to 2.22. This means that `stable-2.21` will now be added to CI matrices if `max_version` has not been explicitly specified ([https://github.com/ansible-community/antsibull-nox/pull/195](https://github.com/ansible-community/antsibull-nox/pull/195) ). ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#bugfixes "Permanent link") * If change detection is enabled and `antsibull-nox.toml` or a linter's config file is changed, check all files ([https://github.com/ansible-community/antsibull-nox/issues/183](https://github.com/ansible-community/antsibull-nox/issues/183) , [https://github.com/ansible-community/antsibull-nox/pull/185](https://github.com/ansible-community/antsibull-nox/pull/185) ). * Run `ruff check` with `--quiet` to avoid warnings to prevent parsing of the JSON output ([https://github.com/ansible-community/antsibull-nox/issues/184](https://github.com/ansible-community/antsibull-nox/issues/184) , [https://github.com/ansible-community/antsibull-nox/pull/186](https://github.com/ansible-community/antsibull-nox/pull/186) ). v1.5.0[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#v150 "Permanent link") -------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#release-summary_1 "Permanent link") Bugfix and feature release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#minor-changes_1 "Permanent link") * Allow to configure which files and directories are modules and module utils ([https://github.com/ansible-community/antsibull-nox/pull/181](https://github.com/ansible-community/antsibull-nox/pull/181) ). * Allow to define the Python code files that the linters should run on ([https://github.com/ansible-community/antsibull-nox/issues/178](https://github.com/ansible-community/antsibull-nox/issues/178) , [https://github.com/ansible-community/antsibull-nox/pull/181](https://github.com/ansible-community/antsibull-nox/pull/181) ). * Allow to set minimum Python version supported by a collection. This is currently used for the `[sessions.ansible_test_integration_w_default_container]` section ([https://github.com/ansible-community/antsibull-nox/issues/163](https://github.com/ansible-community/antsibull-nox/issues/163) , [https://github.com/ansible-community/antsibull-nox/pull/176](https://github.com/ansible-community/antsibull-nox/pull/176) ). * Allow to specify special configs for modules for all formatters and linters in the `lint` section ([https://github.com/ansible-community/antsibull-nox/pull/181](https://github.com/ansible-community/antsibull-nox/pull/181) ). * Format messages nicely outside CI, or when not configured otherwise ([https://github.com/ansible-community/antsibull-nox/pull/175](https://github.com/ansible-community/antsibull-nox/pull/175) ). * Improve error reporting system used by internal scripts ([https://github.com/ansible-community/antsibull-nox/pull/171](https://github.com/ansible-community/antsibull-nox/pull/171) ). * Improve output parsing and formatting for pylint and mypy checks ([https://github.com/ansible-community/antsibull-nox/pull/171](https://github.com/ansible-community/antsibull-nox/pull/171) ). * In the `ruff check` and `ruff check --fix` checks, make sure to run ruff in a `ansible_collections///` structure so that import classification works correctly. The output of these checks is now handled as JSON and parsed and then formatted by antsibull-nox ([https://github.com/ansible-community/antsibull-nox/pull/171](https://github.com/ansible-community/antsibull-nox/pull/171) ). * When antsibull-docs 2.24.0+ is available, the `docs-check` session now uses its JSON message format ([https://github.com/ansible-community/antsibull-nox/pull/173](https://github.com/ansible-community/antsibull-nox/pull/173) ). ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#bugfixes_1 "Permanent link") * Extra code files were ignored so far in the `pylint` test. They are now used there as well ([https://github.com/ansible-community/antsibull-nox/pull/181](https://github.com/ansible-community/antsibull-nox/pull/181) ). * Fix `antsibull-nox-config` session in case antsibull-nox has not been installed in `$PATH` ([https://github.com/ansible-community/antsibull-nox/pull/169](https://github.com/ansible-community/antsibull-nox/pull/169) ). * Fix reporting of locations when running yamllint for YAML code blocks in RST extra docs ([https://github.com/ansible-community/antsibull-nox/pull/177](https://github.com/ansible-community/antsibull-nox/pull/177) ). * Only pass `--color [yes]` to ansible-test when nox is running in color mode ([https://github.com/ansible-community/antsibull-nox/pull/174](https://github.com/ansible-community/antsibull-nox/pull/174) ). * Remove superfluous call from the `antsibull-nox-config` session ([https://github.com/ansible-community/antsibull-nox/pull/172](https://github.com/ansible-community/antsibull-nox/pull/172) ). v1.4.1[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#v141 "Permanent link") -------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#release-summary_2 "Permanent link") Bugfix release. ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#bugfixes_2 "Permanent link") * Avoid construct that does not work with Pythons before 3.13 ([https://github.com/ansible-community/antsibull-nox/pull/165](https://github.com/ansible-community/antsibull-nox/pull/165) ). * Fix compatibility with Python 3.9, and for Python versions < 3.12 ([https://github.com/ansible-community/antsibull-nox/pull/168](https://github.com/ansible-community/antsibull-nox/pull/168) ). * Make sure to set `ANTSIBULL_NOX_IGNORE_INSTALLED_COLLECTIONS` in the GitHub Action also while setting up the nox environment(s) ([https://github.com/ansible-community/antsibull-nox/pull/166](https://github.com/ansible-community/antsibull-nox/pull/166) ). v1.4.0[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#v140 "Permanent link") -------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#release-summary_3 "Permanent link") New bugfix and feature release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#minor-changes_2 "Permanent link") * Add Python 3.15 to Python version search list ([https://github.com/ansible-community/antsibull-nox/pull/142](https://github.com/ansible-community/antsibull-nox/pull/142) ). * Allow to specify extra `requirements.yml` files for ansible-lint ([https://github.com/ansible-community/antsibull-nox/issues/156](https://github.com/ansible-community/antsibull-nox/issues/156) , [https://github.com/ansible-community/antsibull-nox/issues/161](https://github.com/ansible-community/antsibull-nox/issues/161) ). * Also look for needed collections before running ansible-lint [in other places that ansible-lint searches for requirements.yml](https://github.com/ansible/ansible-lint/blob/main/src/ansiblelint/rules/syntax_check.md#syntax-checkunknown-module) ([https://github.com/ansible-community/antsibull-nox/issues/156](https://github.com/ansible-community/antsibull-nox/issues/156) , [https://github.com/ansible-community/antsibull-nox/pull/159](https://github.com/ansible-community/antsibull-nox/pull/159) ). * Declare support for Python 3.14 ([https://github.com/ansible-community/antsibull-nox/pull/141](https://github.com/ansible-community/antsibull-nox/pull/141) ). * Use Python 3.14 for antsibull-nox action ([https://github.com/ansible-community/antsibull-nox/pull/141](https://github.com/ansible-community/antsibull-nox/pull/141) ). * When determining changed files for pylint and mypy, also consider files that (transitively) import the changed files ([https://github.com/ansible-community/antsibull-nox/pull/143](https://github.com/ansible-community/antsibull-nox/pull/143) ). * When running ansible-galaxy to list, download, or install collections, look in the current session's venv first ([https://github.com/ansible-community/antsibull-nox/pull/155](https://github.com/ansible-community/antsibull-nox/pull/155) , [https://github.com/ansible-community/antsibull-nox/pull/157](https://github.com/ansible-community/antsibull-nox/pull/157) , [https://github.com/ansible-community/antsibull-nox/pull/158](https://github.com/ansible-community/antsibull-nox/pull/158) , [https://github.com/ansible-community/antsibull-nox/pull/160](https://github.com/ansible-community/antsibull-nox/pull/160) ). ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#bugfixes_3 "Permanent link") * Adjust URLs for antsibull-nox in new templated noxfiles ([https://github.com/ansible-community/antsibull-nox/pull/148](https://github.com/ansible-community/antsibull-nox/pull/148) ). * Avoid using relative symlinks to link from temporary collection root to collections. This can cause problems with non-canonical paths ([https://github.com/ansible-community/antsibull-nox/issues/152](https://github.com/ansible-community/antsibull-nox/issues/152) , [https://github.com/ansible-community/antsibull-nox/pull/153](https://github.com/ansible-community/antsibull-nox/pull/153) ). * If pylint's output is not valid JSON, show output instead of crashing ([https://github.com/ansible-community/antsibull-nox/pull/140](https://github.com/ansible-community/antsibull-nox/pull/140) ). * When computing Python 3 only paths for black or pylint, do not recurse into `__pycache__` ([https://github.com/ansible-community/antsibull-nox/pull/143](https://github.com/ansible-community/antsibull-nox/pull/143) ). * When determining which files to run various Python linters on when change detection is enabled, ensure to restrict to Python files ([https://github.com/ansible-community/antsibull-nox/pull/146](https://github.com/ansible-community/antsibull-nox/pull/146) ). * Work around [bug in ansible-galaxy when no collections are found](https://github.com/ansible/ansible/issues/73127) ([https://github.com/ansible-community/antsibull-nox/pull/154](https://github.com/ansible-community/antsibull-nox/pull/154) ). v1.3.2[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#v132 "Permanent link") -------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#release-summary_4 "Permanent link") Maintenance release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#minor-changes_3 "Permanent link") * Antsibull-nox's ansible-core `devel` and `milestone` branch versions have been updated to 2.21. This means that `stable-2.20` will now be added to CI matrices if `max_version` has not been explicitly specified ([https://github.com/ansible-community/antsibull-nox/pull/139](https://github.com/ansible-community/antsibull-nox/pull/139) ). v1.3.1[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#v131 "Permanent link") -------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#release-summary_5 "Permanent link") Bugfix release. ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#bugfixes_4 "Permanent link") * Fix `mypy` invocation in `typing` session. For some reason the file list always ended up empty and `mypy` got skipped ([https://github.com/ansible-community/antsibull-nox/pull/137](https://github.com/ansible-community/antsibull-nox/pull/137) ). * isort invocation - make sure to pass `--src` in an appropriate directory structure to ensure correct and more consistent sorting ([https://github.com/ansible-community/antsibull-nox/issues/134](https://github.com/ansible-community/antsibull-nox/issues/134) , [https://github.com/ansible-community/antsibull-nox/pull/136](https://github.com/ansible-community/antsibull-nox/pull/136) ). v1.3.0[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#v130 "Permanent link") -------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#release-summary_6 "Permanent link") Feature and bugfix release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#minor-changes_4 "Permanent link") * Allow to add tags to integration test sessions, automatically add tags to all sessions showing up in the matrix, and allow filtering the CI matrix generated by the shared workflow by these tags ([https://github.com/ansible-community/antsibull-nox/issues/125](https://github.com/ansible-community/antsibull-nox/issues/125) , [https://github.com/ansible-community/antsibull-nox/pull/125](https://github.com/ansible-community/antsibull-nox/pull/125) , [https://github.com/ansible-community/antsibull-nox/pull/126](https://github.com/ansible-community/antsibull-nox/pull/126) ). * Allow to specify Ansible variables in integration tests directly or through environment variables with new `ansible_vars` config directive ([https://github.com/ansible-community/antsibull-nox/pull/117](https://github.com/ansible-community/antsibull-nox/pull/117) ). * Allow to specify a list of packages, requirement files, and constraint files for every `_package` key in the config ([https://github.com/ansible-community/antsibull-nox/issues/108](https://github.com/ansible-community/antsibull-nox/issues/108) , [https://github.com/ansible-community/antsibull-nox/pull/119](https://github.com/ansible-community/antsibull-nox/pull/119) ). * Allow to specify individual ansible-test integration sessions with the new `[sessions.ansible_test_integration]` config setting ([https://github.com/ansible-community/antsibull-nox/issues/114](https://github.com/ansible-community/antsibull-nox/issues/114) , [https://github.com/ansible-community/antsibull-nox/pull/118](https://github.com/ansible-community/antsibull-nox/pull/118) ). * Allow to specify minimum/maximum ansible-core version to `matrix-generator` session and shared workflow ([https://github.com/ansible-community/antsibull-nox/issues/113](https://github.com/ansible-community/antsibull-nox/issues/113) , [https://github.com/ansible-community/antsibull-nox/pull/115](https://github.com/ansible-community/antsibull-nox/pull/115) , [https://github.com/ansible-community/antsibull-nox/pull/126](https://github.com/ansible-community/antsibull-nox/pull/126) ). * Antsibull-nox now supports VCS configuration and basic change detection. At the moment, the following tests support change detection: * All ansible-test tests configured through `antsibull-nox.toml`; * All ansible-test tests configured through `noxfile.py` that explicitly allow change detection; * All `lint` sessions (`formatters`, `codeqa`, `yamllint`, `typing`); * The `extra-checks` session and all its tests; * All tests but `reuse` from the `license-check` session; * The _docs-check_ sessions are restricted to changed files (for code-block tests), or skipped if there are no appropriate changed files. Change detection can be enabled with the environment variable `ANTSIBULL_CHANGE_DETECTION`. The base branch can explicitly set with the environment variable `ANTSIBULL_BASE_BRANCH` ([https://github.com/ansible-community/antsibull-nox/issues/112](https://github.com/ansible-community/antsibull-nox/issues/112) , [https://github.com/ansible-community/antsibull-nox/pull/120](https://github.com/ansible-community/antsibull-nox/pull/120) , [https://github.com/ansible-community/antsibull-nox/pull/122](https://github.com/ansible-community/antsibull-nox/pull/122) , [https://github.com/ansible-community/antsibull-nox/pull/123](https://github.com/ansible-community/antsibull-nox/pull/123) , [https://github.com/ansible-community/antsibull-nox/pull/124](https://github.com/ansible-community/antsibull-nox/pull/124) , [https://github.com/ansible-community/antsibull-nox/pull/129](https://github.com/ansible-community/antsibull-nox/pull/129) , [https://github.com/ansible-community/antsibull-nox/pull/130](https://github.com/ansible-community/antsibull-nox/pull/130) ). \* In `[sessions.lint]`, `pylint_extra_deps` and `mypy_extra_deps` can now use package type dictionaries like `{type = "requirements", file = "requirements/mypy-extra-deps.txt"}` ([https://github.com/ansible-community/antsibull-nox/pull/133](https://github.com/ansible-community/antsibull-nox/pull/133) ). \* Make codecov upload for the shared nox workflow more flexible by allowing to disable it for specific event types ([https://github.com/ansible-community/antsibull-nox/pull/132](https://github.com/ansible-community/antsibull-nox/pull/132) ). \* Provide a new shared workflow `.github/workflows/reusable-nox-run` that allows to run nox with change detection ([https://github.com/ansible-community/antsibull-nox/pull/128](https://github.com/ansible-community/antsibull-nox/pull/128) ). \* The GitHub antsibull-nox action and the shared workflow support change detection. To enable change detection for PRs, simply set the workflow parameter `change-detection-in-prs` to `true` ([https://github.com/ansible-community/antsibull-nox/issues/112](https://github.com/ansible-community/antsibull-nox/issues/112) , [https://github.com/ansible-community/antsibull-nox/pull/120](https://github.com/ansible-community/antsibull-nox/pull/120) , [https://github.com/ansible-community/antsibull-nox/pull/121](https://github.com/ansible-community/antsibull-nox/pull/121) ). \* antsibull-nox now depends on antsibull-fileutils >= 1.5.0 ([https://github.com/ansible-community/antsibull-nox/pull/122](https://github.com/ansible-community/antsibull-nox/pull/122) ). ### Deprecated Features[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#deprecated-features "Permanent link") * In `[sessions.lint]`, shell splitting of strings in `pylint_extra_deps` and `mypy_extra_deps` is deprecated and will stop working in future releases. Use package type dictionaries instead ([https://github.com/ansible-community/antsibull-nox/pull/133](https://github.com/ansible-community/antsibull-nox/pull/133) ). * In `[sessions.lint]`, using strings that start with dashes (`-`) is deprecated and will stop working in future releases. Use appropriate package type dictionaries instead ([https://github.com/ansible-community/antsibull-nox/pull/133](https://github.com/ansible-community/antsibull-nox/pull/133) ). * In all `_package` options, package names starting with dashes (`-`) are deprecated and will stop working in future releases. Use appropriate package type dictionaries instead ([https://github.com/ansible-community/antsibull-nox/pull/133](https://github.com/ansible-community/antsibull-nox/pull/133) ). v1.2.0[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#v120 "Permanent link") -------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#release-summary_7 "Permanent link") Maintenance and feature release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#minor-changes_5 "Permanent link") * Allow to install packages editably and from requirement files ([https://github.com/ansible-community/antsibull-nox/pull/106](https://github.com/ansible-community/antsibull-nox/pull/106) ). ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#bugfixes_5 "Permanent link") * The `action-groups` extra check failed if `plugins/modules/` does not exist ([https://github.com/ansible-community/antsibull-nox/pull/104](https://github.com/ansible-community/antsibull-nox/pull/104) ). * Update supported Python versions for ansible-core milestone ([https://github.com/ansible-community/antsibull-nox/pull/109](https://github.com/ansible-community/antsibull-nox/pull/109) ). v1.1.1[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#v111 "Permanent link") -------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#release-summary_8 "Permanent link") Maintenance release. ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#bugfixes_6 "Permanent link") * Update supported Python versions for ansible-core devel ([https://github.com/ansible-community/antsibull-nox/pull/102](https://github.com/ansible-community/antsibull-nox/pull/102) ). v1.1.0[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#v110 "Permanent link") -------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#release-summary_9 "Permanent link") Feature release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#minor-changes_6 "Permanent link") * Add an `ee-check` session that allows test builds of execution environments ([https://github.com/ansible-community/antsibull-nox/issues/16](https://github.com/ansible-community/antsibull-nox/issues/16) , [https://github.com/ansible-community/antsibull-nox/pull/69](https://github.com/ansible-community/antsibull-nox/pull/69) , [https://github.com/ansible-community/antsibull-nox/pull/99](https://github.com/ansible-community/antsibull-nox/pull/99) , [https://github.com/ansible-community/antsibull-nox/pull/100](https://github.com/ansible-community/antsibull-nox/pull/100) , [https://github.com/ansible-community/antsibull-nox/pull/101](https://github.com/ansible-community/antsibull-nox/pull/101) ). * Allow to set preference for container engines with `ANTSIBULL_NOX_CONTAINER_ENGINE` environment variable ([https://github.com/ansible-community/antsibull-nox/issues/98](https://github.com/ansible-community/antsibull-nox/issues/98) , [https://github.com/ansible-community/antsibull-nox/pull/100](https://github.com/ansible-community/antsibull-nox/pull/100) ). * The YAML-in-RST checker for the `yamllint` session now also checks `ansible-output-data` and `ansible-output-meta` directives for antsibull-doc's `ansible-output` subcommand ([https://github.com/ansible-community/antsibull-nox/pull/95](https://github.com/ansible-community/antsibull-nox/pull/95) , [https://github.com/ansible-community/antsibull-nox/pull/96](https://github.com/ansible-community/antsibull-nox/pull/96) ). * When using the reusable GHA workflow, execution environment tests are automatically added to the matrix ([https://github.com/ansible-community/antsibull-nox/issues/16](https://github.com/ansible-community/antsibull-nox/issues/16) , [https://github.com/ansible-community/antsibull-nox/pull/99](https://github.com/ansible-community/antsibull-nox/pull/99) ). * antsibull-nox now depends on antsibull-fileutils >= 1.4.0 ([https://github.com/ansible-community/antsibull-nox/pull/97](https://github.com/ansible-community/antsibull-nox/pull/97) ). v1.0.0[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#v100 "Permanent link") -------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#release-summary_10 "Permanent link") First stable release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#minor-changes_7 "Permanent link") * New extra check `avoid-characters` allows to flag characters / regular expressions. This can for example be used to avoid tabulator characters, but also more complex character sequences ([https://github.com/ansible-community/antsibull-nox/issues/89](https://github.com/ansible-community/antsibull-nox/issues/89) , [https://github.com/ansible-community/antsibull-nox/pull/94](https://github.com/ansible-community/antsibull-nox/pull/94) ). v0.7.0[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#v070 "Permanent link") -------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#release-summary_11 "Permanent link") Feature release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#minor-changes_8 "Permanent link") * Antsibull-nox's ansible-core `devel` and `milestone` branch versions have been updated to 2.20. This means that `stable-2.19` will now be added to CI matrices if `max_version` has not been explicitly specified ([https://github.com/ansible-community/antsibull-nox/pull/91](https://github.com/ansible-community/antsibull-nox/pull/91) ). * The `docs-check` session now also passes the new `--check-extra-docs-refs` parameter to `antsibull-docs lint-collection-docs` for antsibull-docs >= 2.18.0 ([https://github.com/ansible-community/antsibull-nox/pull/90](https://github.com/ansible-community/antsibull-nox/pull/90) ). v0.6.0[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#v060 "Permanent link") -------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#release-summary_12 "Permanent link") Bugfix and feature release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#minor-changes_9 "Permanent link") * Add new extra check `no-trailing-whitespace` ([https://github.com/ansible-community/antsibull-nox/pull/85](https://github.com/ansible-community/antsibull-nox/pull/85) ). * Add new options to `docs-check` that allow to validate code blocks in collection extra docs ([https://github.com/ansible-community/antsibull-nox/pull/88](https://github.com/ansible-community/antsibull-nox/pull/88) ). * Support running `ruff check --fix --select ...` in the `formatters` session by setting `run_ruff_autofix=true` in the config ([https://github.com/ansible-community/antsibull-nox/issues/70](https://github.com/ansible-community/antsibull-nox/issues/70) , [https://github.com/ansible-community/antsibull-nox/pull/82](https://github.com/ansible-community/antsibull-nox/pull/82) ). * Support running `ruff check` in the `codeqa` session by setting `run_ruff_check=true` in the config ([https://github.com/ansible-community/antsibull-nox/issues/70](https://github.com/ansible-community/antsibull-nox/issues/70) , [https://github.com/ansible-community/antsibull-nox/pull/82](https://github.com/ansible-community/antsibull-nox/pull/82) ). * Support running `ruff format` in the `formatters` session by setting `run_ruff_format=true` in the config ([https://github.com/ansible-community/antsibull-nox/issues/70](https://github.com/ansible-community/antsibull-nox/issues/70) , [https://github.com/ansible-community/antsibull-nox/pull/82](https://github.com/ansible-community/antsibull-nox/pull/82) ). * The `yamllint` test now also checks YAML and YAML+Jinja code blocks in extra documentation (`.rst` files in `docs/docsite/rst/`) ([https://github.com/ansible-community/antsibull-nox/pull/87](https://github.com/ansible-community/antsibull-nox/pull/87) ). ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#bugfixes_7 "Permanent link") * Do not fail if an unexpected action group is found that only contains a metadata entry ([https://github.com/ansible-community/antsibull-nox/pull/81](https://github.com/ansible-community/antsibull-nox/pull/81) ). * Fix config file types for `no_unwanted_files_skip_directories` and `no_unwanted_files_yaml_directories` to what is documented; that is, do not allow `None` ([https://github.com/ansible-community/antsibull-nox/pull/85](https://github.com/ansible-community/antsibull-nox/pull/85) ). * Ignore metadata entries in action groups ([https://github.com/ansible-community/antsibull-nox/pull/81](https://github.com/ansible-community/antsibull-nox/pull/81) ). * The `no_unwanted_files_skip_directories` option for the `no-unwanted-files` was not used ([https://github.com/ansible-community/antsibull-nox/pull/85](https://github.com/ansible-community/antsibull-nox/pull/85) ). v0.5.0[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#v050 "Permanent link") -------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#release-summary_13 "Permanent link") Feature and bugfix release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#minor-changes_10 "Permanent link") * Allow to pass environment variables as Ansible variables for integration tests with the new `ansible_vars_from_env_vars` option for `sessions.ansible_test_integration_w_default_container` ([https://github.com/ansible-community/antsibull-nox/pull/78](https://github.com/ansible-community/antsibull-nox/pull/78) ). ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#bugfixes_8 "Permanent link") * Fix action group test. No errors were reported due to a bug in the test ([https://github.com/ansible-community/antsibull-nox/pull/80](https://github.com/ansible-community/antsibull-nox/pull/80) ). v0.4.0[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#v040 "Permanent link") -------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#release-summary_14 "Permanent link") Feature and bugfix release. ### Major Changes[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#major-changes "Permanent link") * Required collections can now be installed from different sources per depending on the ansible-core version ([https://github.com/ansible-community/antsibull-nox/pull/76](https://github.com/ansible-community/antsibull-nox/pull/76) ). ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#minor-changes_11 "Permanent link") * Capture mypy and pylint errors to report paths of files relative to collection's root, instead of relative to the virtual `ansible_collections` directory ([https://github.com/ansible-community/antsibull-nox/pull/75](https://github.com/ansible-community/antsibull-nox/pull/75) ). * Make yamllint plugin check also check doc fragments ([https://github.com/ansible-community/antsibull-nox/pull/73](https://github.com/ansible-community/antsibull-nox/pull/73) ). * Positional arguments passed to nox are now forwarded to `ansible-lint` ([https://github.com/ansible-community/antsibull-nox/pull/74](https://github.com/ansible-community/antsibull-nox/pull/74) ). * The yamllint session now ignores `RETURN` documentation with values `#` and \`\` # \`\` ([https://github.com/ansible-community/antsibull-nox/pull/71](https://github.com/ansible-community/antsibull-nox/pull/71) ). * The yamllint test no longer shows all filenames in the command line ([https://github.com/ansible-community/antsibull-nox/pull/72](https://github.com/ansible-community/antsibull-nox/pull/72) ). ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#bugfixes_9 "Permanent link") * Adjust yamllint test to no longer use the user's global config, but only the project's config ([https://github.com/ansible-community/antsibull-nox/pull/72](https://github.com/ansible-community/antsibull-nox/pull/72) ). v0.3.0[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#v030 "Permanent link") -------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#release-summary_15 "Permanent link") Feature release that is stabilizing the API. All noxfiles and configs using this version should still work with antsibull-nox 1.0.0, unless a critical problem is found that cannot be solved in any other way. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#minor-changes_12 "Permanent link") * Add `antsibull-nox init` command that creates a `noxfile.py` and `antsibull-nox.tomll` to get started ([https://github.com/ansible-community/antsibull-nox/pull/58](https://github.com/ansible-community/antsibull-nox/pull/58) ). * Add `callback_before` and `callback_after` parameters to `antsibull_nox.add_ansible_test_session()` ([https://github.com/ansible-community/antsibull-nox/pull/63](https://github.com/ansible-community/antsibull-nox/pull/63) ). * Add a `antsibull-nox` CLI tool with a subcommand `lint-config` that lints `noxfile.py` and the `antsibull-nox.toml` config file ([https://github.com/ansible-community/antsibull-nox/pull/56](https://github.com/ansible-community/antsibull-nox/pull/56) ). * Add a session for linting the antsibull-nox configuration to `lint` ([https://github.com/ansible-community/antsibull-nox/pull/56](https://github.com/ansible-community/antsibull-nox/pull/56) ). * Add new options `skip_tests`, `allow_disabled`, and `enable_optional_errors` for ansible-test sanity sessions ([https://github.com/ansible-community/antsibull-nox/pull/61](https://github.com/ansible-community/antsibull-nox/pull/61) ). * Allow to disable coverage upload for specific integration test jobs in shared workflow with `has-coverage=false` in extra data ([https://github.com/ansible-community/antsibull-nox/pull/64](https://github.com/ansible-community/antsibull-nox/pull/64) ). * Ensure that Galaxy importer's output is actually collapsed on GHA ([https://github.com/ansible-community/antsibull-nox/pull/67](https://github.com/ansible-community/antsibull-nox/pull/67) ). * Never show Galaxy importer output unless it can be collapsed, verbosity is enabled, or a new config option `galaxy_importer_always_show_logs` is set to `true` ([https://github.com/ansible-community/antsibull-nox/pull/67](https://github.com/ansible-community/antsibull-nox/pull/67) ). * Skip symlinks that do not point to files in `license-check` and `yamllint` sessions ([https://github.com/ansible-community/antsibull-nox/pull/61](https://github.com/ansible-community/antsibull-nox/pull/61) ). * Update shared workflow to use a `display-name` and `gha-container` extra data ([https://github.com/ansible-community/antsibull-nox/pull/63](https://github.com/ansible-community/antsibull-nox/pull/63) ). ### Removed Features (previously deprecated)[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#removed-features-previously-deprecated "Permanent link") * Removed all deprecated functions from `antsibull_nox.**` that generate sessions. The only functions left that are public API are `antsibull_nox.load_antsibull_nox_toml()`, `antsibull_nox.add_ansible_test_session()`, and `antsibull_nox.sessions.prepare_collections()` ([https://github.com/ansible-community/antsibull-nox/pull/54](https://github.com/ansible-community/antsibull-nox/pull/54) ). ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#bugfixes_10 "Permanent link") * Action groups extra test no longer fails if `action_groups` does not exist in `meta/runtime.yml`. It can now be used to ensure that there is no action group present in `meta/runtime.yml` ([https://github.com/ansible-community/antsibull-nox/pull/60](https://github.com/ansible-community/antsibull-nox/pull/60) ). * Do not fail when trying to install an empty list of packages when `run_reuse=false` ([https://github.com/ansible-community/antsibull-nox/pull/65](https://github.com/ansible-community/antsibull-nox/pull/65) ). * Make sure that `extra_code_files` is considered for `black` when `run_black_modules=false` ([https://github.com/ansible-community/antsibull-nox/pull/59](https://github.com/ansible-community/antsibull-nox/pull/59) ). * Make sure to flush stdout after calling `print()` ([https://github.com/ansible-community/antsibull-nox/pull/67](https://github.com/ansible-community/antsibull-nox/pull/67) ). v0.2.0[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#v020 "Permanent link") -------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#release-summary_16 "Permanent link") Major extension and overhaul with many breaking changes. The next minor release is expected to bring more stabilization. ### Major Changes[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#major-changes_1 "Permanent link") * There is now a new function `antsibull_nox.load_antsibull_nox_toml()` which loads `antsibull-nox.toml` and creates configuration and sessions from it. Calling other functionality from `antsibull_nox` in `noxfile.py` is only necessary for creating own specialized sessions, or ansible-test sessions that cannot be created with the `antsibull_nox.add_all_ansible_test_*_test_sessions*()` type functions ([https://github.com/ansible-community/antsibull-nox/pull/50](https://github.com/ansible-community/antsibull-nox/pull/50) , [https://github.com/ansible-community/antsibull-nox/issues/34](https://github.com/ansible-community/antsibull-nox/issues/34) ). ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#minor-changes_13 "Permanent link") * Add descriptions to generated sessions that are shown when running `nox --list` ([https://github.com/ansible-community/antsibull-nox/pull/31](https://github.com/ansible-community/antsibull-nox/pull/31) ). * Add function `add_matrix_generator` which allows to generate matrixes for CI systems for ansible-test runs ([https://github.com/ansible-community/antsibull-nox/pull/32](https://github.com/ansible-community/antsibull-nox/pull/32) ). * Add several new functions to add ansible-test runs ([https://github.com/ansible-community/antsibull-nox/issues/5](https://github.com/ansible-community/antsibull-nox/issues/5) , [https://github.com/ansible-community/antsibull-nox/pull/32](https://github.com/ansible-community/antsibull-nox/pull/32) , [https://github.com/ansible-community/antsibull-nox/pull/41](https://github.com/ansible-community/antsibull-nox/pull/41) , [https://github.com/ansible-community/antsibull-nox/pull/45](https://github.com/ansible-community/antsibull-nox/pull/45) ). * Add shared workflow for running ansible-test from nox and generating the CI matrix from nox as well ([https://github.com/ansible-community/antsibull-nox/issues/35](https://github.com/ansible-community/antsibull-nox/issues/35) , [https://github.com/ansible-community/antsibull-nox/pull/37](https://github.com/ansible-community/antsibull-nox/pull/37) , [https://github.com/ansible-community/antsibull-nox/pull/38](https://github.com/ansible-community/antsibull-nox/pull/38) , [https://github.com/ansible-community/antsibull-nox/pull/48](https://github.com/ansible-community/antsibull-nox/pull/48) , [https://github.com/ansible-community/antsibull-nox/pull/53](https://github.com/ansible-community/antsibull-nox/pull/53) ). * Allow to add `yamllint` session to `lint` meta-session that checks YAML files, and YAML content embedded in plugins and sidecar docs ([https://github.com/ansible-community/antsibull-nox/pull/42](https://github.com/ansible-community/antsibull-nox/pull/42) ). * Allow to add ansible-lint session ([https://github.com/ansible-community/antsibull-nox/issues/40](https://github.com/ansible-community/antsibull-nox/issues/40) , [https://github.com/ansible-community/antsibull-nox/pull/49](https://github.com/ansible-community/antsibull-nox/pull/49) ). * Allow to disable using installed collections that are not checked out next to the current one by setting the environment variable `ANTSIBULL_NOX_IGNORE_INSTALLED_COLLECTIONS` to `true` ([https://github.com/ansible-community/antsibull-nox/pull/51](https://github.com/ansible-community/antsibull-nox/pull/51) ). * Collapse Galaxy importer's output in GitHub Actions ([https://github.com/ansible-community/antsibull-nox/pull/46](https://github.com/ansible-community/antsibull-nox/pull/46) ). * In the GitHub Action, no longer use installed collections, but only ones that have been checked out next to the current one. This avoids using collections that come with the Ansible community package installed in the default GHA image ([https://github.com/ansible-community/antsibull-nox/pull/51](https://github.com/ansible-community/antsibull-nox/pull/51) ). * The action allows to install additional Python versions with the new `extra-python-versions` option ([https://github.com/ansible-community/antsibull-nox/pull/32](https://github.com/ansible-community/antsibull-nox/pull/32) ). * The action allows to pass extra commands after `--` with the new `extra-args` option ([https://github.com/ansible-community/antsibull-nox/pull/32](https://github.com/ansible-community/antsibull-nox/pull/32) ). * antsibull-nox now automatically installs missing collections. It uses `.nox/.cache` to store the collection artifacts and the extracted collections ([https://github.com/ansible-community/antsibull-nox/pull/46](https://github.com/ansible-community/antsibull-nox/pull/46) , [https://github.com/ansible-community/antsibull-nox/pull/52](https://github.com/ansible-community/antsibull-nox/pull/52) , [https://github.com/ansible-community/antsibull-nox/issues/7](https://github.com/ansible-community/antsibull-nox/issues/7) ). * pydantic is now a required Python dependency of antsibull-nox ([https://github.com/ansible-community/antsibull-nox/pull/50](https://github.com/ansible-community/antsibull-nox/pull/50) ). * tomli is now a required Python dependency of antsibull-nox for Python versions 3.9 and 3.10 For Python 3.11+, the standard library tomllib will be used ([https://github.com/ansible-community/antsibull-nox/pull/50](https://github.com/ansible-community/antsibull-nox/pull/50) ). ### Deprecated Features[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#deprecated-features_1 "Permanent link") * All functions in `antsibull_nox.**` are deprecated except `antsibull_nox.load_antsibull_nox_toml()`, `antsibull_nox.add_ansible_test_session()`, and `antsibull_nox.sessions.prepare_collections()`. The other function will still work for the next minor release, but will then be removed. Use `antsibull-nox.toml` and `antsibull_nox.load_antsibull_nox_toml()` instead ([https://github.com/ansible-community/antsibull-nox/pull/50](https://github.com/ansible-community/antsibull-nox/pull/50) ). v0.1.0[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#v010 "Permanent link") -------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#release-summary_17 "Permanent link") Feature release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#minor-changes_14 "Permanent link") * A `build-import-check` session that builds and tries to import the collection with Galaxy Importer can be added with `add_build_import_check()` ([https://github.com/ansible-community/antsibull-nox/issues/15](https://github.com/ansible-community/antsibull-nox/issues/15) , [https://github.com/ansible-community/antsibull-nox/pull/17](https://github.com/ansible-community/antsibull-nox/pull/17) ). * A `docs-check` session that runs `antsibull-docs lint-collection-docs` can be added with `add_docs_check()` ([https://github.com/ansible-community/antsibull-nox/issues/8](https://github.com/ansible-community/antsibull-nox/issues/8) , [https://github.com/ansible-community/antsibull-nox/pull/14](https://github.com/ansible-community/antsibull-nox/pull/14) ). * A `extra-checks` session that runs extra checks such as `no-unwanted-files` or `action-groups` can be added with `add_extra_checks()` ([https://github.com/ansible-community/antsibull-nox/issues/8](https://github.com/ansible-community/antsibull-nox/issues/8) , [https://github.com/ansible-community/antsibull-nox/pull/14](https://github.com/ansible-community/antsibull-nox/pull/14) ). * A `license-check` session that runs `reuse` and checks for bad licenses can be added with `add_license_check()` ([https://github.com/ansible-community/antsibull-nox/issues/8](https://github.com/ansible-community/antsibull-nox/issues/8) , [https://github.com/ansible-community/antsibull-nox/pull/14](https://github.com/ansible-community/antsibull-nox/pull/14) ). * Allow to decide which sessions should be marked as default and which not ([https://github.com/ansible-community/antsibull-nox/issues/18](https://github.com/ansible-community/antsibull-nox/issues/18) , [https://github.com/ansible-community/antsibull-nox/pull/20](https://github.com/ansible-community/antsibull-nox/pull/20) ). * Allow to provide `extra_code_files` to `add_lint_sessions()` ([https://github.com/ansible-community/antsibull-nox/pull/14](https://github.com/ansible-community/antsibull-nox/pull/14) ). * Check whether we're running in CI using the generic `$CI` enviornment variable instead of `$GITHUB_ACTIONS`. `$CI` is set to `true` on Github Actions, Gitlab CI, and other CI systems ([https://github.com/ansible-community/antsibull-nox/pull/28](https://github.com/ansible-community/antsibull-nox/pull/28) ). * For running pylint and mypy, copy the collection and dependent collections into a new tree. This allows the collection repository to be checked out outside an approriate tree structure, and it also allows the dependent collections to live in another tree structure, as long as `ansible-galaxy collection list` can find them ([https://github.com/ansible-community/antsibull-nox/pull/1](https://github.com/ansible-community/antsibull-nox/pull/1) ). * When a collection checkout is not part of an `ansible_collections` tree, look for collections in adjacent directories of the form `.` that match the containing collection's FQCN ([https://github.com/ansible-community/antsibull-nox/issues/6](https://github.com/ansible-community/antsibull-nox/issues/6) , [https://github.com/ansible-community/antsibull-nox/pull/22](https://github.com/ansible-community/antsibull-nox/pull/22) ). * antsibull-nox now depends on antsibull-fileutils >= 1.2.0 ([https://github.com/ansible-community/antsibull-nox/pull/1](https://github.com/ansible-community/antsibull-nox/pull/1) ). ### Breaking Changes / Porting Guide[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#breaking-changes-porting-guide "Permanent link") * The nox workflow now by default runs all sessions, unless restricted with the `sessions` parameter ([https://github.com/ansible-community/antsibull-nox/pull/14](https://github.com/ansible-community/antsibull-nox/pull/14) ). ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#bugfixes_11 "Permanent link") * Make sure that black in CI checks formatting instead of just reformatting ([https://github.com/ansible-community/antsibull-nox/pull/14](https://github.com/ansible-community/antsibull-nox/pull/14) ). v0.0.1[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#v001 "Permanent link") -------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-nox/changelog/#release-summary_18 "Permanent link") Initial alpha release. --- # Installation - Ansible Development Tools Documentation [Skip to content](https://docs.ansible.com/projects/dev-tools/installation/#requirements) [](https://github.com/ansible/ansible-dev-tools/blob/main/docs/installation.md "Edit this page") [](https://github.com/ansible/ansible-dev-tools/raw/main/docs/installation.md "View source of this page") Installation ============ Requirements[¶](https://docs.ansible.com/projects/dev-tools/installation/#requirements "Permanent link") --------------------------------------------------------------------------------------------------------- * Python 3.10: ansible-dev-tools requires Python 3.10 or later. Make sure you have Python 3.10 installed on your system before proceeding. Installation[¶](https://docs.ansible.com/projects/dev-tools/installation/#installation "Permanent link") --------------------------------------------------------------------------------------------------------- `pip install ansible-dev-tools` Once installation is completed, see the [User Guide](https://docs.ansible.com/projects/dev-tools/user-guide/) for more details about ansible-dev-tools usage. ### Latest Releases[¶](https://docs.ansible.com/projects/dev-tools/installation/#latest-releases "Permanent link") * GitHub To view the latest releases, see the [ansible-dev-tools GitHub releases page](https://github.com/ansible/ansible-dev-tools/releases) . Each release includes detailed release notes outlining new features, improvements, and bug fixes. * PyPI The [PyPI page for ansible-dev-tools](https://pypi.org/project/ansible-dev-tools/) provides information on the latest stable release and allows you to download specific versions of the package. Upgrade[¶](https://docs.ansible.com/projects/dev-tools/installation/#upgrade "Permanent link") ----------------------------------------------------------------------------------------------- To upgrade ansible-dev-tools to the latest version, use the following pip command: `pip install --upgrade ansible-dev-tools` Downgrade[¶](https://docs.ansible.com/projects/dev-tools/installation/#downgrade "Permanent link") --------------------------------------------------------------------------------------------------- If needed, you can downgrade ansible-dev-tools to a specific version using the following pip command: `pip install ansible-dev-tools==desired-version` Uninstallation[¶](https://docs.ansible.com/projects/dev-tools/installation/#uninstallation "Permanent link") ------------------------------------------------------------------------------------------------------------- If you need to uninstall ansible-dev-tools, use the following pip command: `pip uninstall ansible-dev-tools` Usage[¶](https://docs.ansible.com/projects/dev-tools/installation/#usage "Permanent link") ------------------------------------------------------------------------------------------- In addition to installing each of the above tools, `ansible-dev-tools` provides an easy way to show the versions of the content creation tools that make up the current development environment. `[](https://docs.ansible.com/projects/dev-tools/installation/#__codelineno-0-1) $ adt --version [](https://docs.ansible.com/projects/dev-tools/installation/#__codelineno-0-2) ansible-builder 3.1.0 [](https://docs.ansible.com/projects/dev-tools/installation/#__codelineno-0-3) ansible-core 2.19.2 [](https://docs.ansible.com/projects/dev-tools/installation/#__codelineno-0-4) ansible-creator 25.8.0 [](https://docs.ansible.com/projects/dev-tools/installation/#__codelineno-0-5) ansible-dev-environment 25.8.0 [](https://docs.ansible.com/projects/dev-tools/installation/#__codelineno-0-6) ansible-dev-tools 25.8.4.dev6 [](https://docs.ansible.com/projects/dev-tools/installation/#__codelineno-0-7) ansible-lint 25.8.2 [](https://docs.ansible.com/projects/dev-tools/installation/#__codelineno-0-8) ansible-navigator 25.8.0 [](https://docs.ansible.com/projects/dev-tools/installation/#__codelineno-0-9) ansible-sign 0.1.2 [](https://docs.ansible.com/projects/dev-tools/installation/#__codelineno-0-10) molecule 25.7.0 [](https://docs.ansible.com/projects/dev-tools/installation/#__codelineno-0-11) pytest-ansible 25.8.0 [](https://docs.ansible.com/projects/dev-tools/installation/#__codelineno-0-12) tox-ansible 25.8.0` Back to top --- # Ansible SDK documentation — Ansible SDK Documentation * [AnsibleFest](https://www.ansible.com/ansiblefest) * [Products](https://www.ansible.com/tower) * [Community](https://www.ansible.com/community) * [Webinars & Training](https://www.ansible.com/webinars-training) * [Blog](https://www.ansible.com/blog) [![Ansible Logo](https://docs.ansible.com/projects/sdk/en/latest/_static/images/Ansible-Mark-RGB_White.svg)\ \ Ansible SDK Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/sdk/en/latest/#) * Ansible SDK documentation * [Edit on GitHub](https://github.com/ansible/ansible-sdk/blob/main/docs/source/index.rst) * * * Ansible SDK documentation[](https://docs.ansible.com/projects/sdk/en/latest/#ansible-sdk-documentation "Permalink to this heading") ===================================================================================================================================== Ansible SDK is a toolkit that lets you harness the power and simplicity of Ansible automation directly from your applications. Note Need help or want to discuss all things related to Ansible SDK? See the [Community guide](https://docs.ansible.com/projects/sdk/en/latest/community.html#community) and join the conversation! Table of contents: * [Ansible SDK](https://docs.ansible.com/projects/sdk/en/latest/intro.html) * [Installing Ansible SDK](https://docs.ansible.com/projects/sdk/en/latest/install.html) * [Running local automation jobs](https://docs.ansible.com/projects/sdk/en/latest/running_ansible_jobs.html) * [Running automation mesh jobs](https://docs.ansible.com/projects/sdk/en/latest/running_mesh_jobs.html) * [Troubleshooting](https://docs.ansible.com/projects/sdk/en/latest/troubleshooting.html) * [API Reference](https://docs.ansible.com/projects/sdk/en/latest/api.html) * [Community](https://docs.ansible.com/projects/sdk/en/latest/community.html) --- # ansible-sign — Ansible Sign Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/sign/en/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Sign Documentation](https://ansible.readthedocs.io/projects/sign/en/latest/) * [](https://docs.ansible.com/projects/sign/en/latest/#) * ansible-sign * [View page source](https://docs.ansible.com/projects/sign/en/latest/_sources/index.rst.txt) * * * ansible-sign[](https://docs.ansible.com/projects/sign/en/latest/#ansible-sign "Link to this heading") ======================================================================================================= This is the documentation for the **ansible-sign** utility used for signing and verifying Ansible content. Note Need help or want to discuss the project? See the [Community guide](https://docs.ansible.com/projects/sign/en/latest/community.html#community) to join the conversation! Contents[](https://docs.ansible.com/projects/sign/en/latest/#contents "Link to this heading") ----------------------------------------------------------------------------------------------- * [Community](https://docs.ansible.com/projects/sign/en/latest/community.html) * [Code of Conduct](https://docs.ansible.com/projects/sign/en/latest/community.html#code-of-conduct) * [Ansible Forum](https://docs.ansible.com/projects/sign/en/latest/community.html#ansible-forum) * [Contributions & Help](https://docs.ansible.com/projects/sign/en/latest/contributing.html) * [License](https://docs.ansible.com/projects/sign/en/latest/license.html) * [Authors](https://docs.ansible.com/projects/sign/en/latest/authors.html) * [Changelog](https://docs.ansible.com/projects/sign/en/latest/changelog.html) * [Version 1.0.0](https://docs.ansible.com/projects/sign/en/latest/changelog.html#version-1-0-0) * [Rundown (CLI Tutorial)](https://docs.ansible.com/projects/sign/en/latest/rundown.html) * [Adding a GPG key to AWX or Ansible Automation Controller](https://docs.ansible.com/projects/sign/en/latest/rundown.html#adding-a-gpg-key-to-awx-or-ansible-automation-controller) * [How to Access the `ansible-sign` CLI Utility](https://docs.ansible.com/projects/sign/en/latest/rundown.html#how-to-access-the-ansible-sign-cli-utility) * [The Project Directory](https://docs.ansible.com/projects/sign/en/latest/rundown.html#the-project-directory) * [Signing Content](https://docs.ansible.com/projects/sign/en/latest/rundown.html#signing-content) * [Verifying Content](https://docs.ansible.com/projects/sign/en/latest/rundown.html#verifying-content) * [Notes About Automation](https://docs.ansible.com/projects/sign/en/latest/rundown.html#notes-about-automation) * [API modules](https://docs.ansible.com/projects/sign/en/latest/api/modules.html) * [ansible\_sign package](https://docs.ansible.com/projects/sign/en/latest/api/ansible_sign.html) Indices and tables[](https://docs.ansible.com/projects/sign/en/latest/#indices-and-tables "Link to this heading") ------------------------------------------------------------------------------------------------------------------- * [Index](https://docs.ansible.com/projects/sign/en/latest/genindex.html) * [Module Index](https://docs.ansible.com/projects/sign/en/latest/py-modindex.html) * [Search Page](https://docs.ansible.com/projects/sign/en/latest/search.html) --- # Using - Ansible Lint Documentation [Skip to content](https://docs.ansible.com/projects/lint/usage/#using) [](https://github.com/ansible/ansible-lint/blob/main/docs/usage.md "Edit this page") [](https://github.com/ansible/ansible-lint/raw/main/docs/usage.md "View source of this page") Using[¶](https://docs.ansible.com/projects/lint/usage/#using "Permanent link") =============================================================================== Using commands[¶](https://docs.ansible.com/projects/lint/usage/#using-commands "Permanent link") ------------------------------------------------------------------------------------------------- After you install Ansible-lint, run `ansible-lint --help` to display available commands and their options. ``[](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-1) $ ansible-lint --help [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-2) usage: ansible-lint [-h] [-P | -L | -T] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-3) [-f {brief,full,md,json,codeclimate,quiet,pep8,sarif}] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-4) [--sarif-file SARIF_FILE] [-q] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-5) [--profile {min,basic,moderate,safety,shared,production}] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-6) [--project-dir PROJECT_DIR] [-r RULESDIR] [-R] [-s] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-7) [--fix [WRITE_LIST]] [--show-relpath] [-t TAGS] [-v] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-8) [-x SKIP_LIST] [--generate-ignore] [-w WARN_LIST] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-9) [--enable-list ENABLE_LIST] [--nocolor] [--force-color] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-10) [--exclude EXCLUDE_PATHS [EXCLUDE_PATHS ...]] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-11) [-c CONFIG_FILE] [-i IGNORE_FILE] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-12) [--yamllint-file YAMLLINT_FILE] [--offline | --no-offline] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-13) [--version] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-14) [lintables ...] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-15) [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-16) positional arguments: [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-17) lintables One or more files or paths. When missing it will enable auto-detection mode. [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-18) [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-19) options: [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-20) -h, --help show this help message and exit [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-21) -P, --list-profiles List all profiles. [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-22) -L, --list-rules List all the rules. [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-23) -T, --list-tags List all the tags and the rules they cover. [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-24) -f, --format {brief,full,md,json,codeclimate,quiet,pep8,sarif} [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-25) stdout formatting, json being an alias for codeclimate. (default: None) [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-26) --sarif-file SARIF_FILE [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-27) SARIF output file [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-28) -q quieter, reduce verbosity, can be specified twice. [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-29) --profile {min,basic,moderate,safety,shared,production} [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-30) Specify which rules profile to be used. [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-31) --project-dir PROJECT_DIR [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-32) Location of project/repository, autodetected based on location of configuration file. [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-33) -r, --rules-dir RULESDIR [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-34) Specify custom rule directories. Add -R to keep using embedded rules from /home/docs/checkouts/readthedocs.org/user_builds/ansible-lint/checkouts/latest/src/ansiblelint/rules [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-35) -R Keep default rules when using -r [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-36) -s, --strict Return non-zero exit code on warnings as well as errors [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-37) --fix [WRITE_LIST] Allow ansible-lint to perform auto-fixes, including YAML reformatting. You can limit the effective rule transforms (the 'write_list') by passing a keywords 'all' or 'none' or a comma separated list of rule ids or rule tags. YAML reformatting happens whenever '--fix' or '--fix=' is used. '--fix' and '--fix=all' are equivalent: they allow all transforms to run. Presence of --fix in command overrides config file value. [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-38) --show-relpath Display path relative to CWD [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-39) -t, --tags TAGS only check rules whose id/tags match these values [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-40) -v Increase verbosity level (-vv for more) [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-41) -x, --skip-list SKIP_LIST [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-42) only check rules whose id/tags do not match these values. e.g: --skip-list=name,run-once [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-43) --generate-ignore Generate a text file '.ansible-lint-ignore' that ignores all found violations. Each line contains filename and rule id separated by a space. [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-44) -w, --warn-list WARN_LIST [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-45) only warn about these rules, unless overridden in config file. Current version default value is: experimental, jinja[spacing], fqcn[deep] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-46) --enable-list ENABLE_LIST [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-47) activate optional rules by their tag name [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-48) --nocolor disable colored output, same as NO_COLOR=1 [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-49) --force-color Force colored output, same as FORCE_COLOR=1 [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-50) --exclude EXCLUDE_PATHS [EXCLUDE_PATHS ...] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-51) path to directories or files to skip. This option is repeatable. [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-52) -c, --config-file CONFIG_FILE [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-53) Specify configuration file to use. By default it will look for '.ansible-lint', '.ansible-lint.yml', '.ansible-lint.yaml', '.config/ansible-lint.yml', or '.config/ansible-lint.yaml' [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-54) -i, --ignore-file IGNORE_FILE [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-55) Specify ignore file to use. By default it will look for '.ansible-lint-ignore' or '.config/ansible-lint-ignore.txt' [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-56) --yamllint-file YAMLLINT_FILE [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-57) Specify yamllint config file to use. By default it will look for '.yamllint', '.yamllint.yaml', '.yamllint.yml', '~/.config/yamllint/config' or environment variables XDG_CONFIG_HOME and YAMLLINT_CONFIG_FILE. [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-58) --offline, --no-offline [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-59) Disable installation of requirements.yml and schema refreshing [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-60) --version [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-61) [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-62) The following environment variables are also recognized but there is no guarantee that they will work in future versions: [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-63) [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-64) ANSIBLE_LINT_CUSTOM_RULESDIR: Used for adding another folder into the lookup path for new rules. [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-65) [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-66) ANSIBLE_LINT_IGNORE_FILE: Define it to override the name of the default ignore file `.ansible-lint-ignore` [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-67) [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-68) ANSIBLE_LINT_WRITE_TMP: Tells linter to dump fixes into different temp files instead of overriding original. Used internally for testing. [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-69) [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-70) ANSIBLE_LINT_SKIP_SCHEMA_UPDATE: Tells ansible-lint to skip schema refresh. [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-71) [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-72) ANSIBLE_LINT_NODEPS: Avoids installing content dependencies and avoids performing checks that would fail when modules are not installed. Far less violations will be reported.`` ### Command output[¶](https://docs.ansible.com/projects/lint/usage/#command-output "Permanent link") Ansible-lint prints output on both `stdout` and `stderr`. * `stdout` displays rule violations. * `stderr` displays logging and free-form messages like statistics. Most `ansible-lint` examples use pep8 as the output format (`-f pep8`) which is machine parsable. Ansible-lint also print errors using their [annotation](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#setting-an-error-message) format when it detects the `GITHUB_ACTIONS=true` and `GITHUB_WORKFLOW=...` variables. Caching[¶](https://docs.ansible.com/projects/lint/usage/#caching "Permanent link") ----------------------------------------------------------------------------------- For optimal performance, Ansible-lint creates caches with installed or mocked roles, collections, and modules in the `{project_dir}/.cache` folder. The location of `{project_dir}` is passed with a command line argument, determined by the location of the configuration file, git project top-level directory, or user home directory. To perform faster re-runs, Ansible-lint does not automatically clean the cache. If required you can do this manually by simply deleting the `.cache` folder. Ansible-lint creates a new cache on the next invocation. You should add the `.cache` folder to the `.gitignore` file in your git repositories. Gradual adoption[¶](https://docs.ansible.com/projects/lint/usage/#gradual-adoption "Permanent link") ----------------------------------------------------------------------------------------------------- For an easier gradual adoption, adopters should consider [ignore file](https://docs.ansible.com/projects/lint/configuring/#ignoring-rules-for-entire-files "Ignoring rules for entire files") feature. This allows the quick introduction of a linter pipeline for preventing the addition of new violations, while known violations are ignored. Some people can work on addressing these historical violations while others may continue to work on other maintenance tasks. The deprecated `--progressive` mode was removed in v6.16.0 as it added code complexity and performance overhead. It also presented several corner cases where it failed to work as expected and caused false negatives. Linting playbooks and roles[¶](https://docs.ansible.com/projects/lint/usage/#linting-playbooks-and-roles "Permanent link") --------------------------------------------------------------------------------------------------------------------------- Execution Directory **Always run `ansible-lint` from the root of your project or collection.** As of version 25.7.0, running the linter from within a subdirectory (such as inside a `roles/` or `tasks/` folder) is not supported and may result in zero errors being reported even if violations exist. Ansible-lint recommends following the [collection structure layout](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_collections_structure.html#collection-structure) whether you plan to build a collection or not. Following that layout assures the best integration with all ecosystem tools because it helps those tools better distinguish between random YAML files and files managed by Ansible. When you call `ansible-lint` without arguments, it uses internal heuristics to determine file types. Pass the **roles** and **playbooks** that you want to lint as arguments to the `ansible-lint` command. For example, to lint `examples/playbooks/play.yml` and `examples/roles/bobbins`, use the following command: ``[](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-1) $ ansible-lint examples/playbooks/play.yml examples/roles/bobbins [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-2) WARNING Skipped installing collection dependencies due to running in offline mode. [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-3) WARNING Listing 6 violation(s) that are fatal [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-4) Read documentation for instructions on how to ignore specific rule violations. [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-5) [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-6) # Rule Violation Summary [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-7) [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-8) 1 command-instead-of-module profile:basic tags:command-shell,idiom [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-9) 1 name profile:basic tags:idiom [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-10) 1 latest profile:basic tags:idempotency [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-11) 1 no-changed-when profile:basic tags:command-shell,idempotency [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-12) 1 fqcn profile:basic tags:formatting [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-13) 1 args profile:basic tags:syntax,experimental [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-14) [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-15) Failed: 5 failure(s), 1 warning(s) in 4 files processed of 4 encountered. Last profile that met the validation criteria was 'min'. [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-16) name[play]: All plays should be named. [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-17) examples/playbooks/play.yml:2:3 [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-18) [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-19) command-instead-of-module: service used in place of service module [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-20) examples/playbooks/play.yml:5 Task/Handler: A bad play [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-21) [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-22) no-changed-when: Commands should not change things if nothing needs doing. [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-23) examples/playbooks/play.yml:5 Task/Handler: A bad play [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-24) [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-25) args[module]: missing required arguments: repo (warning) [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-26) examples/roles/bobbins/tasks/main.yml:2 Task/Handler: Test tasks [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-27) [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-28) latest[git]: Result of the command may vary on subsequent runs. [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-29) examples/roles/bobbins/tasks/main.yml:2 Task/Handler: Test tasks [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-30) [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-31) fqcn[action-core]: Use FQCN for builtin module actions (git). [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-32) examples/roles/bobbins/tasks/main.yml:3:11 Use `ansible.builtin.git` or `ansible.legacy.git` instead.`` Running example playbooks[¶](https://docs.ansible.com/projects/lint/usage/#running-example-playbooks "Permanent link") ----------------------------------------------------------------------------------------------------------------------- Ansible-lint includes an `ansible-lint/examples` folder that contains example playbooks with different rule violations and undesirable characteristics. You can run `ansible-lint` on the example playbooks to observe Ansible-lint in action, as follows: `[](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-1) $ ansible-lint --offline -f pep8 examples/playbooks/example.yml [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-2) WARNING Skipped installing collection dependencies due to running in offline mode. [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-3) WARNING Ignored exception from NameRule.matchyaml while processing examples/playbooks/example.yml (playbook): 'NoneType' object has no attribute 'get' [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-4) WARNING Listing 22 violation(s) that are fatal [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-5) Read documentation for instructions on how to ignore specific rule violations. [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-6) [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-7) # Rule Violation Summary [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-8) [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-9) 2 command-instead-of-module profile:basic tags:command-shell,idiom [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-10) 2 jinja profile:basic tags:formatting [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-11) 4 no-free-form profile:basic tags:syntax,risk [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-12) 1 schema profile:basic tags:core [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-13) 2 name profile:basic tags:idiom [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-14) 3 latest profile:basic tags:idempotency [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-15) 2 package-latest profile:basic tags:idempotency [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-16) 3 no-changed-when profile:basic tags:command-shell,idempotency [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-17) 3 args profile:basic tags:syntax,experimental [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-18) [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-19) Failed: 19 failure(s), 3 warning(s) in 1 files processed of 1 encountered. Last profile that met the validation criteria was 'min'. [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-20) examples/playbooks/example.yml:1: schema[playbook][/]: $[0].tasks[13] None is not of type 'object'[/] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-21) examples/playbooks/example.yml:9: no-changed-when: Commands should not change things if nothing needs doing. [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-22) examples/playbooks/example.yml:10:15: jinja[spacing][/]: Jinja2 spacing could be improved: echo {{this_variable}} is not set in this playbook -> echo {{ this_variable }} is not set in this playbook [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-23) examples/playbooks/example.yml:12: no-changed-when: Commands should not change things if nothing needs doing. [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-24) examples/playbooks/example.yml:15: args[module][/]: missing required arguments: repo (warning) [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-25) examples/playbooks/example.yml:15: latest[git][/]: Result of the command may vary on subsequent runs. [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-26) examples/playbooks/example.yml:18: args[module][/]: missing required arguments: repo (warning) [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-27) examples/playbooks/example.yml:18: latest[git][/]: Result of the command may vary on subsequent runs. [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-28) examples/playbooks/example.yml:21: args[module][/]: Unsupported parameters for (basic.py) module: bobbins. Supported parameters include: accept_hostkey, accept_newhostkey, archive, archive_prefix, bare, clone, depth, dest, executable, force, gpg_allowlist, key_file, recursive, reference, refspec, remote, repo, separate_git_dir, single_branch, ssh_opts, track_submodules, umask, update, verify_commit, version (gpg_whitelist, name). (warning) [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-29) examples/playbooks/example.yml:21: no-free-form: Avoid using free-form when calling module actions. (ansible.builtin.git) [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-30) examples/playbooks/example.yml:24: command-instead-of-module: git used in place of git module [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-31) examples/playbooks/example.yml:24: no-changed-when: Commands should not change things if nothing needs doing. [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-32) examples/playbooks/example.yml:27: command-instead-of-module: git used in place of git module [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-33) examples/playbooks/example.yml:30: latest[git][/]: Result of the command may vary on subsequent runs. [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-34) examples/playbooks/example.yml:34:15: jinja[spacing][/]: Jinja2 spacing could be improved: {{item}} -> {{ item }} [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-35) examples/playbooks/example.yml:39: no-free-form: Avoid using free-form when calling module actions. (ansible.builtin.dnf) [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-36) examples/playbooks/example.yml:39: package-latest: Package installs should not use latest. [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-37) examples/playbooks/example.yml:42: name[missing][/]: All tasks should be named. [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-38) examples/playbooks/example.yml:42: no-free-form: Avoid using free-form when calling module actions. (ansible.builtin.debug) [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-39) examples/playbooks/example.yml:44: no-free-form: Avoid using free-form when calling module actions. (ansible.builtin.apt) [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-40) examples/playbooks/example.yml:44: package-latest: Package installs should not use latest. [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-41) examples/playbooks/example.yml:47: name[missing][/]: All tasks should be named.` Ansible-lint also handles playbooks that include other playbooks, tasks, handlers, or roles, as the `examples/playbooks/include.yml` example demonstrates. `[](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-1) $ ansible-lint --offline -q -f pep8 examples/playbooks/include.yml [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-2) examples/playbooks/include.yml:13:7: syntax-check[specific][/]` Output formats[¶](https://docs.ansible.com/projects/lint/usage/#output-formats "Permanent link") ------------------------------------------------------------------------------------------------- ### pep8[¶](https://docs.ansible.com/projects/lint/usage/#pep8 "Permanent link") `[](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-1) $ ansible-lint --offline -q -f pep8 examples/playbooks/norole.yml [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-2) examples/playbooks/norole.yml:5:7: syntax-check[specific][/]` ### SARIF JSON[¶](https://docs.ansible.com/projects/lint/usage/#sarif-json "Permanent link") Using `--format sarif` or `--format json` the linter will output on stdout a report in [SARIF](https://docs.oasis-open.org/sarif/sarif/v2.1.0/csprd01/sarif-v2.1.0-csprd01.html) We also have an option `--sarif-file FILE` option that can make the linter dump the output to a file while not altering its normal stdout output. This can be used in CI/CD pipelines. SourceResult `[](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-1) ansible-lint --offline -q -f sarif examples/playbooks/norole.yml` `[](https://docs.ansible.com/projects/lint/usage/#__codelineno-1-1) {"$schema": "https://schemastore.azurewebsites.net/schemas/json/sarif-2.1.0-rtm.5.json", "version": "2.1.0", "runs": [{"tool": {"driver": {"name": "ansible-lint", "version": "26.3.1.dev12", "informationUri": "https://github.com/ansible/ansible-lint", "rules": [{"id": "syntax-check[specific]", "name": "syntax-check[specific]", "shortDescription": {"text": "the role 'node' was not found in /home/docs/checkouts/readthedocs.org/user_builds/ansible-lint/checkouts/latest/examples/playbooks/roles:/home/docs/checkouts/readthedocs.org/user_builds/ansible-lint/checkouts/latest/.ansible/roles:/home/docs/.ansible/roles:/usr/share/ansible/roles:/etc/ansible/roles:/home/docs/checkouts/readthedocs.org/user_builds/ansible-lint/checkouts/latest/examples/playbooks"}, "defaultConfiguration": {"level": "error"}, "help": {"text": ""}, "helpUri": "https://docs.ansible.com/projects/lint/rules/syntax-check/", "properties": {"tags": ["core", "unskippable"]}}]}}, "columnKind": "utf16CodeUnits", "results": [{"ruleId": "syntax-check[specific]", "level": "error", "message": {"text": "the role 'node' was not found in /home/docs/checkouts/readthedocs.org/user_builds/ansible-lint/checkouts/latest/examples/playbooks/roles:/home/docs/checkouts/readthedocs.org/user_builds/ansible-lint/checkouts/latest/.ansible/roles:/home/docs/.ansible/roles:/usr/share/ansible/roles:/etc/ansible/roles:/home/docs/checkouts/readthedocs.org/user_builds/ansible-lint/checkouts/latest/examples/playbooks"}, "locations": [{"physicalLocation": {"artifactLocation": {"uri": "examples/playbooks/norole.yml", "uriBaseId": "SRCROOT"}, "region": {"startLine": 5, "startColumn": 7}}}]}], "originalUriBaseIds": {"SRCROOT": {"uri": "file:///home/docs/checkouts/readthedocs.org/user_builds/ansible-lint/checkouts/latest/"}}}]}` ### Code Climate JSON[¶](https://docs.ansible.com/projects/lint/usage/#code-climate-json "Permanent link") You can generate `JSON` reports based on the [Code Climate](https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md#data-types) specification as the `examples/playbooks/norole.yml` example demonstrates. SourceResult `[](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-1) ansible-lint --offline -q -f codeclimate examples/playbooks/norole.yml` `[](https://docs.ansible.com/projects/lint/usage/#__codelineno-1-1) [{"type": "issue", "check_name": "syntax-check[specific]", "categories": ["core", "unskippable"], "url": "https://docs.ansible.com/projects/lint/rules/syntax-check/", "severity": "major", "description": "the role 'node' was not found in /home/docs/checkouts/readthedocs.org/user_builds/ansible-lint/checkouts/latest/examples/playbooks/roles:/home/docs/checkouts/readthedocs.org/user_builds/ansible-lint/checkouts/latest/.ansible/roles:/home/docs/.ansible/roles:/usr/share/ansible/roles:/etc/ansible/roles:/home/docs/checkouts/readthedocs.org/user_builds/ansible-lint/checkouts/latest/examples/playbooks", "fingerprint": "cd6fdb7a3be48e92851f6a1ec5355aef043390203ca47883d524fda5b95b36e6", "location": {"path": "examples/playbooks/norole.yml", "positions": {"begin": {"line": 5, "column": 7}}}}]` Historically `-f json` was used to generate Code Climate JSON reports but in newer versions we switched its meaning point SARIF JSON format instead. Warning When possible we recommend using the [SARIF](https://docs.ansible.com/projects/lint/usage/#sarif-json) format instead of the Code Climate as that one is more complete and has a full specification and also a JSON validation schema. Code Climate format does not expose our severity levels because we use that field to map warnings as `minor` and errors as `major` issues. Specifying rules at runtime[¶](https://docs.ansible.com/projects/lint/usage/#specifying-rules-at-runtime "Permanent link") --------------------------------------------------------------------------------------------------------------------------- By default, `ansible-lint` applies rules found in `ansible-lint/src/ansiblelint/rules`. Use the `-r /path/to/custom-rules` option to specify the directory path to a set of custom rules. For multiple custom rule sets, pass each set with a separate `-r` option. You can also combine the default rules with custom rules with the `-R` option along with one or more `-r` options. ### Including rules with tags[¶](https://docs.ansible.com/projects/lint/usage/#including-rules-with-tags "Permanent link") Each rule has an associated set of one or more tags. Use the `-T` option to view the list of tags for each available rule. You can then use the `-t` option to specify a tag and include the associated rules in the lint run. For example, the following `ansible-lint` command applies only the rules associated with the _idempotency_ tag: `[](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-1) $ ansible-lint -t idempotency playbook.yml [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-2) WARNING Skipped installing collection dependencies due to running in offline mode. [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-3) [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-4) Passed: 0 failure(s), 0 warning(s) in 1 files processed of 1 encountered. Last profile that met the validation criteria was 'production'.` The following shows the available tags in an example set of rules and the rules associated with each tag: ``[](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-1) ansible-lint -T 2>/dev/null [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-2) # List of tags and rules they cover [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-3) command-shell: # Specific to use of command and shell modules [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-4) - risky-shell-pipe [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-5) core: # Related to internal implementation of the linter [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-6) - schema[ansible-lint-config] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-7) - schema[ansible-navigator-config] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-8) - schema[changelog] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-9) - schema[execution-environment] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-10) - schema[galaxy] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-11) - schema[inventory] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-12) - schema[meta-runtime] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-13) - schema[meta] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-14) - schema[molecule] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-15) - schema[play-argspec] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-16) - schema[playbook] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-17) - schema[requirements] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-18) - schema[role-arg-spec] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-19) - schema[rulebook] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-20) - schema[tasks] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-21) - schema[vars] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-22) deprecations: # Indicate use of features that are removed from Ansible [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-23) - role-name[path] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-24) experimental: # Newly introduced rules, by default triggering only warnings [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-25) - only-builtins [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-26) formatting: # Related to code-style [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-27) - risky-octal [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-28) idempotency: # Possible indication that consequent runs would produce different results [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-29) - package-latest [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-30) idiom: # Anti-pattern detected, likely to cause undesired behavior [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-31) - var-naming[no-jinja] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-32) - var-naming[no-reserved] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-33) - var-naming[pattern] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-34) metadata: # Invalid metadata, likely related to galaxy, collections or roles [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-35) - role-name[path] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-36) opt-in: # Rules that are not used unless manually added to `enable_list` [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-37) - role-argument-spec [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-38) risk: [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-39) - no-free-form[raw-non-string] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-40) - no-free-form[raw] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-41) security: # Rules related to potential security issues, like exposing credentials [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-42) - no-log-password [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-43) syntax: # Related to wrong or deprecated syntax [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-44) - no-free-form[raw-non-string] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-45) - no-free-form[raw] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-46) unpredictability: # Warn about code that might not work in a predictable way [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-47) - risky-file-permissions [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-48) unskippable: # Indicate a fatal error that cannot be ignored or disabled [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-49) - syntax-check [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-50) yaml: # External linter which will also produce its own rule codes [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-51) - yaml[anchors] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-52) - yaml[braces] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-53) - yaml[brackets] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-54) - yaml[colons] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-55) - yaml[commas] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-56) - yaml[comments-indentation] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-57) - yaml[comments] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-58) - yaml[document-end] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-59) - yaml[document-start] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-60) - yaml[empty-lines] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-61) - yaml[empty-values] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-62) - yaml[float-values] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-63) - yaml[hyphens] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-64) - yaml[indentation] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-65) - yaml[key-duplicates] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-66) - yaml[key-ordering] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-67) - yaml[line-length] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-68) - yaml[new-line-at-end-of-file] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-69) - yaml[new-lines] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-70) - yaml[octal-values] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-71) - yaml[quoted-strings] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-72) - yaml[trailing-spaces] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-73) - yaml[truthy]`` ### Excluding rules with tags[¶](https://docs.ansible.com/projects/lint/usage/#excluding-rules-with-tags "Permanent link") To exclude rules by identifiers or tags, use the `-x SKIP_LIST` option. For example, the following command applies all rules except those with the _formatting_ and _metadata_ tags: `[](https://docs.ansible.com/projects/lint/usage/#__codelineno-0-1) $ ansible-lint -x formatting,metadata playbook.yml` ### Ignoring rules[¶](https://docs.ansible.com/projects/lint/usage/#ignoring-rules "Permanent link") To only warn about rules, use the `-w WARN_LIST` option. For example, the following command displays only warns about violations with rules associated with the `experimental` tag: `[](https://docs.ansible.com/projects/lint/usage/#__codelineno-1-1) $ ansible-lint -w experimental playbook.yml` By default, the `WARN_LIST` includes `['experimental', 'jinja[spacing]', 'fqcn[deep]']`. If you define a custom `WARN_LIST`, those defaults are replaced, so include any you want to keep to avoid those rules being treated as errors. Muting warnings to avoid false positives[¶](https://docs.ansible.com/projects/lint/usage/#muting-warnings-to-avoid-false-positives "Permanent link") ----------------------------------------------------------------------------------------------------------------------------------------------------- Not all linting rules are precise, some are general rules of thumb. Advanced _git_, _yum_ or _apt_ usage, for example, can be difficult to achieve in a playbook. In cases like this, Ansible-lint can incorrectly trigger rule violations. To disable rule violations for specific tasks, and mute false positives, add `# noqa: [rule_id]` to the end of the line. It is best practice to add a comment that explains why rules are disabled. You can add the `# noqa: [rule_id]` comment to the end of any line in a task. You can also skip multiple rules with a space-separated list. `[](https://docs.ansible.com/projects/lint/usage/#__codelineno-2-1) - name: This task would typically fire git-latest and partial-become rules [](https://docs.ansible.com/projects/lint/usage/#__codelineno-2-2) become_user: alice # noqa: git-latest partial-become [](https://docs.ansible.com/projects/lint/usage/#__codelineno-2-3) ansible.builtin.git: src=/path/to/git/repo dest=checkout` If the rule is line-based, `# noqa: [rule_id]` must be at the end of the line. `[](https://docs.ansible.com/projects/lint/usage/#__codelineno-3-1) - name: This would typically fire jinja[spacing] [](https://docs.ansible.com/projects/lint/usage/#__codelineno-3-2) get_url: [](https://docs.ansible.com/projects/lint/usage/#__codelineno-3-3) url: http://example.com/file.conf [](https://docs.ansible.com/projects/lint/usage/#__codelineno-3-4) dest: "{{dest_proj_path}}/foo.conf" # noqa: jinja[spacing]` If you want Ansible-lint to skip a rule entirely, use the `-x` command line argument or add it to `skip_list` in your configuration. The least preferred method of skipping rules is to skip all task-based rules for a task, which does not skip line-based rules. You can use the `skip_ansible_lint` tag with all tasks, for example: `[](https://docs.ansible.com/projects/lint/usage/#__codelineno-4-1) - name: This would typically fire no-free-form [](https://docs.ansible.com/projects/lint/usage/#__codelineno-4-2) command: warn=no chmod 644 X [](https://docs.ansible.com/projects/lint/usage/#__codelineno-4-3) [](https://docs.ansible.com/projects/lint/usage/#__codelineno-4-4) - name: This would typically fire git-latest [](https://docs.ansible.com/projects/lint/usage/#__codelineno-4-5) git: src=/path/to/git/repo dest=checkout [](https://docs.ansible.com/projects/lint/usage/#__codelineno-4-6) tags: [](https://docs.ansible.com/projects/lint/usage/#__codelineno-4-7) - skip_ansible_lint` Applying profiles[¶](https://docs.ansible.com/projects/lint/usage/#applying-profiles "Permanent link") ------------------------------------------------------------------------------------------------------- Ansible-lint profiles allow content creators to progressively improve the quality of Ansible playbooks, roles, and collections. During early development cycles, you need Ansible-lint rules to be less strict. Starting with the minimal profile ensures that Ansible can load your content. As you move to the next stage of developing content, you can gradually apply profiles to avoid common pitfalls and brittle complexity. Then, when you are ready to publish or share your content, you can use the `shared` and `production` profiles with much stricter rules. These profiles harden security, guarantee reliability, and ensure your Ansible content is easy for others to contribute to and use. Note Tags such as `opt-in` and `experimental` do not take effect for rules that are included in profiles, directly or indirectly. If a rule is in a profile, Ansible-lint applies that rule to the content. After you install and configure `ansible-lint`, you can apply profiles as follows: 1. View available profiles with the `--list-profiles` flag. `[](https://docs.ansible.com/projects/lint/usage/#__codelineno-5-1) ansible-lint --list-profiles` 1. Specify a profile with the `--profile` parameter to lint your content with those rules, for example: 2. Enforce standard styles and formatting with the `basic` profile. `[](https://docs.ansible.com/projects/lint/usage/#__codelineno-6-1) ansible-lint --profile=basic` * Ensure automation consistency, reliability, and security with the `safety` profile. `[](https://docs.ansible.com/projects/lint/usage/#__codelineno-7-1) ansible-lint --profile=safety` Vaults[¶](https://docs.ansible.com/projects/lint/usage/#vaults "Permanent link") --------------------------------------------------------------------------------- As ansible-lint executes ansible, it also needs access to encrypted secrets. If you do not give access to them or you are concerned about security implications, you should consider refactoring your code to allow it to be linted without access to real secrets: * Configure dummy fallback values that are used during linting, so Ansible will not complain about undefined variables. * Exclude the problematic files from the linting process. `[](https://docs.ansible.com/projects/lint/usage/#__codelineno-8-1) --- [](https://docs.ansible.com/projects/lint/usage/#__codelineno-8-2) # Example of avoiding undefined variable error [](https://docs.ansible.com/projects/lint/usage/#__codelineno-8-3) foo: "{{ undefined_variable_name | default('dummy') }}"` Keep in mind that a well-written playbook or role should allow Ansible's syntax check from passing on it, even if you do not have access to the vault. Internally ansible-lint runs `ansible-playbook --syntax-check` on each playbook and also on roles. As ansible-code does not support running syntax-check directly on roles, the linter will create temporary playbooks that only include each role from your project. You will need to change the code of the role in a way that it does not produce syntax errors when called without any variables or arguments. This usually involves making use of `defaults/` but be sure that you fully understand [variable precedence](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#understanding-variable-precedence) . Dependencies and requirements[¶](https://docs.ansible.com/projects/lint/usage/#dependencies-and-requirements "Permanent link") ------------------------------------------------------------------------------------------------------------------------------- Ansible-lint will recognize `requirements.yml` files used for runtime and testing purposes and install them automatically. Valid locations for these files are: * [`requirements.yml`](https://docs.ansible.com/projects/ansible/latest/galaxy/user_guide.html#installing-roles-and-collections-from-the-same-requirements-yml-file) * `roles/requirements.yml` * `collections/requirements.yml` * `tests/requirements.yml` * `tests/integration/requirements.yml` * `tests/unit/requirements.yml` * [`galaxy.yml`](https://docs.ansible.com/projects/ansible/latest/dev_guide/collections_galaxy_meta.html) Back to top --- # Developer Documentation — Ansible Runner Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/runner/en/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Runner Documentation](https://docs.ansible.com/projects/runner/en/stable/) * [](https://docs.ansible.com/projects/runner/en/latest/) * Developer Documentation * [View page source](https://docs.ansible.com/projects/runner/en/latest/_sources/modules.rst.txt) * * * Developer Documentation[](https://docs.ansible.com/projects/runner/en/latest/modules/#developer-documentation "Link to this heading") ======================================================================================================================================= * [ansible\_runner package](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/) * [Subpackages](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/#subpackages) * [ansible\_runner.config package](https://docs.ansible.com/projects/runner/en/latest/ansible_runner.config/) * [ansible\_runner.display\_callback package](https://docs.ansible.com/projects/runner/en/latest/ansible_runner.display_callback/) * [Submodules](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/#submodules) * [ansible\_runner.exceptions module](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/#module-ansible_runner.exceptions) * [ansible\_runner.interface module](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/#module-ansible_runner.interface) * [ansible\_runner.loader module](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/#module-ansible_runner.loader) * [ansible\_runner.runner module](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/#module-ansible_runner.runner) * [ansible\_runner.runner\_config module](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/#module-ansible_runner.runner_config) * [ansible\_runner.utils module](https://docs.ansible.com/projects/runner/en/latest/ansible_runner/#module-ansible_runner.utils) --- # Developers | Ansible documentation | Ansible documentation Join us at [Red Hat Summit in Atlanta](https://www.redhat.com/en/summit?sc_id=RHCTE0250000464461) to learn about Ansible Automation Platform | May 11-14, 2026 Developers ---------- Extend automation with custom Ansible modules, add functionality to existing modules, or fix bugs to improve existing code. Top links for developers ------------------------ [Developing modules](https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_general.html) [Ansible and Python 3](https://docs.ansible.com/ansible/latest/dev_guide/developing_python_3.html) [Python API](https://docs.ansible.com/ansible/latest/dev_guide/developing_api.html) * * * ### Start writing code [Set up your development environment](https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_general.html#environment-setup) [Learn how Ansible works](https://docs.ansible.com/ansible/latest/dev_guide/overview_architecture.html) [Write custom modules or plugins](https://docs.ansible.com/ansible/latest/dev_guide/developing_locally.html) ### Contribute code to a collection [Make your first contribution](https://docs.ansible.com/ansible/latest/community/contributor_path.html#making-your-first-contribution) [Explore the Collection contributor guide](https://docs.ansible.com/ansible/latest/community/contributions_collections.html) [Contribute your module to an existing collection](https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_checklist.html) [Review the lifecycle of an Ansible module or plugin](https://docs.ansible.com/ansible/latest/dev_guide/module_lifecycle.html) ### Test plugins and modules [Understand testing in Ansible](https://docs.ansible.com/ansible/latest/dev_guide/testing.html#why-test-your-ansible-contributions) [Run sanity tests](https://docs.ansible.com/ansible/latest/dev_guide/testing_sanity.html) [Write integration tests](https://docs.ansible.com/ansible/latest/dev_guide/testing_integration.html#testing-integration) [Write unit tests](https://docs.ansible.com/ansible/latest/dev_guide/testing_units.html#testing-units) ### Create new collections [Set things up with the collection skeleton](https://docs.ansible.com/ansible/latest/dev_guide/developing_collections_creating.html#creating-collections-skeleton) [Test your collection for code quality](https://docs.ansible.com/ansible/latest/dev_guide/developing_collections_testing.html) [Publish your collection on a distribution server](https://docs.ansible.com/ansible/devel/dev_guide/developing_collections_distributing.html#initial-configuration-of-your-distribution-server-or-servers) [Request a collection be added to the Ansible package](https://github.com/ansible-collections/ansible-inclusion) * [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) * [Privacy policy](https://www.redhat.com/en/about/privacy-policy) * [Code of conduct](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html) Sponsored by [![Red Hat logo.](https://docs.ansible.com/assets/images/redhat_reversed.svg)](https://www.redhat.com/en/technologies/management/ansible?sc_id=RHCTE0250000464439) --- # Installing - Ansible Lint Documentation [Skip to content](https://docs.ansible.com/projects/lint/installing/#installing) [](https://github.com/ansible/ansible-lint/blob/main/docs/installing.md "Edit this page") [](https://github.com/ansible/ansible-lint/raw/main/docs/installing.md "View source of this page") Installing[¶](https://docs.ansible.com/projects/lint/installing/#installing "Permanent link") ============================================================================================== Install Ansible-lint to apply rules and follow best practices with your automation content. Note Ansible-lint does not currently support installation on Windows systems. Warning Ansible-lint does not support any installation methods that are not mentioned in this document. Before raising any bugs related to installation, review all of the following details: * You should use the installation methods outlined in this document only. * You should upgrade the Python installer (`pip` or `pipx`) to the latest version available from pypi.org. If you use a system package manager, you will need to upgrade the installer to a newer version. * If you are installing from a git zip archive, which is not supported but should work, ensure you use the main branch and the latest version of pip and setuptools. * If you are installing Ansible-lint within a container or system package, you should not report the issue here. Contact the relevant container or package provider instead. * If you are using [poetry](https://python-poetry.org/) , read this [discussion](https://github.com/ansible/ansible-lint/discussions/2820#discussioncomment-4400380) . Pull requests to improve installation instructions are welcome. Any new issues related to the installation will be closed and locked. For a container image, we recommend using [community-ansible-dev-tools](https://docs.ansible.com/projects/dev-tools/container/) which includes `ansible-dev-tools` (it combines critical Ansible development packages into a unified Python package). If you have a use case that the `community-ansible-dev-tools` container doesn't satisfy, please contact the team through the [discussion](https://github.com/ansible/ansible-lint/discussions) forum. You can also run Ansible-lint on your source code with the [Ansible-lint GitHub action](https://github.com/marketplace/actions/run-ansible-lint) instead of installing it directly. Installing the latest version[¶](https://docs.ansible.com/projects/lint/installing/#installing-the-latest-version "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------ Recommendation The **recommended** approach to install `ansible-lint` is using the `ansible-dev-tools` package. [Ansible Development Tools](https://docs.ansible.com/projects/dev-tools/) aims to streamline the setup and usage of several tools needed in order to create [Ansible](https://www.ansible.com/) content. It combines critical Ansible development packages into a unified Python package. `[](https://docs.ansible.com/projects/lint/installing/#__codelineno-0-1) # This also installs ansible-core if it is not already installed [](https://docs.ansible.com/projects/lint/installing/#__codelineno-0-2) pip3 install ansible-dev-tools` You can install the most recent version of Ansible-lint with the [pip3](https://pypi.org/project/pip/) or [pipx](https://pypa.github.io/pipx/) Python package manager. Use [pipx](https://pypa.github.io/pipx/) to isolate Ansible-lint from your current Python environment as an alternative to creating a virtual environment. `[](https://docs.ansible.com/projects/lint/installing/#__codelineno-1-1) # This also installs ansible-core if it is not already installed [](https://docs.ansible.com/projects/lint/installing/#__codelineno-1-2) pip3 install ansible-lint` Note If you want to install the exact versions of all dependencies that were used to test a specific version of ansible-lint, you can add `lock` extra. This will only work with Python 3.10 or newer. Do this only inside a virtual environment. `[](https://docs.ansible.com/projects/lint/installing/#__codelineno-2-1) pip3 install "ansible-lint[lock]"` Installing on Fedora and RHEL[¶](https://docs.ansible.com/projects/lint/installing/#installing-on-fedora-and-rhel "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------ You can install Ansible-lint on Fedora, or Red Hat Enterprise Linux (RHEL) with the `dnf` package manager. `[](https://docs.ansible.com/projects/lint/installing/#__codelineno-3-1) dnf install ansible-lint` Note On RHEL, `ansible-lint` package is part of "Red Hat Ansible Automation Platform" subscription, which needs to be activated. Installing from source code[¶](https://docs.ansible.com/projects/lint/installing/#installing-from-source-code "Permanent link") -------------------------------------------------------------------------------------------------------------------------------- **Note**: `pip>=22.3.1` is required for installation from the source repository. Please consult the [PyPA User Guide](https://packaging.python.org/en/latest/tutorials/installing-packages/#ensure-pip-setuptools-and-wheel-are-up-to-date) to learn more about managing Pip versions. `[](https://docs.ansible.com/projects/lint/installing/#__codelineno-4-1) pip3 install git+https://github.com/ansible/ansible-lint` Installing Ansible Lint as a GitHub Action[¶](https://docs.ansible.com/projects/lint/installing/#installing-ansible-lint-as-a-github-action "Permanent link") -------------------------------------------------------------------------------------------------------------------------------------------------------------- To use the action simply create a file `.github/workflows/ansible-lint.yml` with content similar to the example below: `[](https://docs.ansible.com/projects/lint/installing/#__codelineno-5-1) # .github/workflows/ansible-lint.yml [](https://docs.ansible.com/projects/lint/installing/#__codelineno-5-2) name: ansible-lint [](https://docs.ansible.com/projects/lint/installing/#__codelineno-5-3) on: [](https://docs.ansible.com/projects/lint/installing/#__codelineno-5-4) pull_request: [](https://docs.ansible.com/projects/lint/installing/#__codelineno-5-5) branches: ["stable", "release/v*"] [](https://docs.ansible.com/projects/lint/installing/#__codelineno-5-6) jobs: [](https://docs.ansible.com/projects/lint/installing/#__codelineno-5-7) build: [](https://docs.ansible.com/projects/lint/installing/#__codelineno-5-8) name: Ansible Lint # Naming the build is important to use it as a status check [](https://docs.ansible.com/projects/lint/installing/#__codelineno-5-9) runs-on: ubuntu-24.04 [](https://docs.ansible.com/projects/lint/installing/#__codelineno-5-10) steps: [](https://docs.ansible.com/projects/lint/installing/#__codelineno-5-11) - uses: actions/checkout@v4 [](https://docs.ansible.com/projects/lint/installing/#__codelineno-5-12) - name: Run ansible-lint [](https://docs.ansible.com/projects/lint/installing/#__codelineno-5-13) uses: ansible/ansible-lint@main [](https://docs.ansible.com/projects/lint/installing/#__codelineno-5-14) # optional (see below): [](https://docs.ansible.com/projects/lint/installing/#__codelineno-5-15) with: [](https://docs.ansible.com/projects/lint/installing/#__codelineno-5-16) args: "" [](https://docs.ansible.com/projects/lint/installing/#__codelineno-5-17) setup_python: "true" [](https://docs.ansible.com/projects/lint/installing/#__codelineno-5-18) python_version: "3.14" [](https://docs.ansible.com/projects/lint/installing/#__codelineno-5-19) working_directory: "" [](https://docs.ansible.com/projects/lint/installing/#__codelineno-5-20) requirements_file: ""` All the arguments are optional and most users should not need them: * `args`: Arguments to be passed to ansible-lint command. * `setup_python`: If python should be installed. Default is `true`. * `python_version`: Python version to be installed. Default is `3.14`. * `working_directory`: The directory where to run ansible-lint from. Default is `github.workspace`. That might be needed if you want to lint only a subset of your repository. * `requirements_file`: Path to the requirements.yml file to install role and collection dependencies. Due to limitations on how GitHub Actions are processing arguments, we do not plan to provide extra options. You will have to make use of [ansible-lint own configuration file](https://docs.ansible.com/projects/lint/configuring/) to alter its behavior. ### Installing roles and collections from private repositories[¶](https://docs.ansible.com/projects/lint/installing/#installing-roles-and-collections-from-private-repositories "Permanent link") To install roles and collections from private repositories, you can: 1. Create an [access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#about-personal-access-tokens) 2. Add the token as an [deploy secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository) 3. Add the following step before the ansible-lint step. `[](https://docs.ansible.com/projects/lint/installing/#__codelineno-6-1) - name: Prepare Git for Github [](https://docs.ansible.com/projects/lint/installing/#__codelineno-6-2) shell: bash [](https://docs.ansible.com/projects/lint/installing/#__codelineno-6-3) run: | [](https://docs.ansible.com/projects/lint/installing/#__codelineno-6-4) git config --global url."https://${{ secrets.ANSIBLE_LINT_TOKEN }}@github.com".insteadOf "https://github.com"` Back to top --- # Welcome to Ansible Rulebook documentation — Ansible Rulebook Documentation * [AnsibleFest](https://www.ansible.com/ansiblefest) * [Products](https://www.ansible.com/tower) * [Community](https://www.ansible.com/community) * [Webinars & Training](https://www.ansible.com/webinars-training) * [Blog](https://www.ansible.com/blog) [![Ansible Logo](https://docs.ansible.com/projects/rulebook/en/v1.2.0/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Rulebook Documentation](https://ansible-rulebook.readthedocs.io/en/latest/) * [](https://docs.ansible.com/projects/rulebook/en/v1.2.0/#) * Welcome to Ansible Rulebook documentation * [View page source](https://docs.ansible.com/projects/rulebook/en/v1.2.0/_sources/index.rst.txt) * * * Welcome to Ansible Rulebook documentation[](https://docs.ansible.com/projects/rulebook/en/v1.2.0/#welcome-to-ansible-rulebook-documentation "Link to this heading") ===================================================================================================================================================================== Contents: * [Introduction](https://docs.ansible.com/projects/rulebook/en/v1.2.0/introduction.html) * [What is Event-Driven Ansible?](https://docs.ansible.com/projects/rulebook/en/v1.2.0/introduction.html#what-is-event-driven-ansible) * [Why Event-Driven?](https://docs.ansible.com/projects/rulebook/en/v1.2.0/introduction.html#why-event-driven) * [Why Rulebooks?](https://docs.ansible.com/projects/rulebook/en/v1.2.0/introduction.html#why-rulebooks) * [Getting started](https://docs.ansible.com/projects/rulebook/en/v1.2.0/introduction.html#getting-started) * [Other Resources](https://docs.ansible.com/projects/rulebook/en/v1.2.0/introduction.html#other-resources) * [Getting started](https://docs.ansible.com/projects/rulebook/en/v1.2.0/getting_started.html) * [Hello world!](https://docs.ansible.com/projects/rulebook/en/v1.2.0/getting_started.html#hello-world) * [A webhook example](https://docs.ansible.com/projects/rulebook/en/v1.2.0/getting_started.html#a-webhook-example) * [Installation](https://docs.ansible.com/projects/rulebook/en/v1.2.0/installation.html) * [Pulling the container image](https://docs.ansible.com/projects/rulebook/en/v1.2.0/installation.html#pulling-the-container-image) * [Installing with `pip`](https://docs.ansible.com/projects/rulebook/en/v1.2.0/installation.html#installing-with-pip) * [Development environment](https://docs.ansible.com/projects/rulebook/en/v1.2.0/development_environment.html) * [Building the container image](https://docs.ansible.com/projects/rulebook/en/v1.2.0/development_environment.html#building-the-container-image) * [Git pre-commit hooks](https://docs.ansible.com/projects/rulebook/en/v1.2.0/development_environment.html#git-pre-commit-hooks) * [Contributing](https://docs.ansible.com/projects/rulebook/en/v1.2.0/contributing.html) * [Getting in touch](https://docs.ansible.com/projects/rulebook/en/v1.2.0/contributing.html#getting-in-touch) * [Types of Contributions](https://docs.ansible.com/projects/rulebook/en/v1.2.0/contributing.html#types-of-contributions) * [Usage](https://docs.ansible.com/projects/rulebook/en/v1.2.0/usage.html) * [Rulebooks](https://docs.ansible.com/projects/rulebook/en/v1.2.0/rulebooks.html) * [Rulesets](https://docs.ansible.com/projects/rulebook/en/v1.2.0/rulebooks.html#rulesets) * [Including multiple sources](https://docs.ansible.com/projects/rulebook/en/v1.2.0/rulebooks.html#including-multiple-sources) * [Using vaulted strings](https://docs.ansible.com/projects/rulebook/en/v1.2.0/rulebooks.html#using-vaulted-strings) * [Rules](https://docs.ansible.com/projects/rulebook/en/v1.2.0/rules.html) * [Conditions](https://docs.ansible.com/projects/rulebook/en/v1.2.0/conditions.html) * [Supported data types](https://docs.ansible.com/projects/rulebook/en/v1.2.0/conditions.html#supported-data-types) * [Navigate structured data](https://docs.ansible.com/projects/rulebook/en/v1.2.0/conditions.html#navigate-structured-data) * [Supported Operators](https://docs.ansible.com/projects/rulebook/en/v1.2.0/conditions.html#supported-operators) * [Examples](https://docs.ansible.com/projects/rulebook/en/v1.2.0/conditions.html#examples) * [FAQ](https://docs.ansible.com/projects/rulebook/en/v1.2.0/conditions.html#faq) * [Events and Facts](https://docs.ansible.com/projects/rulebook/en/v1.2.0/events_and_facts.html) * [Differences between Events and Facts](https://docs.ansible.com/projects/rulebook/en/v1.2.0/events_and_facts.html#differences-between-events-and-facts) * [Variables](https://docs.ansible.com/projects/rulebook/en/v1.2.0/variables.html) * [Accessing variables in your rulebook](https://docs.ansible.com/projects/rulebook/en/v1.2.0/variables.html#accessing-variables-in-your-rulebook) * [Providing extra vars to actions](https://docs.ansible.com/projects/rulebook/en/v1.2.0/variables.html#providing-extra-vars-to-actions) * [Using vaulted strings for variables](https://docs.ansible.com/projects/rulebook/en/v1.2.0/variables.html#using-vaulted-strings-for-variables) * [Limiting hosts](https://docs.ansible.com/projects/rulebook/en/v1.2.0/host_limit.html) * [Inserting hosts to meta](https://docs.ansible.com/projects/rulebook/en/v1.2.0/host_limit.html#inserting-hosts-to-meta) * [Matching multiple events](https://docs.ansible.com/projects/rulebook/en/v1.2.0/multi_events.html) * [Actions](https://docs.ansible.com/projects/rulebook/en/v1.2.0/actions.html) * [run\_playbook](https://docs.ansible.com/projects/rulebook/en/v1.2.0/actions.html#run-playbook) * [run\_module](https://docs.ansible.com/projects/rulebook/en/v1.2.0/actions.html#run-module) * [run\_job\_template](https://docs.ansible.com/projects/rulebook/en/v1.2.0/actions.html#run-job-template) * [run\_workflow\_template](https://docs.ansible.com/projects/rulebook/en/v1.2.0/actions.html#run-workflow-template) * [post\_event](https://docs.ansible.com/projects/rulebook/en/v1.2.0/actions.html#post-event) * [set\_fact](https://docs.ansible.com/projects/rulebook/en/v1.2.0/actions.html#set-fact) * [retract\_fact](https://docs.ansible.com/projects/rulebook/en/v1.2.0/actions.html#retract-fact) * [print\_event](https://docs.ansible.com/projects/rulebook/en/v1.2.0/actions.html#print-event) * [shutdown](https://docs.ansible.com/projects/rulebook/en/v1.2.0/actions.html#shutdown) * [Results](https://docs.ansible.com/projects/rulebook/en/v1.2.0/actions.html#results) * [debug](https://docs.ansible.com/projects/rulebook/en/v1.2.0/actions.html#debug) * [none](https://docs.ansible.com/projects/rulebook/en/v1.2.0/actions.html#none) * [FAQ](https://docs.ansible.com/projects/rulebook/en/v1.2.0/actions.html#faq) * [How to Develop a Custom Plugin](https://docs.ansible.com/projects/rulebook/en/v1.2.0/sources.html) * [Best Practices and Patterns](https://docs.ansible.com/projects/rulebook/en/v1.2.0/sources.html#best-practices-and-patterns) * [Plugin template](https://docs.ansible.com/projects/rulebook/en/v1.2.0/sources.html#plugin-template) * [Plugin entrypoint](https://docs.ansible.com/projects/rulebook/en/v1.2.0/sources.html#plugin-entrypoint) * [Distributing plugins](https://docs.ansible.com/projects/rulebook/en/v1.2.0/sources.html#distributing-plugins) * [Document plugins](https://docs.ansible.com/projects/rulebook/en/v1.2.0/sources.html#document-plugins) * [Event Filters](https://docs.ansible.com/projects/rulebook/en/v1.2.0/filters.html) * [Builtin Event Filters](https://docs.ansible.com/projects/rulebook/en/v1.2.0/filters.html#builtin-event-filters) * [Runner](https://docs.ansible.com/projects/rulebook/en/v1.2.0/runner.html) * [Rulebook and Collections](https://docs.ansible.com/projects/rulebook/en/v1.2.0/collections.html) * [The structure of a Collection with Rulebook content](https://docs.ansible.com/projects/rulebook/en/v1.2.0/collections.html#the-structure-of-a-collection-with-rulebook-content) * [Using a rulebook included in a collection](https://docs.ansible.com/projects/rulebook/en/v1.2.0/collections.html#using-a-rulebook-included-in-a-collection) * [Decision Environment](https://docs.ansible.com/projects/rulebook/en/v1.2.0/decision_environment.html) * [Using your own rulebooks and projects with the decision environment](https://docs.ansible.com/projects/rulebook/en/v1.2.0/decision_environment.html#using-your-own-rulebooks-and-projects-with-the-decision-environment) Indices and tables[](https://docs.ansible.com/projects/rulebook/en/v1.2.0/#indices-and-tables "Link to this heading") ======================================================================================================================= * [Module Index](https://docs.ansible.com/projects/rulebook/en/v1.2.0/py-modindex.html) * [Search Page](https://docs.ansible.com/projects/rulebook/en/v1.2.0/search.html) --- # Ansible ecosystem | Ansible documentation Join us at [Red Hat Summit in Atlanta](https://www.redhat.com/en/summit?sc_id=RHCTE0250000464461) to learn about Ansible Automation Platform | May 11-14, 2026 Ansible ecosystem ================= Expand your automation to a virtually unlimited set of use cases. ### Awesome Ansible A collaborative curated list of awesome Ansible resources, tools, roles, tutorials and other related content. * [Awesome Ansible list](https://github.com/ansible-community/awesome-ansible/blob/main/README.md) ![Ansible community logo](https://docs.ansible.com/images/project-logos/ansible-community.svg) ### Ansible community package The Ansible community package consists of ansible-core and a set of Ansible collections published as the Python \`ansible\` package, in tradition of the Ansible 2.9 and earlier "batteries included" releases. * [PyPI page for Ansible community package](https://pypi.org/project/ansible/) * [Documentation of package build process](https://docs.ansible.com/projects/ansible-build-data/) * [Source code of package build](https://github.com/ansible-community/ansible-build-data) * [Source code of the Antsibull build tool](https://github.com/ansible-community/antsibull) ![Ansible community logo](https://docs.ansible.com/images/project-logos/ansible-community.svg) ### Antsibull Changelog A changelog generator used by ansible-core and Ansible collections. * [Documentation](https://docs.ansible.com/projects/antsibull-changelog/) * [Source code](https://github.com/ansible-community/antsibull-changelog) ![Ansible community logo](https://docs.ansible.com/images/project-logos/ansible-community.svg) ### Antsibull Docs Tooling for building documentation for Ansible collections, ansible-core, and the Ansible community package. * [Documentation](https://docs.ansible.com/projects/antsibull-docs/) * [Source code](https://github.com/ansible-community/antsibull-docs) * [Python library for parsing Ansible markup](https://github.com/ansible-community/antsibull-docs-parser) * [TypeScript library for parsing Ansible markup](https://github.com/ansible-community/antsibull-docs-ts) ![Ansible community logo](https://docs.ansible.com/images/project-logos/ansible-community.svg) ### Anstibull Nox A nox helper library that simplifies the process of testing Ansible collections through a common interface for various tools. * [Documentation](https://docs.ansible.com/projects/antsibull-nox/) * [Source code](https://github.com/ansible-community/antsibull-nox) ![Ansible community logo](https://docs.ansible.com/images/project-logos/ansible-community.svg) ### Ansible Development Environment A pip-like install for Ansible collections that isolates environments and promotes an ephemeral approach to development. * [Documentation](https://docs.ansible.com/projects/dev-environment/) * [Source code](https://github.com/ansible/ansible-development-environment) ![Ansible Development Environment project logo](https://docs.ansible.com/images/project-logos/ansible-community.svg) ### Ansible Development Tools Ansible Development Tools (ADT) streamlines the setup and usage of several tools for creating Ansible content. * [Documentation](https://docs.ansible.com/projects/dev-tools/) * [Source code](https://github.com/ansible/ansible-dev-tools) ![Ansible Development Tools project logo](https://docs.ansible.com/images/project-logos/ansible-community.svg) ### ansible-pylibssh ansible-pylibssh provides Python bindings for Ansible with the libssh project. * [Documentation](https://ansible-pylibssh.readthedocs.io/en/latest/) * [Source code](https://github.com/ansible/pylibssh) ![ansible-pylibssh project logo](https://docs.ansible.com/images/project-logos/ansible-community.svg) ### Ansible AWX AWX provides a web-based user interface, REST API, and task engine built on top of Ansible. * [Documentation](https://docs.ansible.com/projects/awx/) * [Source code](https://github.com/ansible/awx) ![AWX project logo](https://docs.ansible.com/images/project-logos/awx.svg) ### AWX Operator Ansible AWX Operator offers built-in intelligence and operational best practices for deploying on Kubernetes environments. * [Documentation](https://docs.ansible.com/projects/awx-operator/) * [Source code](https://github.com/ansible/awx-operator) ![AWX Operator project logo](https://docs.ansible.com/images/project-logos/ansible-community.svg) ### Ansible Builder Ansible Builder lets you create Execution Environments, which are container images that act as Ansible control nodes. * [Documentation](https://docs.ansible.com/projects/builder/) * [Source code](https://github.com/ansible/ansible-builder) ![Ansible Builder project logo](https://docs.ansible.com/images/project-logos/builder.svg) ### Ansible collections Ansible collections offer distributions of playbooks, roles, modules, and plugins. * [Collection index](https://docs.ansible.com/ansible/latest/collections/index.html) * [Find out how to use collections](https://docs.ansible.com/ansible/latest/collections_guide/index.html) * [Learn how to contribute to collections](https://docs.ansible.com/ansible/devel/community/contributions_collections.html#collections-contributions) * [Index of all modules and plugins](https://docs.ansible.com/ansible/latest/collections/all_plugins.html) ![Ansible community logo](https://docs.ansible.com/images/project-logos/ansible-community.svg) ### Ansible Compat Compat is a Python package that assists with compatibility between different Ansible releases, starting at version 2.9. * [Documentation](https://docs.ansible.com/projects/compat/) * [Source code](https://github.com/ansible/ansible-compat) ![Ansible Compat project logo](https://docs.ansible.com/images/project-logos/ansible-community.svg) ### Ansible Core Ansible Core is the language and runtime that powers automation. It also provides command-line tools such as Ansible Test. * [Ansible Core documentation](https://docs.ansible.com/ansible-core/devel/index.html) * [Ansible Test documentation](https://docs.ansible.com/ansible-core/devel/dev_guide/testing_running_locally.html) * [Source code](https://github.com/ansible/ansible) ![Ansible Core project logo](https://docs.ansible.com/images/project-logos/ansible-core.svg) ### Ansible Creator Ansible Creator is a Command-Line Interface (CLI) tool designed for effortlessly scaffolding all your Ansible content. * [Documentation](https://docs.ansible.com/projects/creator/) * [Source code](https://github.com/ansible/ansible-creator) ![Ansible Creator project logo](https://docs.ansible.com/images/project-logos/ansible-community.svg) ### Event-Driven Ansible Server Event-Driven Ansible Server offers scalable and flexible automation that can subscribe to a wide variety of event sources. * [Deployment guide](https://github.com/ansible/eda-server/blob/main/docs/deployment.md) * [Development environment setup](https://github.com/ansible/eda-server/blob/main/docs/development.md) * [Source code](https://github.com/ansible/eda-server) ![Event-Driven Ansible Server project logo](https://docs.ansible.com/images/project-logos/eda.svg) ### Edge Automation Edge provides tooling and collections to run automation jobs on device endpoints at the very edge of your infrastructure. * [Osbuild Composer Collection](https://github.com/redhat-cop/infra.osbuild) * [Common Industrial Protocol (CIP) Collection](https://github.com/ansible-collections/community.cip) * [FDO Collection](https://github.com/ansible-collections/community.fdo) * [MicroShift Collection](https://github.com/ansible-collections/edge.microshift/) ![Edge Automation logo](https://docs.ansible.com/images/project-logos/ansible-community.svg) ### Galaxy NG Galaxy NG jumpstarts automation projects with Ansible community content. Galaxy lets you share Ansible automation and promotes a collaborative approach to development and maintenance. * [Search Galaxy](https://galaxy.ansible.com/search) * [Documentation](https://docs.ansible.com/projects/galaxy-ng/) * [Source code](https://github.com/ansible/galaxy_ng/) ![Galaxy NG project logo](https://docs.ansible.com/images/project-logos/galaxy.svg) ### Ansible Lint Lint improves code quality through proven best practices, patterns, and behaviors so that your Ansible content results in reliable and consistent automation. * [Documentation](https://docs.ansible.com/projects/lint/) * [Source code](https://github.com/ansible/ansible-lint) ![Ansible Lint project logo](https://docs.ansible.com/images/project-logos/ansible-community.svg) ### Molecule Molecule helps you develop and test Ansible roles with consistent development patterns. Using Molecule results in well-written roles that are easy to understand and maintain. * [Documentation](https://docs.ansible.com/projects/molecule/) * [Source code](https://github.com/ansible/molecule/) ![Molecule project logo](https://docs.ansible.com/images/project-logos/ansible-community.svg) ### Ansible Navigator Ansible Navigator is a command-line tool for creating, reviewing, and troubleshooting Ansible content. * [Documentation](https://docs.ansible.com/projects/navigator/) * [Source code](https://github.com/ansible/ansible-navigator) ![Ansible Navigator project logo](https://docs.ansible.com/images/project-logos/ansible-community.svg) ### Ansible Pytest Enables the use of Ansible in tests as well as the use of pytest as a collection unit test runner, and exposes molecule scenarios using a pytest fixture. * [Documentation](https://docs.ansible.com/projects/pytest-ansible/) * [Source code](https://github.com/ansible/pytest-ansible) ![Ansible Pytest project logo](https://docs.ansible.com/images/project-logos/ansible-community.svg) ### Ansible Rulebook Ansible Rulebook is a command-line tool that listens to events so your automation can react when software or system states change. * [Documentation](https://docs.ansible.com/projects/rulebook/) * [Source code](https://github.com/ansible/ansible-rulebook) ![Ansible Rulebook project logo](https://docs.ansible.com/images/project-logos/ansible-community.svg) ### Ansible Runner Ansible Runner provides a stable and consistent interface abstraction to Ansible. * [Documentation](https://docs.ansible.com/projects/runner/) * [Source code](https://github.com/ansible/ansible-runner) ![Ansible Runner project logo](https://docs.ansible.com/images/project-logos/runner.svg) ### Ansible SDK Ansible SDK is a toolkit that lets you harness the power and simplicity of Ansible automation directly from your applications. * [Documentation](https://docs.ansible.com/projects/sdk/) * [Source code](https://github.com/ansible/ansible-sdk) ![Ansible SDK project logo](https://docs.ansible.com/images/project-logos/ansible-community.svg) ### Ansible Sign Ansible Sign is a utility for signing and verifying Ansible automation. Use Sign to secure workflows and pipelines for trusted automation content. * [Documentation](https://docs.ansible.com/projects/sign/) * [Source code](https://github.com/ansible/ansible-sign) ![Ansible Sign project logo](https://docs.ansible.com/images/project-logos/ansible-community.svg) ### Tox Ansible Tox Ansible is a utility designed to simplify the testing of Ansible content collections. * [Documentation](https://docs.ansible.com/projects/tox-ansible/) * [Source code](https://github.com/ansible/tox-ansible) ![Tox Ansible project logo](https://docs.ansible.com/images/project-logos/ansible-community.svg) ### Ansible VS Code Extension The VS Code extension adds Ansible language support to Visual Studio Code and OpenVSX compatible editors. * [Documentation](https://marketplace.visualstudio.com/items?itemName=redhat.ansible) * [Source code](https://github.com/ansible/vscode-ansible) ![Ansible VS Code Extension project logo](https://docs.ansible.com/images/project-logos/ansible-community.svg) * [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) * [Privacy policy](https://www.redhat.com/en/about/privacy-policy) * [Code of conduct](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html) Sponsored by [![Red Hat logo.](https://docs.ansible.com/assets/images/redhat_reversed.svg)](https://www.redhat.com/en/technologies/management/ansible?sc_id=RHCTE0250000464439) --- # Custom image - Ansible Molecule [Skip to content](https://docs.ansible.com/projects/molecule/guides/custom-image/#customizing-the-docker-image-used-by-a-scenarioplatform) [](https://github.com/ansible/molecule/blob/main/docs/guides/custom-image.md "Edit this page") [](https://github.com/ansible/molecule/raw/main/docs/guides/custom-image.md "View source of this page") Custom image ============ Customizing the Docker Image Used by a Scenario/Platform[¶](https://docs.ansible.com/projects/molecule/guides/custom-image/#customizing-the-docker-image-used-by-a-scenarioplatform "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ The docker driver supports using pre-built images and `docker build` -ing local customizations for each scenario's platform. The Docker image used by a scenario is governed by the following configuration items: 1. `platforms[*].image`: Docker image name:tag to use as base image. 2. `platforms[*].pre_build_image`: Whether to customize base image or use as-is[1](https://docs.ansible.com/projects/molecule/guides/custom-image/#fn:1) . > * When `true`, use the specified `platform[].image` as-is. > * When `false`, exec `docker build` to customize base image using either: > > > * Dockerfile specified by `platforms[*].dockerfile` or > > * Dockerfile rendered from `Dockerfile.j2` template (in scenario dir) The `Dockerfile.j2` template is generated at `molecule init scenario`\-time when `--driver-name` is `docker`. The template can be customized as needed to create the desired modifications to the Docker image used in the scenario. Note: `platforms[*].pre_build_image` defaults to `true` in each scenario's generated `molecule.yml` file. * * * 1. [Implementation in molecule docker driver](https://github.com/ansible-community/molecule-plugins/blob/main/src/molecule_plugins/docker/playbooks/create.yml)  [↩](https://docs.ansible.com/projects/molecule/guides/custom-image/#fnref:1 "Jump back to footnote 1 in the text") Back to top --- # Python 3 Support — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * Python 3 Support * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/reference_appendices/python_3_support.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Python 3 Support[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/python_3_support.html#python-3-support "Link to this heading") ============================================================================================================================================================= Ansible 2.5 and above work with Python 3. Previous to 2.5, using Python 3 was considered a tech preview. This topic discusses how to set up your control node and managed machines to use Python 3. See [Control Node Requirements](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#control-node-requirements) and [Managed Node Requirements](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#managed-node-requirements) for the specific versions supported. On the control node side[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/python_3_support.html#on-the-control-node-side "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The easiest way to run **/usr/bin/ansible** under Python 3 is to install it with the Python3 version of pip. This will make the default **/usr/bin/ansible** run with Python3: $ pip3 install ansible $ ansible \--version | grep "python version" python version \= 3.10.5 (main, Jun 9 2022, 00:00:00) \[GCC 12.1.1 20220507 (Red Hat 12.1.1-1)\] (/usr/bin/python) If you are running Ansible [Running the devel branch from a clone](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#from-source) and want to use Python 3 with your source checkout, run your command through `python3`. For example: $ source ./hacking/env-setup $ python3 $(which ansible) localhost \-m ping $ python3 $(which ansible-playbook) sample-playbook.yml Note Individual Linux distribution packages may be packaged for Python2 or Python3. When running from distro packages you’ll only be able to use Ansible with the Python version for which it was installed. Sometimes distros will provide a means of installing for several Python versions (through a separate package or through some commands that are run after install). You’ll need to check with your distro to see if that applies in your case. Using Python 3 on the managed machines with commands and playbooks[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/python_3_support.html#using-python-3-on-the-managed-machines-with-commands-and-playbooks "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * Ansible will automatically detect and use Python 3 on many platforms that ship with it. To explicitly configure a Python 3 interpreter, set the `ansible_python_interpreter` inventory variable at a group or host level to the location of a Python 3 interpreter, such as **/usr/bin/python3**. The default interpreter path may also be set in `ansible.cfg`. See also [Interpreter Discovery](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/interpreter_discovery.html#interpreter-discovery) for more information. \# Example inventory that makes an alias for localhost that uses Python3 localhost-py3 ansible\_host\=localhost ansible\_connection=local ansible\_python\_interpreter=/usr/bin/python3 \# Example of setting a group of hosts to use Python3 \[py3\_hosts\] ubuntu16 fedora27 \[py3\_hosts:vars\] ansible\_python\_interpreter\=/usr/bin/python3 See also [How to build your inventory](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#intro-inventory) for more information. * Run your command or playbook: $ ansible localhost-py3 \-m ping $ ansible-playbook sample-playbook.yml Note that you can also use the \-e command line option to manually set the python interpreter when you run a command. This can be useful if you want to test whether a specific module or playbook has any bugs under Python 3. For example: $ ansible localhost \-m ping \-e 'ansible\_python\_interpreter=/usr/bin/python3' $ ansible-playbook sample-playbook.yml \-e 'ansible\_python\_interpreter=/usr/bin/python3' What to do if an incompatibility is found[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/python_3_support.html#what-to-do-if-an-incompatibility-is-found "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- We have spent several releases squashing bugs and adding new tests so that Ansible’s core feature set runs under both Python 2 and Python 3. However, bugs may still exist in edge cases and many of the modules shipped with Ansible are maintained by the community and not all of those may be ported yet. If you find a bug running under Python 3 you can submit a bug report on [Ansible’s GitHub project](https://github.com/ansible/ansible/issues/) . Be sure to mention Python3 in the bug report so that the right people look at it. If you would like to fix the code and submit a pull request on github, you can refer to [Ansible and Python 3](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_python_3.html#developing-python-3) for information on how we fix common Python3 compatibility issues in the Ansible codebase. --- # Playbook Testing - Ansible Molecule [Skip to content](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#playbook-testing) [](https://github.com/ansible/molecule/blob/main/docs/getting-started-playbooks.md "Edit this page") [](https://github.com/ansible/molecule/raw/main/docs/getting-started-playbooks.md "View source of this page") Playbook Testing[¶](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#playbook-testing "Permanent link") ============================================================================================================================= This guide demonstrates testing Ansible playbooks using Molecule within an ansible-creator playbook project. It covers the fundamentals of playbook testing, container and network device testing scenarios, and complete test lifecycle management. Prerequisites[¶](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#prerequisites "Permanent link") ----------------------------------------------------------------------------------------------------------------------- Before starting, ensure you have the following installed: * [Ansible](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html) (ansible-core) * [Molecule](https://docs.ansible.com/projects/molecule/installation/) * [ansible-creator](https://docs.ansible.com/projects/creator/) for scaffolding * [Podman](https://podman.io/getting-started/installation) for container testing `[](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-0-1) # Install ansible-creator in your virtual environment [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-0-2) pip install ansible-creator` Creating a Playbook Project[¶](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#creating-a-playbook-project "Permanent link") --------------------------------------------------------------------------------------------------------------------------------------------------- **Initialize a playbook project using ansible-creator:** `[](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-1-1) ansible-creator init playbook myorg.myproject /tmp/my-playbooks [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-1-2) cd /tmp/my-playbooks` This creates the following structure: `[](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-2-1) my-playbooks/ [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-2-2) ├── ansible.cfg [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-2-3) ├── ansible-navigator.yml [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-2-4) ├── collections/ [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-2-5) │ └── requirements.yml [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-2-6) ├── inventory/ [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-2-7) │ ├── group_vars/ [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-2-8) │ ├── host_vars/ [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-2-9) │ └── hosts.yml [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-2-10) ├── linux_playbook.yml [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-2-11) ├── network_playbook.yml [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-2-12) └── site.yml` **Create Molecule requirements file:** `[](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-3-1) mkdir molecule [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-3-2) cat > molecule/requirements.yml << 'EOF' [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-3-3) --- [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-3-4) collections: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-3-5) - name: containers.podman [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-3-6) version: ">=1.10.0" [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-3-7) - name: arista.eos [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-3-8) version: ">=6.0.0" [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-3-9) EOF` **Initialize Molecule scenarios for different testing needs:** `[](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-4-1) # Linux container testing scenario [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-4-2) molecule init scenario linux [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-4-3) [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-4-4) # Network device testing scenario [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-4-5) molecule init scenario network` Linux Container Testing Scenario[¶](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#linux-container-testing-scenario "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------------------------- This scenario tests playbooks against Linux containers using Podman. ### Configure the Linux Scenario[¶](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#configure-the-linux-scenario "Permanent link") **Update `molecule/linux/molecule.yml`:** The `molecule.yml` file is the scenario-specific configuration that tailors Molecule's behavior to the needs of this testing scenario. `[](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-5-1) --- [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-5-2) dependency: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-5-3) name: galaxy [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-5-4) options: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-5-5) requirements-file: ../requirements.yml [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-5-6) [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-5-7) ansible: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-5-8) cfg: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-5-9) defaults: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-5-10) collections_path: collections [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-5-11) inventory: inventory/hosts.yml [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-5-12) [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-5-13) scenario: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-5-14) test_sequence: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-5-15) - dependency [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-5-16) - create [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-5-17) - prepare [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-5-18) - converge [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-5-19) - idempotence [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-5-20) - verify [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-5-21) - cleanup [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-5-22) - destroy` **Create `molecule/linux/inventory.yml`:** The inventory defines the testing resources and their configuration details that Molecule will use to create and manage test instances. `[](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-6-1) --- [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-6-2) all: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-6-3) children: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-6-4) webservers: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-6-5) hosts: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-6-6) web-server: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-6-7) ansible_host: web-server [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-6-8) container_image: quay.io/centos/centos:stream9 [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-6-9) container_command: /sbin/init [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-6-10) container_privileged: true [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-6-11) vars: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-6-12) http_port: 80 [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-6-13) server_name: test-web [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-6-14) required_packages: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-6-15) - python3 [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-6-16) - systemd [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-6-17) databases: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-6-18) hosts: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-6-19) db-server: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-6-20) ansible_host: db-server [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-6-21) container_image: quay.io/centos/centos:stream9 [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-6-22) container_command: /sbin/init [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-6-23) container_privileged: true [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-6-24) vars: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-6-25) db_name: testdb [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-6-26) db_user: testuser [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-6-27) required_packages: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-6-28) - python3 [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-6-29) - systemd` **Create `molecule/linux/create.yml`:** The create playbook is used to instantiate the testing resources defined in the inventory, provisioning containers and establishing connectivity. `[](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-7-1) --- [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-7-2) - name: Create container instances [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-7-3) hosts: localhost [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-7-4) gather_facts: false [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-7-5) tasks: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-7-6) - name: Create container network [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-7-7) containers.podman.podman_network: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-7-8) name: molecule-linux-test [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-7-9) state: present [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-7-10) [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-7-11) - name: Create test containers [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-7-12) containers.podman.podman_container: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-7-13) name: "{{ hostvars[item].ansible_host }}" [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-7-14) image: "{{ hostvars[item].container_image }}" [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-7-15) command: "{{ hostvars[item].container_command }}" [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-7-16) privileged: "{{ hostvars[item].container_privileged }}" [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-7-17) state: started [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-7-18) networks: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-7-19) - molecule-linux-test [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-7-20) systemd: true [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-7-21) loop: "{{ groups['all'] }}" [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-7-22) [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-7-23) - name: Wait for containers to be ready [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-7-24) ansible.builtin.wait_for_connection: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-7-25) timeout: 300 [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-7-26) delegate_to: "{{ hostvars[item].ansible_host }}" [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-7-27) loop: "{{ groups['all'] }}"` **Create `molecule/linux/prepare.yml`:** The prepare playbook configures the testing resources with any prerequisites needed before running the main playbook under test. `[](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-8-1) --- [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-8-2) - name: Prepare container instances [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-8-3) hosts: all [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-8-4) gather_facts: false [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-8-5) become: true [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-8-6) tasks: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-8-7) - name: Install required packages [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-8-8) ansible.builtin.dnf: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-8-9) name: "{{ required_packages }}" [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-8-10) state: present [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-8-11) when: required_packages is defined` **Create `molecule/linux/converge.yml`:** The converge playbook executes the main playbook being tested, applying your automation logic to the prepared testing resources. `[](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-9-1) --- [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-9-2) - name: Converge [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-9-3) ansible.builtin.import_playbook: ../../linux_playbook.yml` **Create `molecule/linux/verify.yml`:** The verify playbook validates that the converge playbook achieved the desired results by testing the final state of the resources. `[](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-10-1) --- [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-10-2) - name: Verify [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-10-3) hosts: all [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-10-4) gather_facts: true [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-10-5) tasks: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-10-6) - name: Check required packages are installed [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-10-7) ansible.builtin.package_facts: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-10-8) manager: auto [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-10-9) [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-10-10) - name: Verify python3 is installed [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-10-11) ansible.builtin.assert: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-10-12) that: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-10-13) - "'python3' in ansible_facts.packages" [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-10-14) fail_msg: "Python3 package not found" [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-10-15) [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-10-16) - name: Verify systemd service is running [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-10-17) ansible.builtin.systemd: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-10-18) name: systemd-logind [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-10-19) state: started [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-10-20) check_mode: true [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-10-21) register: systemd_check [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-10-22) failed_when: false [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-10-23) [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-10-24) - name: Assert systemd is active [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-10-25) ansible.builtin.assert: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-10-26) that: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-10-27) - systemd_check is not failed [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-10-28) fail_msg: "Systemd service not running"` **Create `molecule/linux/cleanup.yml`:** The cleanup playbook removes temporary artifacts and resets the testing resources to a clean state before destruction. `[](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-11-1) --- [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-11-2) - name: Cleanup [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-11-3) hosts: all [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-11-4) gather_facts: false [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-11-5) tasks: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-11-6) - name: Remove test artifacts [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-11-7) ansible.builtin.file: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-11-8) path: /tmp/molecule-test [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-11-9) state: absent [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-11-10) become: true` **Create `molecule/linux/destroy.yml`:** The destroy playbook tears down all testing resources, removing containers and networks to return the system to its original state. `[](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-12-1) --- [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-12-2) - name: Destroy container instances [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-12-3) hosts: localhost [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-12-4) gather_facts: false [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-12-5) tasks: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-12-6) - name: Remove test containers [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-12-7) containers.podman.podman_container: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-12-8) name: "{{ hostvars[item].ansible_host }}" [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-12-9) state: absent [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-12-10) loop: "{{ groups['all'] }}" [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-12-11) failed_when: false [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-12-12) [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-12-13) - name: Remove container network [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-12-14) containers.podman.podman_network: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-12-15) name: molecule-linux-test [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-12-16) state: absent [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-12-17) failed_when: false` Network Device Testing Scenario[¶](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#network-device-testing-scenario "Permanent link") ----------------------------------------------------------------------------------------------------------------------------------------------------------- This scenario tests playbooks against Arista EOS network devices using containerized cEOS. ### Configure the Network Scenario[¶](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#configure-the-network-scenario "Permanent link") **Update `molecule/network/molecule.yml`:** This scenario-specific configuration adapts Molecule for network device testing with simplified sequences and network-specific settings. `[](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-13-1) --- [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-13-2) dependency: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-13-3) name: galaxy [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-13-4) options: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-13-5) requirements-file: ../requirements.yml [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-13-6) [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-13-7) ansible: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-13-8) cfg: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-13-9) defaults: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-13-10) collections_path: collections [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-13-11) inventory: inventory/hosts.yml [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-13-12) host_key_checking: false [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-13-13) [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-13-14) scenario: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-13-15) name: network [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-13-16) description: Test against network devices [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-13-17) test_sequence: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-13-18) - dependency [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-13-19) - create [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-13-20) - converge [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-13-21) - verify [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-13-22) - cleanup [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-13-23) - destroy` **Create `molecule/network/inventory.yml`:** The network inventory defines containerized network devices with connection parameters and container configuration for realistic device testing. `[](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-14-1) --- [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-14-2) all: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-14-3) children: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-14-4) arista_switches: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-14-5) hosts: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-14-6) eos-switch-01: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-14-7) ansible_host: eos-switch-01 [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-14-8) ansible_network_os: eos [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-14-9) ansible_user: admin [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-14-10) ansible_password: admin [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-14-11) ansible_connection: ansible.netcommon.network_cli [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-14-12) container_image: ceos:latest [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-14-13) container_privileged: true [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-14-14) container_env: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-14-15) CEOS: 1 [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-14-16) EOS_PLATFORM: ceoslab [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-14-17) container: docker [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-14-18) vars: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-14-19) ansible_python_interpreter: "{{ ansible_playbook_python }}"` **Create `molecule/network/create.yml`:** The create playbook launches containerized network devices and waits for both SSH and API services to become available for testing. `[](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-1) --- [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-2) - name: Create network device containers [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-3) hosts: localhost [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-4) gather_facts: false [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-5) tasks: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-6) - name: Create container network [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-7) containers.podman.podman_network: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-8) name: molecule-network-test [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-9) state: present [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-10) [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-11) - name: Create EOS containers [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-12) containers.podman.podman_container: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-13) name: "{{ hostvars[item].ansible_host }}" [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-14) image: "{{ hostvars[item].container_image }}" [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-15) privileged: "{{ hostvars[item].container_privileged }}" [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-16) state: started [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-17) networks: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-18) - molecule-network-test [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-19) ports: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-20) - "2200:22" [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-21) - "2600:443" [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-22) volumes: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-23) - /etc/sysctl.d/99-zceos.conf:/etc/sysctl.d/99-zceos.conf:ro [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-24) tmpfs: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-25) - /tmp [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-26) command: /sbin/init [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-27) env: "{{ hostvars[item].container_env }}" [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-28) network_cli_ssh_type: paramiko [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-29) loop: "{{ groups['arista_switches'] }}" [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-30) [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-31) - name: Wait for SSH to be available [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-32) ansible.builtin.wait_for: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-33) host: "{{ hostvars[item].ansible_host }}" [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-34) port: 22 [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-35) timeout: 300 [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-36) loop: "{{ groups['arista_switches'] }}" [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-37) [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-38) - name: Wait for EOS API to be ready [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-39) ansible.builtin.uri: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-40) url: "https://{{ hostvars[item].ansible_host }}:443/command-api" [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-41) method: GET [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-42) validate_certs: false [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-43) timeout: 10 [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-44) register: api_check [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-45) until: api_check.status == 200 [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-46) retries: 30 [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-47) delay: 10 [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-48) loop: "{{ groups['arista_switches'] }}" [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-15-49) failed_when: false` **Create `molecule/network/converge.yml`:** The converge playbook executes the network playbook under test against the containerized network devices. `[](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-16-1) --- [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-16-2) - name: Converge [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-16-3) ansible.builtin.import_playbook: ../../network_playbook.yml` **Create `molecule/network/verify.yml`:** The verify playbook tests network device functionality using EOS-specific commands to validate the playbook's effects on device configuration. `[](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-17-1) --- [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-17-2) - name: Verify network devices [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-17-3) hosts: arista_switches [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-17-4) gather_facts: false [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-17-5) connection: ansible.netcommon.network_cli [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-17-6) tasks: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-17-7) - name: Get EOS version [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-17-8) arista.eos.eos_command: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-17-9) commands: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-17-10) - show version [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-17-11) register: version_output [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-17-12) [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-17-13) - name: Verify EOS version contains expected info [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-17-14) ansible.builtin.assert: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-17-15) that: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-17-16) - "'Arista' in version_output.stdout[0]" [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-17-17) fail_msg: "EOS version check failed" [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-17-18) [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-17-19) - name: Gather EOS facts [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-17-20) arista.eos.eos_facts: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-17-21) gather_subset: min [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-17-22) register: eos_facts [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-17-23) [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-17-24) - name: Verify system facts [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-17-25) ansible.builtin.assert: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-17-26) that: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-17-27) - eos_facts.ansible_facts.ansible_net_version is defined [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-17-28) - eos_facts.ansible_facts.ansible_net_hostname is defined [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-17-29) fail_msg: "Required EOS facts not available"` **Create `molecule/network/cleanup.yml`:** The cleanup playbook removes any test configurations from the network devices to restore them to a clean state. `[](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-18-1) --- [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-18-2) - name: Cleanup network configuration [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-18-3) hosts: arista_switches [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-18-4) gather_facts: false [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-18-5) connection: ansible.netcommon.network_cli [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-18-6) tasks: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-18-7) - name: Remove test configurations [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-18-8) arista.eos.eos_config: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-18-9) lines: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-18-10) - no interface Loopback99 [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-18-11) backup: false [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-18-12) failed_when: false` **Create `molecule/network/destroy.yml`:** The destroy playbook removes the containerized network devices and networks, completing the test lifecycle cleanup. `[](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-19-1) --- [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-19-2) - name: Destroy network device containers [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-19-3) hosts: localhost [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-19-4) gather_facts: false [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-19-5) tasks: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-19-6) - name: Remove EOS containers [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-19-7) containers.podman.podman_container: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-19-8) name: "{{ hostvars[item].ansible_host }}" [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-19-9) state: absent [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-19-10) loop: "{{ groups['arista_switches'] }}" [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-19-11) failed_when: false [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-19-12) [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-19-13) - name: Remove container network [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-19-14) containers.podman.podman_network: [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-19-15) name: molecule-network-test [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-19-16) state: absent [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-19-17) failed_when: false` Running the Tests[¶](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#running-the-tests "Permanent link") ------------------------------------------------------------------------------------------------------------------------------- ### Testing Individual Scenarios[¶](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#testing-individual-scenarios "Permanent link") **Linux Scenario:** `[](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-20-1) # Test the complete lifecycle [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-20-2) molecule test --scenario-name linux --report --command-borders [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-20-3) [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-20-4) # Run specific actions [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-20-5) molecule create --scenario-name linux --report --command-borders [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-20-6) molecule converge --scenario-name linux --report --command-borders [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-20-7) molecule verify --scenario-name linux --report --command-borders` **Network Scenario:** `[](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-21-1) # Test the network scenario [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-21-2) molecule test --scenario-name network --report --command-borders [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-21-3) [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-21-4) # Converge only [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-21-5) molecule converge --scenario-name network --report --command-borders` ### Expected Output[¶](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#expected-output "Permanent link") `[](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-1) $ molecule test --scenario-name linux --report --command-borders [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-2) [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-3) INFO linux ➜ discovery: scenario test matrix: dependency, create, prepare, converge, idempotence, verify, cleanup, destroy [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-4) INFO linux ➜ dependency: Executing [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-5) INFO linux ➜ create: Executing [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-6) ┌────────────────────────────────────────────────────────────────────────────────── [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-7) │ ansible-playbook --inventory /tmp/molecule/linux/inventory [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-8) │ --skip-tags molecule-notest,notest [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-9) │ /tmp/molecule/linux/create.yml [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-10) │ [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-11) │ [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-12) │ PLAY [Create container instances] ******************************************** [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-13) │ [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-14) │ TASK [Create container network] ********************************************** [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-15) │ changed: [localhost] [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-16) │ [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-17) │ TASK [Create test containers] ************************************************ [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-18) │ changed: [localhost] => (item=web-server) [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-19) │ changed: [localhost] => (item=db-server) [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-20) │ [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-21) │ TASK [Wait for containers to be ready] ************************************** [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-22) │ ok: [web-server] [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-23) │ ok: [db-server] [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-24) │ [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-25) │ PLAY RECAP ******************************************************************** [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-26) │ localhost : ok=2 changed=2 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-27) │ [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-28) └─ Return code: 0 ───────────────────────────────────────────────────────────────── [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-29) INFO linux ➜ create: Executed: Successful [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-30) INFO linux ➜ prepare: Executing [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-31) ┌────────────────────────────────────────────────────────────────────────────────── [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-32) │ ansible-playbook --inventory /tmp/molecule/linux/inventory [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-33) │ --skip-tags molecule-notest,notest [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-34) │ /tmp/molecule/linux/prepare.yml [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-35) │ [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-36) │ [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-37) │ PLAY [Prepare container instances] ******************************************* [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-38) │ [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-39) │ TASK [Install required packages] ********************************************* [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-40) │ changed: [web-server] => (item=python3) [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-41) │ changed: [db-server] => (item=python3) [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-42) │ changed: [web-server] => (item=systemd) [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-43) │ changed: [db-server] => (item=systemd) [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-44) │ [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-45) │ PLAY RECAP ******************************************************************** [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-46) │ web-server : ok=1 changed=1 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-47) │ db-server : ok=1 changed=1 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-48) │ [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-49) └─ Return code: 0 ───────────────────────────────────────────────────────────────── [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-50) INFO linux ➜ prepare: Executed: Successful [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-51) INFO linux ➜ converge: Executing [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-52) INFO linux ➜ idempotence: Executing [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-53) INFO linux ➜ verify: Executing [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-54) INFO linux ➜ cleanup: Executing [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-55) INFO linux ➜ destroy: Executing [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-56) [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-57) SCENARIO RECAP [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-22-58) linux : actions=8 successful=8 disabled=0 skipped=0 missing=0 failed=0` Advanced Testing Patterns[¶](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#advanced-testing-patterns "Permanent link") ----------------------------------------------------------------------------------------------------------------------------------------------- ### Environment-Specific Testing[¶](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#environment-specific-testing "Permanent link") Test playbooks with different inventory configurations: `[](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-23-1) # Test with specific inventory [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-23-2) molecule converge --scenario-name linux --inventory inventory/production.yml --report --command-borders` ### Multiple Playbook Testing[¶](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#multiple-playbook-testing "Permanent link") Create scenarios to test different playbook combinations: `[](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-24-1) # Initialize scenario for site.yml testing [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-24-2) molecule init scenario site-testing [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-24-3) [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-24-4) # Test the complete site playbook [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-24-5) molecule test --scenario-name site-testing --report --command-borders` ### Parallel Testing[¶](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#parallel-testing "Permanent link") Run multiple scenarios simultaneously: `[](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-25-1) # Test both scenarios in parallel [](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#__codelineno-25-2) molecule test --parallel --report --command-borders` Summary[¶](https://docs.ansible.com/projects/molecule/getting-started-playbooks/#summary "Permanent link") ----------------------------------------------------------------------------------------------------------- This guide demonstrated comprehensive playbook testing using Molecule with both container and network device scenarios. Key benefits include: * **Complete test lifecycle management** with create, converge, verify, and cleanup phases * **Multiple testing environments** supporting both Linux containers and network devices * **Realistic testing scenarios** using actual device containers (cEOS) rather than simulation * **Integration with ansible-creator** for standardized project structure * **Flexible inventory management** supporting both static and dynamic configurations The ansible-native approach ensures that your Molecule tests integrate seamlessly with existing Ansible workflows while providing comprehensive validation of playbook functionality across diverse infrastructure environments. Back to top --- # Configuring Ansible — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * [Installation Guide](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/index.html) * Configuring Ansible * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/installation_guide/intro_configuration.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * [Configuring Ansible](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_configuration.html#id3) [](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_configuration.html#configuring-ansible "Link to this heading") ============================================================================================================================================================================================================================================================================= This topic describes how to control Ansible settings. [Configuration file](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_configuration.html#id4) [](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_configuration.html#configuration-file "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Certain settings in Ansible are adjustable with a configuration file (`ansible.cfg`). The stock configuration should be sufficient for most users, but there may be reasons you would want to change them. Paths where the configuration file is searched are listed in [reference documentation](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/config.html#ansible-configuration-settings-locations) . ### [Getting the latest configuration](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_configuration.html#id5) [](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_configuration.html#getting-the-latest-configuration "Link to this heading") If installing Ansible from a package manager, the latest `ansible.cfg` file should be present in `/etc/ansible`, possibly as a `.rpmnew` file (or other) as appropriate in the case of updates. If you installed Ansible from `pip` or from the source, you may want to create this file to override default settings in Ansible. You can generate an Ansible configuration file, `ansible.cfg`, that lists all default settings as follows: $ ansible-config init \--disabled \> ansible.cfg Include available plugins to create a more complete Ansible configuration as follows: $ ansible-config init \--disabled \-t all \> ansible.cfg For more details and a full listing of available configurations go to [configuration\_settings](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/config.html#ansible-configuration-settings) . You can use the [ansible-config](https://docs.ansible.com/projects/ansible-core/devel/cli/ansible-config.html#ansible-config) command-line utility to list your available options and inspect the current values. For in-depth details, see [Ansible Configuration Settings](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/config.html#ansible-configuration-settings) . [Environmental configuration](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_configuration.html#id6) [](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_configuration.html#environmental-configuration "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Ansible also allows configuring settings using environment variables. If these environment variables are set, they will override any associated settings loaded from the configuration file. You can get a full listing of available environment variables from: * [Ansible Configuration Settings](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/config.html#ansible-configuration-settings) : for configuring core functionality * [Index of all Collection Environment Variables](https://docs.ansible.com/projects/ansible-core/devel/collections/environment_variables.html#list-of-collection-env-vars) : for configuring plugins in collections [Command line options](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_configuration.html#id7) [](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_configuration.html#command-line-options "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Not all configuration options are present in the command line, just the ones deemed most useful or common. Settings in the command line will override those passed through the configuration file and the environment. The full list of options available is in [ansible-playbook](https://docs.ansible.com/projects/ansible-core/devel/cli/ansible-playbook.html#ansible-playbook) and [ansible](https://docs.ansible.com/projects/ansible-core/devel/cli/ansible.html#ansible) . --- # Installation Guide — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * Installation Guide * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/installation_guide/index.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Installation Guide[](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/index.html#installation-guide "Link to this heading") ==================================================================================================================================================== Welcome to the Ansible Installation Guide! * [Installing Ansible](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html) * [Control node requirements](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#control-node-requirements) * [Managed node requirements](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#managed-node-requirements) * [Node requirement summary](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#node-requirement-summary) * [Selecting an Ansible package and version to install](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#selecting-an-ansible-package-and-version-to-install) * [Installing and upgrading Ansible with pipx](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#installing-and-upgrading-ansible-with-pipx) * [Installing and upgrading Ansible with pip](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#installing-and-upgrading-ansible-with-pip) * [Installing Ansible to containers](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#installing-ansible-to-containers) * [Installing for development](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#installing-for-development) * [Confirming your installation](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#confirming-your-installation) * [Adding Ansible command shell completion](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#adding-ansible-command-shell-completion) * [Installing Ansible on specific operating systems](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/installation_distros.html) * [Requirements for adding new distributions](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/installation_distros.html#requirements-for-adding-new-distributions) * [Installing Ansible on Fedora Linux](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/installation_distros.html#installing-ansible-on-fedora-linux) * [Installing Ansible from EPEL](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/installation_distros.html#installing-ansible-from-epel) * [Installing Ansible on OpenSUSE Tumbleweed/Leap](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/installation_distros.html#installing-ansible-on-opensuse-tumbleweed-leap) * [Installing Ansible on Ubuntu](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/installation_distros.html#installing-ansible-on-ubuntu) * [Installing Ansible on Debian](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/installation_distros.html#installing-ansible-on-debian) * [Installing Ansible on Arch Linux](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/installation_distros.html#installing-ansible-on-arch-linux) * [Installing Ansible on Windows](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/installation_distros.html#installing-ansible-on-windows) * [Configuring Ansible](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_configuration.html) * [Configuration file](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_configuration.html#configuration-file) * [Environmental configuration](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_configuration.html#environmental-configuration) * [Command line options](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_configuration.html#command-line-options) --- # Galaxy Developer Guide — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * Galaxy Developer Guide * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/galaxy/dev_guide.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Galaxy Developer Guide[](https://docs.ansible.com/projects/ansible-core/devel/galaxy/dev_guide.html#galaxy-developer-guide "Link to this heading") ==================================================================================================================================================== You can host collections and roles on Galaxy to share with the Ansible community. Galaxy content is formatted in pre-packaged units of work such as [roles](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_reuse_roles.html#playbooks-reuse-roles) , and [collections](https://docs.ansible.com/projects/ansible-core/devel/collections_guide/index.html#collections) . You can create roles for provisioning infrastructure, deploying applications, and all of the tasks you do everyday. Taking this a step further, you can create collections which provide a comprehensive package of automation that may include multiple playbooks, roles, modules, and plugins. [Creating collections for Galaxy](https://docs.ansible.com/projects/ansible-core/devel/galaxy/dev_guide.html#id1) [](https://docs.ansible.com/projects/ansible-core/devel/galaxy/dev_guide.html#creating-collections-for-galaxy "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- 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/) . See [Developing collections](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_collections.html#developing-collections) for details on how to create collections. [Creating roles for Galaxy](https://docs.ansible.com/projects/ansible-core/devel/galaxy/dev_guide.html#id2) [](https://docs.ansible.com/projects/ansible-core/devel/galaxy/dev_guide.html#creating-roles-for-galaxy "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Use the `init` command to initialize the base structure of a new role, saving time on creating the various directories and main.yml files a role requires $ ansible-galaxy role init role\_name The above will create the following directory structure in the current working directory: role\_name/ README.md defaults/ main.yml files/ handlers/ main.yml meta/ main.yml tasks/ main.yml templates/ tests/ inventory test.yml vars/ main.yml If you want to create a repository for the role, the repository root should be role\_name. ### [Force](https://docs.ansible.com/projects/ansible-core/devel/galaxy/dev_guide.html#id3) [](https://docs.ansible.com/projects/ansible-core/devel/galaxy/dev_guide.html#force "Link to this heading") If a directory matching the name of the role already exists in the current working directory, the init command will result in an error. To ignore the error use the `--force` option. Force will create the above subdirectories and files, replacing anything that matches. ### [Container enabled](https://docs.ansible.com/projects/ansible-core/devel/galaxy/dev_guide.html#id4) [](https://docs.ansible.com/projects/ansible-core/devel/galaxy/dev_guide.html#container-enabled "Link to this heading") If you are creating a Container Enabled role, pass `--type container` to `ansible-galaxy role init`. This will create the same directory structure as above, but populate it with default files appropriate for a Container Enabled role. For example, the README.md has a slightly different structure, the `.travis.yml` file tests the role using [Ansible Container](https://github.com/ansible/ansible-container) , and the meta directory includes a `container.yml` file. ### [Using a custom role skeleton](https://docs.ansible.com/projects/ansible-core/devel/galaxy/dev_guide.html#id5) [](https://docs.ansible.com/projects/ansible-core/devel/galaxy/dev_guide.html#using-a-custom-role-skeleton "Link to this heading") A custom role skeleton directory can be supplied as follows: $ ansible-galaxy role init \--role-skeleton\=/path/to/skeleton role\_name When a skeleton is provided, init will: * copy all files and directories from the skeleton to the new role * any .j2 files found outside of a templates folder will be rendered as templates. The only useful variable at the moment is role\_name * The .git folder and any .git\_keep files will not be copied Alternatively, the role\_skeleton and ignoring of files can be configured with ansible.cfg \[galaxy\] role\_skeleton = /path/to/skeleton role\_skeleton\_ignore = ^.git$,^.\*/.git\_keep$ ### [Authenticate with Galaxy](https://docs.ansible.com/projects/ansible-core/devel/galaxy/dev_guide.html#id6) [](https://docs.ansible.com/projects/ansible-core/devel/galaxy/dev_guide.html#authenticate-with-galaxy "Link to this heading") Using the `import`, `delete` and `setup` commands to manage your roles on the Galaxy website requires authentication in the form of an API key, you must create an account on the Galaxy website. To create an authentication token: 1. Click Collections > API Token. 2. Click Load Token and then copy it. 3. Save your token in the path set in the [GALAXY\_TOKEN\_PATH](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/config.html#galaxy-token-path) . ### [Import a role](https://docs.ansible.com/projects/ansible-core/devel/galaxy/dev_guide.html#id7) [](https://docs.ansible.com/projects/ansible-core/devel/galaxy/dev_guide.html#import-a-role "Link to this heading") The `import` command requires that you authenticate with the API token. You can include it in your `ansible.cfg` file or use the `--token` command option. You are only allowed to remove roles where you have access to the repository in GitHub. To import a new role: $ ansible-galaxy role import github\_user github\_repo By default, the command will wait for Galaxy to complete the import process, displaying the results as the import progresses: Successfully submitted import request 41 Starting import 41: role\_name=myrole repo=githubuser/ansible-role-repo ref= Retrieving GitHub repo githubuser/ansible-role-repo Accessing branch: devel Parsing and validating meta/main.yml Parsing galaxy\_tags Parsing platforms Adding dependencies Parsing and validating README.md Adding repo tags as role versions Import completed Status SUCCESS : warnings=0 errors=0 See [ansible-galaxy](https://docs.ansible.com/projects/ansible-core/devel/cli/ansible-galaxy.html#ansible-galaxy) for other command options. ### [Delete a role](https://docs.ansible.com/projects/ansible-core/devel/galaxy/dev_guide.html#id8) [](https://docs.ansible.com/projects/ansible-core/devel/galaxy/dev_guide.html#delete-a-role "Link to this heading") The `delete` command requires that you authenticate with the API token. You can include it in your `ansible.cfg` file or use the `--token` command option. You are only allowed to remove roles where you have access to the repository in GitHub. Use the following to delete a role: $ ansible-galaxy role delete github\_user github\_repo This only removes the role from Galaxy. It does not remove or alter the actual GitHub repository. ### [Travis integrations](https://docs.ansible.com/projects/ansible-core/devel/galaxy/dev_guide.html#id9) [](https://docs.ansible.com/projects/ansible-core/devel/galaxy/dev_guide.html#travis-integrations "Link to this heading") You can create an integration or connection between a role in Galaxy and [Travis](https://travis-ci.org/) . Once the connection is established, a build in Travis will automatically trigger an import in Galaxy, updating the search index with the latest information about the role. You create the integration using the `setup` command with your API token. You will also need an account in Travis, and your Travis token. Once you are ready, use the following command to create the integration: $ ansible-galaxy role setup travis github\_user github\_repo xxx-travis-token-xxx The setup command requires your Travis token, however the token is not stored in Galaxy. It is used along with the GitHub username and repo to create a hash as described in [the Travis documentation](https://docs.travis-ci.com/user/notifications/) . The hash is stored in Galaxy and used to verify notifications received from Travis. The setup command enables Galaxy to respond to notifications. To configure Travis to run a build on your repository and send a notification, follow the [Travis getting started guide](https://docs.travis-ci.com/user/getting-started/) . To instruct Travis to notify Galaxy when a build completes, add the following to your .travis.yml file: notifications: webhooks: https://galaxy.ansible.com/api/v1/notifications/ #### List Travis integrations[](https://docs.ansible.com/projects/ansible-core/devel/galaxy/dev_guide.html#list-travis-integrations "Link to this heading") Use the `--list` option to display your Travis integrations: $ ansible-galaxy role setup \--list travis github\_user github\_repo xxx-travis-token-xxx ID Source Repo ---------- \---------- \---------- 2 travis github\_user/github\_repo 1 travis github\_user/github\_repo #### Remove Travis integrations[](https://docs.ansible.com/projects/ansible-core/devel/galaxy/dev_guide.html#remove-travis-integrations "Link to this heading") Use the `--remove` option to disable and remove a Travis integration: > $ ansible-galaxy role setup \--remove ID Provide the ID of the integration to be disabled. You can find the ID by using the `--list` option. See also [Using Ansible collections](https://docs.ansible.com/projects/ansible-core/devel/collections_guide/index.html#collections) Shareable collections of modules, playbooks and roles [Roles](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_reuse_roles.html#playbooks-reuse-roles) All about ansible roles [Communication](https://docs.ansible.com/projects/ansible-core/devel/community/communication.html#communication) Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide --- # Special Variables — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * Special Variables * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/reference_appendices/special_variables.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Special Variables[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#special-variables "Link to this heading") ================================================================================================================================================================ Magic variables[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#magic-variables "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------ These variables cannot be set directly by the user; Ansible will always override them to reflect internal state. ansible\_check\_mode[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-ansible_check_mode "Link to this term") Boolean that indicates if we are in check mode or not ansible\_collection\_name[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-ansible_collection_name "Link to this term") The name of the collection the task that is executing is a part of. In the format of `namespace.collection` ansible\_config\_file[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-ansible_config_file "Link to this term") The full path of used Ansible configuration file ansible\_dependent\_role\_names[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-ansible_dependent_role_names "Link to this term") The names of the roles currently imported into the current play as dependencies of other plays ansible\_diff\_mode[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-ansible_diff_mode "Link to this term") Boolean that indicates if we are in diff mode or not ansible\_forks[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-ansible_forks "Link to this term") Integer reflecting the number of maximum forks available to this run ansible\_index\_var[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-ansible_index_var "Link to this term") The name of the value provided to `loop_control.index_var`. Added in `2.9` ansible\_inventory\_sources[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-ansible_inventory_sources "Link to this term") List of sources used as inventory ansible\_limit[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-ansible_limit "Link to this term") Contents of the `--limit` CLI option for the current execution of Ansible ansible\_loop[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-ansible_loop "Link to this term") A dictionary/map containing extended loop information when enabled through `loop_control.extended` ansible\_loop\_var[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-ansible_loop_var "Link to this term") The name of the value provided to `loop_control.loop_var`. Added in `2.8` ansible\_parent\_role\_names[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-ansible_parent_role_names "Link to this term") When the current role is being executed by means of an [include\_role](https://docs.ansible.com/projects/ansible-core/devel/collections/ansible/builtin/include_role_module.html#include-role-module) or [import\_role](https://docs.ansible.com/projects/ansible-core/devel/collections/ansible/builtin/import_role_module.html#import-role-module) action, this variable contains a list of all parent roles, with the most recent role (in other words, the role that included/imported this role) being the first item in the list. When multiple inclusions occur, this list lists the _last_ role (in other words, the role that included this role) as the _first_ item in the list. It is also possible that a specific role exists more than once in this list. For example: When role **A** includes role **B**, inside role B, `ansible_parent_role_names` will equal to `['A']`. If role **B** then includes role **C**, the list becomes `['B', 'A']`. ansible\_parent\_role\_paths[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-ansible_parent_role_paths "Link to this term") When the current role is being executed by means of an [include\_role](https://docs.ansible.com/projects/ansible-core/devel/collections/ansible/builtin/include_role_module.html#include-role-module) or [import\_role](https://docs.ansible.com/projects/ansible-core/devel/collections/ansible/builtin/import_role_module.html#import-role-module) action, this variable contains a list of all parent roles paths, with the most recent role (in other words, the role that included/imported this role) being the first item in the list. Please refer to `ansible_parent_role_names` for the order of items in this list. ansible\_play\_batch[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-ansible_play_batch "Link to this term") List of active hosts in the current play run limited by the serial, aka ‘batch’. Failed/Unreachable hosts are not considered ‘active’. ansible\_play\_hosts[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-ansible_play_hosts "Link to this term") List of hosts in the current play run, not limited by the serial. Failed/Unreachable hosts are excluded from this list. ansible\_play\_hosts\_all[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-ansible_play_hosts_all "Link to this term") List of all the hosts that were targeted by the play ansible\_play\_name[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-ansible_play_name "Link to this term") The name of the currently executed play. Added in `2.8`. (name attribute of the play, not file name of the playbook.) ansible\_play\_role\_names[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-ansible_play_role_names "Link to this term") The names of the roles currently imported into the current play. This list does **not** contain the role names that are implicitly included through dependencies. ansible\_playbook\_python[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-ansible_playbook_python "Link to this term") The path to the python interpreter being used by Ansible on the control node ansible\_role\_name[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-ansible_role_name "Link to this term") The fully qualified collection role name, in the format of `namespace.collection.role_name` ansible\_role\_names[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-ansible_role_names "Link to this term") The names of the roles currently imported into the current play, or roles referenced as dependencies of the roles imported into the current play. ansible\_run\_tags[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-ansible_run_tags "Link to this term") Contents of the `--tags` CLI option, which specifies which tags will be included for the current run. Note that if `--tags` is not passed, this variable will default to `["all"]`. ansible\_search\_path[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-ansible_search_path "Link to this term") Current search path for action plugins and lookups, in other words, where we search for relative paths when you do `template: src=myfile` ansible\_skip\_tags[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-ansible_skip_tags "Link to this term") Contents of the `--skip-tags` CLI option, which specifies which tags will be skipped for the current run. ansible\_verbosity[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-ansible_verbosity "Link to this term") Current verbosity setting for Ansible ansible\_version[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-ansible_version "Link to this term") Dictionary/map that contains information about the current running version of ansible, it has the following keys: full, major, minor, revision and string. group\_names[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-group_names "Link to this term") List of groups the current host is part of, it always reflects the `inventory_hostname` and ignores delegation. groups[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-groups "Link to this term") A dictionary/map with all the groups in inventory and each group has the list of hosts that belong to it hostvars[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-hostvars "Link to this term") A dictionary/map with all the hosts in inventory and variables assigned to them inventory\_dir[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-inventory_dir "Link to this term") The directory of the inventory source in which the inventory\_hostname was first defined. This always reflects the `inventory_hostname` and ignores delegation. inventory\_hostname[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-inventory_hostname "Link to this term") The inventory name for the ‘current’ host being iterated over in the play. This is not affected by delegation, it always reflects the original host for the task inventory\_hostname\_short[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-inventory_hostname_short "Link to this term") The short version of inventory\_hostname, is the first section after splitting it via `.`. As an example, for the `inventory_hostname` of `www.example.com`, `www` would be the `inventory_hostname_short` This is affected by delegation, so it will reflect the ‘short name’ of the delegated host inventory\_file[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-inventory_file "Link to this term") The file name of the inventory source in which the inventory\_hostname was first defined. Ignores delegation and always reflects the information for the `inventory_hostname`. omit[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-omit "Link to this term") Special variable that allows you to ‘omit’ an option in a task, for example `- user: name=bob home={{ bobs_home|default(omit) }}` play\_hosts[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-play_hosts "Link to this term") Deprecated, the same as ansible\_play\_batch playbook\_dir[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-playbook_dir "Link to this term") The path to the directory of the current playbook being executed. NOTE: This might be different than directory of the playbook passed to the `ansible-playbook` command line when a playbook contains a `import_playbook` statement. role\_name[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-role_name "Link to this term") The name of the role currently being executed. role\_names[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-role_names "Link to this term") Deprecated, the same as ansible\_play\_role\_names role\_path[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-role_path "Link to this term") The path to the dir of the currently running role Facts[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#facts "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------- These are variables that contain information pertinent to the current host (inventory\_hostname). They are only available if gathered first. See [Discovering variables: facts and magic variables](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_vars_facts.html#vars-and-facts) for more information. ansible\_facts[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-ansible_facts "Link to this term") Contains any facts gathered or cached for the inventory\_hostname Facts are normally gathered by the [setup](https://docs.ansible.com/projects/ansible-core/devel/collections/ansible/builtin/setup_module.html#setup-module) module automatically in a play, but any module can return facts. ansible\_local[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-ansible_local "Link to this term") Contains any ‘local facts’ gathered or cached for the inventory\_hostname. The keys available depend on the custom facts created. See the [setup](https://docs.ansible.com/projects/ansible-core/devel/collections/ansible/builtin/setup_module.html#setup-module) module and [facts.d or local facts](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_vars_facts.html#local-facts) for more details. Connection variables[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#connection-variables "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- Connection variables are normally used to set the specifics on how to execute actions on a target. Most of them correspond to connection plugins, but not all are specific to them; other plugins like shell, terminal and become are normally involved. Only the common ones are described as each connection/become/shell/etc plugin can define its own overrides and specific variables. See [Controlling how Ansible behaves: precedence rules](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/general_precedence.html#general-precedence-rules) for how connection variables interact with [configuration settings](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/config.html#ansible-configuration-settings) , [command-line options](https://docs.ansible.com/projects/ansible-core/devel/command_guide/command_line_tools.html#command-line-tools) , and [playbook keywords](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/playbooks_keywords.html#playbook-keywords) . ansible\_become\_user[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-ansible_become_user "Link to this term") The user Ansible ‘becomes’ after using privilege escalation. This must be available to the ‘login user’. ansible\_connection[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-ansible_connection "Link to this term") The connection plugin actually used for the task on the target host. ansible\_host[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-ansible_host "Link to this term") The ip/name of the target host to use instead of inventory\_hostname. ansible\_python\_interpreter[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-ansible_python_interpreter "Link to this term") The path to the Python executable Ansible should use on the target host. ansible\_user[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#term-ansible_user "Link to this term") The user Ansible ‘logs in’ as. --- # Return Values — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * Return Values * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/reference_appendices/common_return_values.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * [Return Values](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/common_return_values.html#id1) [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/common_return_values.html#return-values "Link to this heading") ======================================================================================================================================================================================================================================================================= Ansible modules normally return a data structure that can be registered into a variable, or seen directly when output by the ansible program. Each module can optionally document its own unique return values (visible through ansible-doc and on the [main docsite](https://docs.ansible.com/projects/ansible/2.9/index.html#ansible-documentation "(in Ansible v2.9)") ). This document covers return values common to all modules. Note Some of these keys might be set by Ansible itself once it processes the module’s return information. [Common](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/common_return_values.html#id2) [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/common_return_values.html#common "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [backup\_file](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/common_return_values.html#id3) [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/common_return_values.html#backup-file "Link to this heading") For those modules that implement backup=no|yes when manipulating files, a path to the backup file created if original file was changed. > "backup\_file": "./foo.txt.32729.2020-07-30@06:24:19~" ### [changed](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/common_return_values.html#id4) [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/common_return_values.html#changed "Link to this heading") A boolean indicating if the task had to make changes to the target or delegated host. > "changed": true ### [diff](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/common_return_values.html#id5) [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/common_return_values.html#diff "Link to this heading") Information on differences between the previous and current state. Often a dictionary with entries `before` and `after`, which will then be formatted by the callback plugin to a diff view. > "diff": \[\ > {\ > "after": "",\ > "after\_header": "foo.txt (content)",\ > "before": "",\ > "before\_header": "foo.txt (content)"\ > },\ > {\ > "after\_header": "foo.txt (file attributes)",\ > "before\_header": "foo.txt (file attributes)"\ > }\ \ ### [failed](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/common_return_values.html#id6)\ [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/common_return_values.html#failed "Link to this heading")\ \ A boolean that indicates if the task was failed or not.\ \ > "failed": false\ \ ### [invocation](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/common_return_values.html#id7)\ [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/common_return_values.html#invocation "Link to this heading")\ \ Information on how the module was invoked.\ \ > "invocation": {\ > "module\_args": {\ > "\_original\_basename": "foo.txt",\ > "attributes": null,\ > "backup": true,\ > "checksum": "da39a3ee5e6b4b0d3255bfef95601890afd80709",\ > "content": null,\ > "delimiter": null,\ > "dest": "./foo.txt",\ > "directory\_mode": null,\ > "follow": false,\ > "force": true,\ > "group": null,\ > "local\_follow": null,\ > "mode": "666",\ > "owner": null,\ > "regexp": null,\ > "remote\_src": null,\ > "selevel": null,\ > "serole": null,\ > "setype": null,\ > "seuser": null,\ > "src": "/Users/foo/.ansible/tmp/ansible-tmp-1596115458.110205-105717464505158/source",\ > "unsafe\_writes": null,\ > "validate": null\ > }\ \ ### [msg](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/common_return_values.html#id8)\ [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/common_return_values.html#msg "Link to this heading")\ \ A string with a generic message relayed to the user.\ \ > "msg": "line added"\ \ ### [rc](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/common_return_values.html#id9)\ [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/common_return_values.html#rc "Link to this heading")\ \ Some modules execute command line utilities or are geared for executing commands directly (raw, shell, command, and so on), this field contains ‘return code’ of these utilities.\ \ > "rc": 257\ \ ### [results](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/common_return_values.html#id10)\ [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/common_return_values.html#results "Link to this heading")\ \ If this key exists, it indicates that a loop was present for the task and that it contains a list of the normal module ‘result’ per item.\ \ > "results": \[\ > {\ > "ansible\_loop\_var": "item",\ > "backup": "foo.txt.83170.2020-07-30@07:03:05~",\ > "changed": true,\ > "diff": \[\ > {\ > "after": "",\ > "after\_header": "foo.txt (content)",\ > "before": "",\ > "before\_header": "foo.txt (content)"\ > },\ > {\ > "after\_header": "foo.txt (file attributes)",\ > "before\_header": "foo.txt (file attributes)"\ > }\ > \],\ > "failed": false,\ > "invocation": {\ > "module\_args": {\ > "attributes": null,\ > "backrefs": false,\ > "backup": true\ > }\ > },\ > "item": "foo",\ > "msg": "line added"\ > },\ > {\ > "ansible\_loop\_var": "item",\ > "backup": "foo.txt.83187.2020-07-30@07:03:05~",\ > "changed": true,\ > "diff": \[\ > {\ > "after": "",\ > "after\_header": "foo.txt (content)",\ > "before": "",\ > "before\_header": "foo.txt (content)"\ > },\ > {\ > "after\_header": "foo.txt (file attributes)",\ > "before\_header": "foo.txt (file attributes)"\ > }\ > \],\ > "failed": false,\ > "invocation": {\ > "module\_args": {\ > "attributes": null,\ > "backrefs": false,\ > "backup": true\ > }\ > },\ > "item": "bar",\ > "msg": "line added"\ > }\ > \]\ \ ### [skipped](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/common_return_values.html#id11)\ [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/common_return_values.html#skipped "Link to this heading")\ \ A boolean that indicates if the task was skipped or not\ \ > "skipped": true\ \ ### [stderr](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/common_return_values.html#id12)\ [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/common_return_values.html#stderr "Link to this heading")\ \ Some modules execute command line utilities or are geared for executing commands directly (raw, shell, command, and so on), this field contains the error output of these utilities.\ \ > "stderr": "ls: foo: No such file or directory"\ \ ### [stderr\_lines](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/common_return_values.html#id13)\ [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/common_return_values.html#stderr-lines "Link to this heading")\ \ When stderr is returned we also always provide this field which is a list of strings, one item per line from the original.\ \ > "stderr\_lines": \[\ > "ls: doesntexist: No such file or directory"\ > \]\ \ ### [stdout](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/common_return_values.html#id14)\ [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/common_return_values.html#stdout "Link to this heading")\ \ Some modules execute command line utilities or are geared for executing commands directly (raw, shell, command, and so on). This field contains the normal output of these utilities.\ \ > "stdout": "foo!"\ \ ### [stdout\_lines](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/common_return_values.html#id15)\ [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/common_return_values.html#stdout-lines "Link to this heading")\ \ When stdout is returned, Ansible always provides a list of strings, each containing one item per line from the original output.\ \ > "stdout\_lines": \[\ > "foo!"\ > \]\ \ [Internal use](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/common_return_values.html#id16)\ [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/common_return_values.html#internal-use "Link to this heading")\ \ ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------\ \ These keys can be added by modules but will be removed from registered variables; they are ‘consumed’ by Ansible itself.\ \ ### [ansible\_facts](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/common_return_values.html#id17)\ [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/common_return_values.html#ansible-facts "Link to this heading")\ \ This key should contain a dictionary which will be appended to the facts assigned to the host. These will be directly accessible and don’t require using a registered variable.\ \ ### [exception](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/common_return_values.html#id18)\ [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/common_return_values.html#exception "Link to this heading")\ \ This key can contain traceback information caused by an exception in a module. It will only be displayed on high verbosity (-vvv).\ \ ### [warnings](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/common_return_values.html#id19)\ [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/common_return_values.html#warnings "Link to this heading")\ \ This key contains a list of strings that will be presented to the user.\ \ ### [deprecations](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/common_return_values.html#id20)\ [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/common_return_values.html#deprecations "Link to this heading")\ \ This key contains a list of dictionaries that will be presented to the user. Keys of the dictionaries are msg and version, values are string, value for the version key can be an empty string.\ \ See also\ \ [Collection Index](https://docs.ansible.com/projects/ansible-core/devel/collections/index.html#list-of-collections)\ \ Browse existing collections, modules, and plugins\ \ [GitHub modules directory](https://github.com/ansible/ansible/tree/devel/lib/ansible/modules)\ \ Browse source of core and extras modules\ \ [Communication](https://docs.ansible.com/projects/ansible-core/devel/community/communication.html#communication)\ \ Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide --- # Interpreter Discovery — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * Interpreter Discovery * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/reference_appendices/interpreter_discovery.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Interpreter Discovery[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/interpreter_discovery.html#interpreter-discovery "Link to this heading") ============================================================================================================================================================================ Most Ansible modules that execute under a POSIX environment require a Python interpreter on the target host. Unless configured otherwise, Ansible will attempt to discover a suitable Python interpreter on each target host the first time a Python module is executed for that host. To control the discovery behavior: * for individual hosts and groups, use the `ansible_python_interpreter` inventory variable * globally, use the `interpreter_python` key in the `[defaults]` section of `ansible.cfg` Configure a path to a specific Python interpreter, or one of the following values: auto (default) : Searches the configurable list of common Python interpreter paths (see [INTERPRETER\_PYTHON\_FALLBACK](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/config.html#interpreter-python-fallback) ) and issues a warning that future installation of another Python interpreter could alter the one chosen. auto\_legacy : Deprecated alias for `auto`. auto\_silent : Same as `auto`, but does not issue warnings. auto\_legacy\_silent : Deprecated alias for `auto_silent`. --- # Red Hat Ansible Automation Platform — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * Red Hat Ansible Automation Platform * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/reference_appendices/tower.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Red Hat Ansible Automation Platform[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/tower.html#red-hat-ansible-automation-platform "Link to this heading") ======================================================================================================================================================================================== Important Red Hat Ansible Automation Platform is available on multiple cloud platforms. See [Ansible on Clouds](https://access.redhat.com/documentation/en-us/ansible_on_clouds/2.x) for details. [Red Hat Ansible Automation Platform](https://www.ansible.com/products/automation-platform) (RHAAP) is an integrated solution for operationalizing Ansible across your team, organization, and enterprise. The platform includes a controller with a web console and REST API, analytics, Execution Environments, and much more. RHAAP gives you role-based access control, including control over the use of securely stored credentials for SSH and other services. You can sync your inventory with a wide variety of cloud sources, and powerful multi-playbook workflows allow you to model complex processes. RHAAP logs all of your jobs, integrates well with LDAP, SAML, and other authentication sources, and has an amazing browsable REST API. Command line tools are available for easy integration with Jenkins as well. RHAAP incorporates the downstream Red Hat supported product version of Ansible AWX, the downstream Red Hat supported product version of Ansible Galaxy, and multiple SaaS offerings. Find out more about RHAAP features and on the [Red Hat Ansible Automation Platform webpage](https://www.ansible.com/products/automation-platform) . A Red Hat Ansible Automation Platform subscription includes support from Red Hat, Inc. --- # Ansible Automation Hub — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * Ansible Automation Hub * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/reference_appendices/automationhub.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Ansible Automation Hub[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/automationhub.html#ansible-automation-hub "Link to this heading") ====================================================================================================================================================================== [Ansible Automation Hub](https://www.ansible.com/products/automation-hub) is the official location to discover and download certified [collections](https://catalog.redhat.com/software/search?type=Ansible%20Collection&p=1) , included as part of an Ansible Automation Platform subscription. These content collections contain modules, plugins, roles, and playbooks in a downloadable package. Ansible Automation Hub gives you direct access to trusted content collections from Red Hat and Certified Partners. You can find content by topic or Ansible Partner organizations. Ansible Automation Hub is the downstream Red Hat supported product version of Ansible Galaxy. Find out more about Ansible Automation Hub features and how to access it at [Ansible Automation Hub](https://www.ansible.com/products/automation-hub) . Ansible Automation Hub is part of the Red Hat Ansible Automation Platform subscription, and comes bundled with support from Red Hat, Inc. --- # Logging Ansible output — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * Logging Ansible output * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/reference_appendices/logging.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Logging Ansible output[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/logging.html#logging-ansible-output "Link to this heading") ================================================================================================================================================================ By default, Ansible sends output about plays, tasks, and module arguments to your screen (STDOUT) on the control node. If you want to capture Ansible output in a log, you have three options: * To save Ansible output in a single log on the control node, set the `log_path` [configuration file setting](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_configuration.html#intro-configuration) . You may also want to set `display_args_to_stdout`, which helps to differentiate similar tasks by including variable values in the Ansible output. * To save Ansible output in separate logs, one on each managed node, set the `no_target_syslog` and `syslog_facility` [configuration file settings](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_configuration.html#intro-configuration) . * To save Ansible output to a secure database, use AWX or [Red Hat Ansible Automation Platform](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/tower.html#ansible-platform) . You can then review history based on hosts, projects, and particular inventories over time, using graphs and/or a REST API. Protecting sensitive data with `no_log`[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/logging.html#protecting-sensitive-data-with-no-log "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ If you save Ansible output to a log, you expose any secret data in your Ansible output, such as passwords and usernames. To keep sensitive values out of your logs, mark tasks that expose them with the `no_log: True` attribute. However, the `no_log` attribute does not affect debugging output, so be careful not to debug playbooks in a production environment. See [How do I keep secret data in my playbook?](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#keep-secret-data) for an example. --- # Building Ansible inventories — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * Building Ansible inventories * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/inventory_guide/index.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Building Ansible inventories[](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/index.html#building-ansible-inventories "Link to this heading") ===================================================================================================================================================================== Note **Making Open Source More Inclusive** 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) . Welcome to the guide to building Ansible inventories. An inventory is a list of managed nodes, or hosts, that Ansible deploys and configures. This guide introduces you to inventories and covers the following topics: * Creating inventories to track a list of servers and devices that you want to automate. * Using dynamic inventories to track cloud services with servers and devices that are constantly starting and stopping. * Using patterns to automate specific sub-sets of an inventory. * Expanding and refining the connection methods Ansible uses for your inventory. * [How to build your inventory](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html) * [Inventory basics: formats, hosts, and groups](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#inventory-basics-formats-hosts-and-groups) * [Passing multiple inventory sources](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#passing-multiple-inventory-sources) * [Organizing inventory in a directory](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#organizing-inventory-in-a-directory) * [Adding variables to inventory](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#adding-variables-to-inventory) * [Assigning a variable to one machine: host variables](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#assigning-a-variable-to-one-machine-host-variables) * [Defining variables in INI format](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#defining-variables-in-ini-format) * [Assigning a variable to many machines: group variables](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#assigning-a-variable-to-many-machines-group-variables) * [Organizing host and group variables](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#organizing-host-and-group-variables) * [How variables are merged](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#how-variables-are-merged) * [Connecting to hosts: behavioral inventory parameters](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#connecting-to-hosts-behavioral-inventory-parameters) * [Inventory setup examples](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#inventory-setup-examples) * [Working with dynamic inventory](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_dynamic_inventory.html) * [Inventory script example: Cobbler](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_dynamic_inventory.html#inventory-script-example-cobbler) * [Other inventory scripts](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_dynamic_inventory.html#other-inventory-scripts) * [Using inventory directories and multiple inventory sources](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_dynamic_inventory.html#using-inventory-directories-and-multiple-inventory-sources) * [Static groups of dynamic groups](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_dynamic_inventory.html#static-groups-of-dynamic-groups) * [Patterns: targeting hosts and groups](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_patterns.html) * [Using patterns](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_patterns.html#using-patterns) * [Common patterns](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_patterns.html#common-patterns) * [Limitations of patterns](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_patterns.html#limitations-of-patterns) * [Pattern processing order](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_patterns.html#pattern-processing-order) * [Advanced pattern options](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_patterns.html#advanced-pattern-options) * [Patterns and ad-hoc commands](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_patterns.html#patterns-and-ad-hoc-commands) * [Patterns and ansible-playbook flags](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_patterns.html#patterns-and-ansible-playbook-flags) * [Connection methods and details](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/connection_details.html) * [ControlPersist and paramiko](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/connection_details.html#controlpersist-and-paramiko) * [Setting a remote user](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/connection_details.html#setting-a-remote-user) * [Setting up SSH keys](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/connection_details.html#setting-up-ssh-keys) * [Running against localhost](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/connection_details.html#running-against-localhost) * [Managing host key checking](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/connection_details.html#managing-host-key-checking) * [Other connection methods](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/connection_details.html#other-connection-methods) --- # ansible-core Contributors Guide — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * ansible-core Contributors Guide * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/community/contributions.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * ansible-core Contributors Guide[](https://docs.ansible.com/projects/ansible-core/devel/community/contributions.html#ansible-core-contributors-guide "Link to this heading") ============================================================================================================================================================================= * [Reporting bugs and requesting features](https://docs.ansible.com/projects/ansible-core/devel/community/reporting_bugs_and_features.html) * [Reporting a bug](https://docs.ansible.com/projects/ansible-core/devel/community/reporting_bugs_and_features.html#reporting-a-bug) * [Requesting a feature](https://docs.ansible.com/projects/ansible-core/devel/community/reporting_bugs_and_features.html#requesting-a-feature) * [Contributing to the Ansible Documentation](https://docs.ansible.com/projects/ansible-core/devel/community/documentation_contributions.html) * [Editing docs directly on GitHub](https://docs.ansible.com/projects/ansible-core/devel/community/documentation_contributions.html#editing-docs-directly-on-github) * [Reviewing or solving open issues](https://docs.ansible.com/projects/ansible-core/devel/community/documentation_contributions.html#reviewing-or-solving-open-issues) * [Reviewing open PRs](https://docs.ansible.com/projects/ansible-core/devel/community/documentation_contributions.html#reviewing-open-prs) * [Opening a new issue and/or PR](https://docs.ansible.com/projects/ansible-core/devel/community/documentation_contributions.html#opening-a-new-issue-and-or-pr) * [Verifying your documentation PR](https://docs.ansible.com/projects/ansible-core/devel/community/documentation_contributions.html#verifying-your-documentation-pr) * [Joining the documentation working group](https://docs.ansible.com/projects/ansible-core/devel/community/documentation_contributions.html#joining-the-documentation-working-group) * [The Ansible Development Cycle](https://docs.ansible.com/projects/ansible-core/devel/community/development_process.html) * [Macro development: `ansible-core` roadmaps, releases, and projects](https://docs.ansible.com/projects/ansible-core/devel/community/development_process.html#macro-development-ansible-core-roadmaps-releases-and-projects) * [Micro development: the lifecycle of a PR](https://docs.ansible.com/projects/ansible-core/devel/community/development_process.html#micro-development-the-lifecycle-of-a-pr) * [Making your PR merge-worthy](https://docs.ansible.com/projects/ansible-core/devel/community/development_process.html#making-your-pr-merge-worthy) * [Backporting merged PRs in `ansible-core`](https://docs.ansible.com/projects/ansible-core/devel/community/development_process.html#backporting-merged-prs-in-ansible-core) * [Other Tools and Programs](https://docs.ansible.com/projects/ansible-core/devel/community/other_tools_and_programs.html) * [Popular editors](https://docs.ansible.com/projects/ansible-core/devel/community/other_tools_and_programs.html#popular-editors) * [Tools for validating playbooks](https://docs.ansible.com/projects/ansible-core/devel/community/other_tools_and_programs.html#tools-for-validating-playbooks) * [Collection development tools](https://docs.ansible.com/projects/ansible-core/devel/community/other_tools_and_programs.html#collection-development-tools) * [Other tools](https://docs.ansible.com/projects/ansible-core/devel/community/other_tools_and_programs.html#other-tools) If you have a specific Ansible interest or expertise (for example, VMware, Linode, and so on), consider joining a [working group](https://docs.ansible.com/projects/ansible-core/devel/community/communication.html#working-group-list) . Working with the Ansible repo[](https://docs.ansible.com/projects/ansible-core/devel/community/contributions.html#working-with-the-ansible-repo "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * I want to make my first code changes to a collection or to `ansible-core`. How do I [set up my Python development environment](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_general.html#environment-setup) ? * I would like to get more efficient as a developer. How can I find [editors, linters, and other tools](https://docs.ansible.com/projects/ansible-core/devel/community/other_tools_and_programs.html#other-tools-and-programs) that will support my Ansible development efforts? * I want my code to meet Ansible’s guidelines. Where can I find guidance on [coding in Ansible](https://docs.ansible.com/projects/ansible/2.9/dev_guide/index.html#developer-guide "(in Ansible v2.9)") ? * I would like to connect Ansible to a new API or other resource. How do I [create a collection](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_in_groups.html#developing-modules-in-groups) ? * My pull request is marked `needs_rebase`. How do I [rebase my PR](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_rebasing.html#rebase-guide) ? * I am using an older version of Ansible and want a bug fixed in my version that has already been fixed on the `devel` branch. How do I [backport a bugfix PR](https://docs.ansible.com/projects/ansible-core/devel/community/development_process.html#backport-process) ? * I have an open pull request with a failing test. How do I learn about Ansible’s [testing (CI) process](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/testing.html#developing-testing) ? * I am ready to step up as a collection maintainer. What are the [guidelines for maintainers](https://docs.ansible.com/projects/ansible/2.9/community/maintainers.html#maintainers "(in Ansible v2.9)") ? * A module in a collection I maintain is obsolete. How do I [deprecate a module](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/module_lifecycle.html#deprecating-modules) ? --- # Creating a playbook — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * [Getting started with Ansible](https://docs.ansible.com/projects/ansible-core/devel/getting_started/index.html) * Creating a playbook * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/getting_started/get_started_playbook.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Creating a playbook[](https://docs.ansible.com/projects/ansible-core/devel/getting_started/get_started_playbook.html#creating-a-playbook "Link to this heading") ================================================================================================================================================================== Playbooks are automation blueprints, in `YAML` format, that Ansible uses to deploy and configure managed nodes. Playbook A list of plays that define the order in which Ansible performs operations, from top to bottom, to achieve an overall goal. Play An ordered list of tasks that maps to managed nodes in an inventory. Task A reference to a single module that defines the operations that Ansible performs. Module A unit of code or binary that Ansible runs on managed nodes. Ansible modules are grouped in collections with a [Fully Qualified Collection Name (FQCN)](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Fully-Qualified-Collection-Name-FQCN) for each module. Complete the following steps to create a playbook that pings your hosts and prints a “Hello world” message: 1. Create a file named `playbook.yaml` in your `ansible_quickstart` directory, that you created earlier, with the following content: \- name: My first play hosts: myhosts tasks: \- name: Ping my hosts ansible.builtin.ping: \- name: Print message ansible.builtin.debug: msg: Hello world 2. Run your playbook. ansible-playbook \-i inventory.ini playbook.yaml Ansible returns the following output: PLAY \[My first play\] \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\* TASK \[Gathering Facts\] \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\* ok: \[192.0.2.50\] ok: \[192.0.2.51\] ok: \[192.0.2.52\] TASK \[Ping my hosts\] \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\* ok: \[192.0.2.50\] ok: \[192.0.2.51\] ok: \[192.0.2.52\] TASK \[Print message\] \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\* ok: \[192.0.2.50\] => { "msg": "Hello world" } ok: \[192.0.2.51\] => { "msg": "Hello world" } ok: \[192.0.2.52\] => { "msg": "Hello world" } PLAY RECAP \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\* 192.0.2.50: ok=3 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 192.0.2.51: ok=3 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 192.0.2.52: ok=3 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 In this output you can see: * The names that you give the play and each task. You should always use descriptive names that make it easy to verify and troubleshoot playbooks. * The “Gathering Facts” task runs implicitly. By default, Ansible gathers information about your inventory that it can use in the playbook. * The status of each task. Each task has a status of `ok` which means it ran successfully. * The play recap that summarizes results of all tasks in the playbook per host. In this example, there are three tasks so `ok=3` indicates that each task ran successfully. Congratulations, you have started using Ansible! See also [Ansible playbooks](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_intro.html#playbooks-intro) Start building playbooks for real world scenarios. [Working with playbooks](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks.html#working-with-playbooks) Go into more detail with Ansible playbooks. [Ansible tips and tricks](https://docs.ansible.com/projects/ansible-core/devel/tips_tricks/index.html#playbooks-best-practices) Get tips and tricks for using playbooks. [Discovering variables: facts and magic variables](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_vars_facts.html#vars-and-facts) Learn more about the `gather_facts` keyword in playbooks. --- # Ansible concepts — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * [Getting started with Ansible](https://docs.ansible.com/projects/ansible-core/devel/getting_started/index.html) * Ansible concepts * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/getting_started/basic_concepts.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Ansible concepts[](https://docs.ansible.com/projects/ansible-core/devel/getting_started/basic_concepts.html#ansible-concepts "Link to this heading") ====================================================================================================================================================== These concepts are common to all uses of Ansible. You should understand them before using Ansible or reading the documentation. [Control node](https://docs.ansible.com/projects/ansible-core/devel/getting_started/basic_concepts.html#id1) [](https://docs.ansible.com/projects/ansible-core/devel/getting_started/basic_concepts.html#control-node "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The machine from which you run the Ansible CLI tools (`ansible-playbook` , `ansible`, `ansible-vault` and others). You can use any computer that meets the software requirements as a control node - laptops, shared desktops, and servers can all run Ansible. You can also run Ansible in containers known as [Execution Environments](https://docs.ansible.com/projects/ansible/12/getting_started_ee/index.html#getting-started-ee-index "(in Ansible v12)") . Multiple control nodes are possible, but Ansible itself does not coordinate across them, see `AAP` for such features. [Managed nodes](https://docs.ansible.com/projects/ansible-core/devel/getting_started/basic_concepts.html#id2) [](https://docs.ansible.com/projects/ansible-core/devel/getting_started/basic_concepts.html#managed-nodes "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Also referred to as ‘hosts’, these are the target devices (servers, network appliances or any computer) you aim to manage with Ansible. Ansible is not normally installed on managed nodes, unless you are using `ansible-pull`, but this is rare and not the recommended setup. [Inventory](https://docs.ansible.com/projects/ansible-core/devel/getting_started/basic_concepts.html#id3) [](https://docs.ansible.com/projects/ansible-core/devel/getting_started/basic_concepts.html#inventory "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- A list of managed nodes provided by one or more ‘inventory sources’. Your inventory can specify information specific to each node, like IP address. It is also used for assigning groups, that both allow for node selection in the Play and bulk variable assignment. To learn more about inventory, see [the Working with Inventory](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#intro-inventory) section. Sometimes an inventory source file is also referred to as a ‘hostfile’. [Playbooks](https://docs.ansible.com/projects/ansible-core/devel/getting_started/basic_concepts.html#id4) [](https://docs.ansible.com/projects/ansible-core/devel/getting_started/basic_concepts.html#playbooks "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- They contain Plays (which are the basic unit of Ansible execution). This is both an ‘execution concept’ and how we describe the files on which `ansible-playbook` operates. Playbooks are written in YAML and are easy to read, write, share and understand. To learn more about playbooks, see [Ansible playbooks](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_intro.html#about-playbooks) . ### [Plays](https://docs.ansible.com/projects/ansible-core/devel/getting_started/basic_concepts.html#id5) [](https://docs.ansible.com/projects/ansible-core/devel/getting_started/basic_concepts.html#plays "Link to this heading") The main context for Ansible execution, this playbook object maps managed nodes (hosts) to tasks. The Play contains variables, roles and an ordered lists of tasks and can be run repeatedly. It basically consists of an implicit loop over the mapped hosts and tasks and defines how to iterate over them. #### [Roles](https://docs.ansible.com/projects/ansible-core/devel/getting_started/basic_concepts.html#id6) [](https://docs.ansible.com/projects/ansible-core/devel/getting_started/basic_concepts.html#roles "Link to this heading") A limited distribution of reusable Ansible content (tasks, handlers, variables, plugins, templates and files) for use inside of a Play. To use any Role resource, the Role itself must be imported into the Play. #### [Tasks](https://docs.ansible.com/projects/ansible-core/devel/getting_started/basic_concepts.html#id7) [](https://docs.ansible.com/projects/ansible-core/devel/getting_started/basic_concepts.html#tasks "Link to this heading") The definition of an ‘action’ to be applied to the managed host. You can execute a single task once with an ad hoc command using `ansible` or `ansible-console` (both create a virtual Play). #### [Handlers](https://docs.ansible.com/projects/ansible-core/devel/getting_started/basic_concepts.html#id8) [](https://docs.ansible.com/projects/ansible-core/devel/getting_started/basic_concepts.html#handlers "Link to this heading") A special form of a Task, that only executes when notified by a previous task which resulted in a ‘changed’ status. [Modules](https://docs.ansible.com/projects/ansible-core/devel/getting_started/basic_concepts.html#id9) [](https://docs.ansible.com/projects/ansible-core/devel/getting_started/basic_concepts.html#modules "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The code or binaries that Ansible copies to and executes on each managed node (when needed) to accomplish the action defined in each Task. Each module has a particular use, from administering users on a specific type of database to managing VLAN interfaces on a specific type of network device. You can invoke a single module with a task, or invoke several different modules in a playbook. Ansible modules are grouped in collections. For an idea of how many collections Ansible includes, see the [Collection Index](https://docs.ansible.com/projects/ansible-core/devel/collections/index.html#list-of-collections) . [Plugins](https://docs.ansible.com/projects/ansible-core/devel/getting_started/basic_concepts.html#id10) [](https://docs.ansible.com/projects/ansible-core/devel/getting_started/basic_concepts.html#plugins "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Pieces of code that expand Ansible’s core capabilities. Plugins can control how you connect to a managed node (connection plugins), manipulate data (filter plugins) and even control what is displayed in the console (callback plugins). See [Working with plugins](https://docs.ansible.com/projects/ansible-core/devel/plugins/plugins.html#working-with-plugins) for details. [Collections](https://docs.ansible.com/projects/ansible-core/devel/getting_started/basic_concepts.html#id11) [](https://docs.ansible.com/projects/ansible-core/devel/getting_started/basic_concepts.html#collections "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- A format in which Ansible content is distributed that can contain playbooks, roles, modules, and plugins. You can install and use collections through [Ansible Galaxy](https://galaxy.ansible.com/) . To learn more about collections, see [Using Ansible collections](https://docs.ansible.com/projects/ansible-core/devel/collections_guide/index.html#collections) . Collection resources can be used independently and discretely from each other. --- # Getting started with Ansible — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * Getting started with Ansible * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/getting_started/index.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Getting started with Ansible[](https://docs.ansible.com/projects/ansible-core/devel/getting_started/index.html#getting-started-with-ansible "Link to this heading") ===================================================================================================================================================================== Ansible automates the management of remote systems and controls their desired state. [![Basic components of an Ansible environment include a control node, an inventory of managed nodes, and a module copied to each managed node.](https://docs.ansible.com/projects/ansible-core/devel/_images/ansible_inv_start.svg)](https://docs.ansible.com/projects/ansible-core/devel/_images/ansible_inv_start.svg) As shown in the preceding figure, most Ansible environments have three main components: Control node A system on which Ansible is installed. You run Ansible commands such as `ansible` or `ansible-inventory` on a control node. Inventory A list of managed nodes that are logically organized. You create an inventory on the control node to describe host deployments to Ansible. Managed node A remote system, or host, that Ansible controls. * [Introduction to Ansible](https://docs.ansible.com/projects/ansible-core/devel/getting_started/introduction.html) * [Start automating with Ansible](https://docs.ansible.com/projects/ansible-core/devel/getting_started/get_started_ansible.html) * [Building an inventory](https://docs.ansible.com/projects/ansible-core/devel/getting_started/get_started_inventory.html) * [Creating a playbook](https://docs.ansible.com/projects/ansible-core/devel/getting_started/get_started_playbook.html) * [Ansible concepts](https://docs.ansible.com/projects/ansible-core/devel/getting_started/basic_concepts.html) --- # Controlling how Ansible behaves: precedence rules — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * Controlling how Ansible behaves: precedence rules * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/reference_appendices/general_precedence.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Controlling how Ansible behaves: precedence rules[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/general_precedence.html#controlling-how-ansible-behaves-precedence-rules "Link to this heading") ================================================================================================================================================================================================================================ To give you maximum flexibility in managing your environments, Ansible offers many ways to control how Ansible behaves: how it connects to managed nodes, how it works once it has connected. If you use Ansible to manage a large number of servers, network devices, and cloud resources, you may define Ansible behavior in several different places and pass that information to Ansible in several different ways. This flexibility is convenient, but it can backfire if you do not understand the precedence rules. These precedence rules apply to any setting that can be defined in multiple ways (by configuration settings, command-line options, playbook keywords, variables). [Precedence categories](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/general_precedence.html#id1) [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/general_precedence.html#precedence-categories "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Ansible offers four sources for controlling its behavior. In order of precedence from lowest (most easily overridden) to highest (overrides all others), the categories are: > * Configuration settings > > * Command-line options > > * Playbook keywords > > * Variables > > * Direct Assignment > Each category overrides any information from all lower-precedence categories. For example, a playbook keyword will override any configuration setting. Within each precedence category, specific rules apply. However, generally speaking, ‘last defined’ wins and overrides any previous definitions. ### [Configuration settings](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/general_precedence.html#id2) [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/general_precedence.html#configuration-settings "Link to this heading") [Configuration settings](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/config.html#ansible-configuration-settings) include both values from the `ansible.cfg` file and environment variables. Within this category, values set in configuration files have lower precedence. Ansible uses the first `ansible.cfg` file it finds, ignoring all others. Ansible searches for `ansible.cfg` in these locations in order: > * `ANSIBLE_CONFIG` (environment variable if set) > > * `ansible.cfg` (in the current directory) > > * `~/.ansible.cfg` (in the home directory) > > * `/etc/ansible/ansible.cfg` > Environment variables have a higher precedence than entries in `ansible.cfg`. If you have environment variables set on your control node, they override the settings in whichever `ansible.cfg` file Ansible loads. The value of any given environment variable follows normal shell precedence: the last value defined overwrites previous values. ### [Command-line options](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/general_precedence.html#id3) [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/general_precedence.html#command-line-options "Link to this heading") Any command-line option will override any configuration setting. When you type something directly at the command line, you may feel that your hand-crafted values should override all others, but Ansible does not work that way. Command-line options have low precedence - they override configuration only. They do not override playbook keywords, variables from inventory or variables from playbooks. You can override all other settings from all other sources in all other precedence categories at the command line by [Using -e extra variables at the command line](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/general_precedence.html#general-precedence-extra-vars) , but that is not a command-line option, it is a way of passing a [variable](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/general_precedence.html#general-precedence-variables) . At the command line, if you pass multiple values for a parameter that accepts only a single value, the last defined value wins. For example, this [ad hoc task](https://docs.ansible.com/projects/ansible-core/devel/command_guide/intro_adhoc.html#intro-adhoc) will connect as `carol`, not as `mike`: ansible \-u mike \-m ping myhost \-u carol Some parameters allow multiple values. In this case, Ansible will append all values from the hosts listed in inventory files inventory1 and inventory2: ansible \-i /path/inventory1 \-i /path/inventory2 \-m ping all The help for each [command-line tool](https://docs.ansible.com/projects/ansible-core/devel/command_guide/command_line_tools.html#command-line-tools) lists available options for that tool. ### [Playbook keywords](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/general_precedence.html#id4) [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/general_precedence.html#playbook-keywords "Link to this heading") Any [playbook keyword](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/playbooks_keywords.html#playbook-keywords) will override any command-line option and any configuration setting. Within playbook keywords, precedence flows with the playbook itself; the more specific wins against the more general: * play (most general) * blocks/includes/imports/roles (optional and can contain tasks and each other) * tasks (most specific) A simple example: \- hosts: all connection: ssh tasks: \- name: This task uses ssh. ping: \- name: This task uses paramiko. connection: paramiko ping: In this example, the `connection` keyword is set to `ssh` at the play level. The first task inherits that value, and connects using `ssh`. The second task inherits that value, overrides it, and connects using `paramiko`. The same logic applies to blocks and roles as well. All tasks, blocks, and roles within a play inherit play-level keywords; any task, block, or role can override any keyword by defining a different value for that keyword within the task, block, or role. Remember that these are KEYWORDS, not variables. Both playbooks and variable files are defined in YAML but they have different significance. Playbooks are the command or ‘state description’ structure for Ansible, variables are data we use to help make playbooks more dynamic. ### [Variables](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/general_precedence.html#id5) [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/general_precedence.html#variables "Link to this heading") Ansible variables are very high on the precedence stack. They will override any playbook keyword, any command-line option, environment variable and any configuration file setting. Variables that have equivalent playbook keywords, command-line options, and configuration settings are known as [Connection variables](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/special_variables.html#connection-variables) . Originally designed for connection parameters, this category has expanded to include other core variables like the temporary directory and the python interpreter. Connection variables, like all variables, can be set in multiple ways and places. You can define variables for hosts and groups in [inventory](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#intro-inventory) . You can define variables for tasks and plays in `vars:` blocks in [playbooks](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_intro.html#about-playbooks) . However, they are still variables - they are data, not keywords or configuration settings. Variables that override playbook keywords, command-line options, and configuration settings follow the same rules of [variable precedence](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_variables.html#ansible-variable-precedence) as any other variables. When set in a playbook, variables follow the same inheritance rules as playbook keywords. You can set a value for the play, then override it in a task, block, or role: \- hosts: cloud gather\_facts: false become: true vars: ansible\_become\_user: admin tasks: \- name: This task uses admin as the become user. dnf: name: some-service state: latest \- block: \- name: This task uses service-admin as the become user. \# a task to configure the new service \- name: This task also uses service-admin as the become user, defined in the block. \# second task to configure the service vars: ansible\_become\_user: service-admin \- name: This task (outside of the block) uses admin as the become user again. service: name: some-service state: restarted #### [Variable scope: how long is a value available?](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/general_precedence.html#id6) [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/general_precedence.html#variable-scope-how-long-is-a-value-available "Link to this heading") Variable values set in a playbook exist only within the playbook object that defines them. These ‘playbook object scope’ variables are not available to subsequent objects, including other plays. Variable values associated directly with a host or group, including variables defined in inventory, by vars plugins, or using modules like [set\_fact](https://docs.ansible.com/projects/ansible-core/devel/collections/ansible/builtin/set_fact_module.html#set-fact-module) and [include\_vars](https://docs.ansible.com/projects/ansible-core/devel/collections/ansible/builtin/include_vars_module.html#include-vars-module) , are available to all plays. These ‘host scope’ variables are also available through the `hostvars[]` dictionary. Variables set through `extra vars` have a global scope for the current run and will be present both as ‘playbook object vars’ and ‘hostvars’. #### [Using `-e` extra variables at the command line](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/general_precedence.html#id7) [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/general_precedence.html#using-e-extra-variables-at-the-command-line "Link to this heading") To override all other variables, you can use extra variables: `--extra-vars` or `-e` at the command line. Values passed with `-e`, while still a command-line option itself, have the highest precedence among variables and will, a bit counter intuitively, be of the higher precedence among most configuration sources, since variables themselves have high precedence. For example, this task will connect as `brian` not as `carol`: ansible \-u carol \-e 'ansible\_user=brian' \-a whoami all You must specify both the variable name and the value with `--extra-vars`. ### [Direct Assignment](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/general_precedence.html#id8) [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/general_precedence.html#direct-assignment "Link to this heading") This category only applies to things that take direct options, generally modules and some plugin types. Most modules and action plugins do not have any other way to assign settings so precedence rarely comes up in that context, but it still possible for some of them to do so and should be reflected in the documentation. \- debug: msg='this is a direct assignment option to an action plugin' \- ping: data: also a direct assignment Outside of task actions, the most recognizable ‘direct assignments’ are with lookup, filter and test plugins: lookup('plugin', direct1='value', direct2='value2') 'value\_directly\_assigned'|filter('another directly assigned') 'direct value' is testplugin Though most of these are not configured in other ways, specially tests, it is possible for plugins and filters to use input from other configuration sources if specified in their documentation. Inventory plugins are a bit tricky as they use ‘inventory sources’ and these sometimes can look like a configuration file and are passed in as a command line option, yet it is still considered ‘direct assignment’. It is a bit clearer when using an inline source `-i host1, host2, host3` than when using a file source `-i /path/to/inventory_source`, but they both have the same precedence. --- # YAML Syntax — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * YAML Syntax * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/reference_appendices/YAMLSyntax.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * YAML Syntax[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/YAMLSyntax.html#yaml-syntax "Link to this heading") ============================================================================================================================================= This page provides a basic overview of correct YAML syntax, which is how Ansible playbooks (our configuration management language) are expressed. We use YAML because it is easier for humans to read and write than other common data formats like XML or JSON. Further, there are libraries available in most programming languages for working with YAML. You may also wish to read [Working with playbooks](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks.html#working-with-playbooks) at the same time to see how this is used in practice. YAML Basics[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/YAMLSyntax.html#yaml-basics "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------- For Ansible, nearly every YAML file starts with a list. Each item in the list is a list of key/value pairs, commonly called a “hash” or a “dictionary”. So, we need to know how to write lists and dictionaries in YAML. There’s another small quirk to YAML. All YAML files (regardless of their association with Ansible or not) can optionally begin with `---` and end with `...`. This is part of the YAML format and indicates the start and end of a document. All members of a list are lines beginning at the same indentation level starting with a `"- "` (a dash and a space): \--- \# A list of tasty fruits \- Apple \- Orange \- Strawberry \- Mango ... A dictionary is represented in a simple `key: value` form (the colon must be followed by a space): \# An employee record martin: name: Martin D'vloper job: Developer skill: Elite More complicated data structures are possible, such as lists of dictionaries, dictionaries whose values are lists or a mix of both: \# Employee records \- martin: name: Martin D'vloper job: Developer skills: \- python \- perl \- pascal \- tabitha: name: Tabitha Bitumen job: Developer skills: \- lisp \- fortran \- erlang Dictionaries and lists can also be represented in an abbreviated form if you really want to: \--- martin: {name: Martin D'vloper, job: Developer, skill: Elite} fruits: \['Apple', 'Orange', 'Strawberry', 'Mango'\] These are called “Flow collections”. Ansible doesn’t really use these too much, but you can also specify a [boolean value](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_variables.html#playbooks-variables) (true/false) in several forms: create\_key: true needs\_agent: false knows\_oop: True likes\_emacs: TRUE uses\_cvs: false Use lowercase ‘true’ or ‘false’ for boolean values in dictionaries if you want to be compatible with default yamllint options. Values can span multiple lines using `|` or `>`. Spanning multiple lines using a “Literal Block Scalar” `|` will include the newlines and any trailing spaces. Using a “Folded Block Scalar” `>` will fold newlines to spaces; it is used to make what would otherwise be a very long line easier to read and edit. In either case the indentation will be ignored. Examples are: include\_newlines: | exactly as you see will appear these three lines of poetry fold\_newlines: \> this is really a single line of text despite appearances While in the above `>` example all newlines are folded into spaces, there are two ways to enforce a newline to be kept: fold\_some\_newlines: \> a b c d e f Alternatively, it can be enforced by including newline `\n` characters: fold\_same\_newlines: "a b\\nc d\\n e\\nf\\n" Let’s combine what we learned so far in an arbitrary YAML example. This really has nothing to do with Ansible, but will give you a feel for the format: \--- \# An employee record name: Martin D'vloper job: Developer skill: Elite employed: True foods: \- Apple \- Orange \- Strawberry \- Mango languages: perl: Elite python: Elite pascal: Lame education: | 4 GCSEs 3 A-Levels BSc in the Internet of Things That’s all you really need to know about YAML to start writing Ansible playbooks. Gotchas[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/YAMLSyntax.html#gotchas "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------- While you can put just about anything into an unquoted scalar, there are some exceptions. A colon followed by a space (or newline) `": "` is an indicator for a mapping. A space followed by the pound sign `" #"` starts a comment. Because of this, the following is going to result in a YAML syntax error: foo: somebody said I should put a colon here: so I did windows\_drive: c: …but this will work: windows\_path: c:\\windows You will want to quote hash values using colons followed by a space or the end of the line: foo: 'somebody said I should put a colon here: so I did' windows\_drive: 'c:' …and then the colon will be preserved. Alternatively, you can use double quotes: foo: "somebody said I should put a colon here: so I did" windows\_drive: "c:" The difference between single quotes and double quotes is that in double quotes you can use escapes: foo: "a \\t TAB and a \\n NEWLINE" The list of allowed escapes can be found in the YAML Specification under “Escape Sequences” (YAML 1.1) or “Escape Characters” (YAML 1.2). The following is invalid YAML: foo: "an escaped \\' single quote" Further, Ansible uses “{{ var }}” for variables. If a value after a colon starts with a “{”, YAML will think it is a dictionary, so you must quote it, like so: foo: "{{ variable }}" If your value starts with a quote the entire value must be quoted, not just part of it. Here are some additional examples of how to properly quote things: foo: "{{ variable }}/additional/string/literal" foo2: "{{ variable }}\\\\backslashes\\\\are\\\\also\\\\special\\\\characters" foo3: "even if it is just a string literal it must all be quoted" Not valid: foo: "E:\\\\path\\\\"rest\\\\of\\\\path In addition to `'` and `"` there are a number of characters that are special (or reserved) and cannot be used as the first character of an unquoted scalar: ``[] {} > | * & ! % # ` @ ,``. You should also be aware of `? : -`. In YAML, they are allowed at the beginning of a string if a non-space character follows, but YAML processor implementations differ, so it is better to use quotes. In Flow Collections, the rules are a bit more strict: a scalar in block mapping: this } is \[ all , valid\ \ flow mapping: { key: "you { should \[ use , quotes here" }\ \ Boolean conversion is helpful, but this can be a problem when you want a literal yes or other boolean values as a string. In these cases just use quotes:\ \ non\_boolean: "yes"\ other\_string: "False"\ \ YAML converts certain strings into floating-point values, such as the string 1.0. If you need to specify a version number (in a requirements.yml file, for example), you will need to quote the value if it looks like a floating-point value:\ \ version: "1.0"\ \ See also\ \ [Working with playbooks](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks.html#working-with-playbooks)\ \ Learn what playbooks can do and how to write/run them.\ \ [YAMLLint](http://yamllint.com/)\ \ YAML Lint (online) helps you debug YAML syntax if you are having problems\ \ [Wikipedia YAML syntax reference](https://en.wikipedia.org/wiki/YAML)\ \ A good guide to YAML syntax\ \ [YAML 1.1 Specification](https://yaml.org/spec/1.1/)\ \ The Specification for YAML 1.1, which PyYAML and libyaml are currently implementing\ \ [YAML 1.2 Specification](https://yaml.org/spec/1.2/spec.html)\ \ For completeness, YAML 1.2 is the successor of 1.1\ \ [Communication](https://docs.ansible.com/projects/ansible-core/devel/community/communication.html#communication)\ \ Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide --- # antsibull-docs Release Notes - antsibull-docs – Ansible Documentation Build Scripts [Skip to content](https://docs.ansible.com/projects/antsibull-docs/changelog/#antsibull-docs-ansible-documentation-build-scripts-release-notes) antsibull-docs -- Ansible Documentation Build Scripts Release Notes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#antsibull-docs-ansible-documentation-build-scripts-release-notes "Permanent link") ====================================================================================================================================================================================================================== v2.24.0[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v2240 "Permanent link") ----------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary "Permanent link") Feature release to improve linting. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#minor-changes "Permanent link") * Allow to output linting results as JSON ([https://github.com/ansible-community/antsibull-docs/pull/437](https://github.com/ansible-community/antsibull-docs/pull/437) ). * When copying collections to a temporary directory for reading their documentation with ansible-doc, detect whether they are part of Git repositories, and if yes, do not copy ignored files ([https://github.com/ansible-community/antsibull-docs/pull/438](https://github.com/ansible-community/antsibull-docs/pull/438) ). v2.23.1[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v2231 "Permanent link") ----------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_1 "Permanent link") Bugfix release. ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#bugfixes "Permanent link") * Do not reject role argument specs that use `mutually_exclusive`, `required_one_of`, `required_by`, `required_if`, or `required_together` ([https://github.com/ansible-community/antsibull-docs/issues/434](https://github.com/ansible-community/antsibull-docs/issues/434) , [https://github.com/ansible-community/antsibull-docs/pull/435](https://github.com/ansible-community/antsibull-docs/pull/435) ). v2.23.0[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v2230 "Permanent link") ----------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_2 "Permanent link") Feature release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#minor-changes_1 "Permanent link") * Add new RST roles `:ansoptref:` and `:ansretvalref:` which allow to reference options and return values with explicit titles ([https://github.com/ansible-community/antsibull-docs/pull/430](https://github.com/ansible-community/antsibull-docs/pull/430) ). v2.22.1[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v2221 "Permanent link") ----------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_3 "Permanent link") Maintenance release. ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#bugfixes_1 "Permanent link") * Adjust docs.ansible.com URLs to the new `projects/` structure ([https://github.com/ansible-community/antsibull-docs/pull/428](https://github.com/ansible-community/antsibull-docs/pull/428) ). v2.22.0[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v2220 "Permanent link") ----------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_4 "Permanent link") Bugfix and maintenance release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#minor-changes_2 "Permanent link") * Declare support for Python 3.14 ([https://github.com/ansible-community/antsibull-docs/pull/425](https://github.com/ansible-community/antsibull-docs/pull/425) ). * Uses new logging framework provided by antsibull-core. This currently has no user-observable impact, but that will change with later versions of antsibull-core ([https://github.com/ansible-community/antsibull-docs/pull/414](https://github.com/ansible-community/antsibull-docs/pull/414) ). * antsibull-docs now depends on antsibull-core 3.5.0+ ([https://github.com/ansible-community/antsibull-docs/pull/414](https://github.com/ansible-community/antsibull-docs/pull/414) ). ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#bugfixes_2 "Permanent link") * Remove unnecessary part from template ([https://github.com/ansible-community/antsibull-docs/pull/423](https://github.com/ansible-community/antsibull-docs/pull/423) ). v2.21.0[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v2210 "Permanent link") ----------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_5 "Permanent link") Feature release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#minor-changes_3 "Permanent link") * Add an index for all deprecated collections (official docsite only) and plugins ([https://github.com/ansible-community/antsibull-docs/pull/413](https://github.com/ansible-community/antsibull-docs/pull/413) ). v2.20.0[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v2200 "Permanent link") ----------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_6 "Permanent link") Bugfix and feature release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#minor-changes_4 "Permanent link") * Add `--config` parameter to the `ansible-output` subcommand to allow specifying a config file when not in collection mode ([https://github.com/ansible-community/antsibull-docs/pull/410](https://github.com/ansible-community/antsibull-docs/pull/410) ). * Add `ansible-output-meta` directive that allows to apply meta actions, like resetting previous code blocks for variable references, or defining templates for `ansible-output-data` ([https://github.com/ansible-community/antsibull-docs/pull/409](https://github.com/ansible-community/antsibull-docs/pull/409) ). * Allow to specify YAML inventory for `ansible-output` subcommand code blocks ([https://github.com/ansible-community/antsibull-docs/pull/411](https://github.com/ansible-community/antsibull-docs/pull/411) ). * Let `ansible-output` subcommand run `ansible-playbook` instances in parallel ([https://github.com/ansible-community/antsibull-docs/pull/407](https://github.com/ansible-community/antsibull-docs/pull/407) , [https://github.com/ansible-community/antsibull-docs/pull/408](https://github.com/ansible-community/antsibull-docs/pull/408) ). ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#bugfixes_3 "Permanent link") * Run the post-processors in the `ansible-output` subcommand from the current working directory, and not from the temporary playbook directory. This allows post-processors to have relative paths from where `antsibull-docs ansible-output` is called ([https://github.com/ansible-community/antsibull-docs/pull/406](https://github.com/ansible-community/antsibull-docs/pull/406) ). v2.19.1[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v2191 "Permanent link") ----------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_7 "Permanent link") Bugfix release for official docsite build. ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#bugfixes_4 "Permanent link") * Remove `ansible._protomatter` from the collection list if no plugins are found for it and it has not been explicitly added to the collection list ([https://github.com/ansible-community/antsibull-docs/pull/405](https://github.com/ansible-community/antsibull-docs/pull/405) ). * Remove old hint on configuration settings precedence. The new note makes this one superfluous ([https://github.com/ansible-community/antsibull-docs/pull/404](https://github.com/ansible-community/antsibull-docs/pull/404) ). v2.19.0[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v2190 "Permanent link") ----------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_8 "Permanent link") Bugfix and feature release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#minor-changes_5 "Permanent link") * Add a new subcommand `ansible-output` which allows to render Ansible output into RST code blocks ([https://github.com/ansible-community/antsibull-docs/pull/397](https://github.com/ansible-community/antsibull-docs/pull/397) , [https://github.com/ansible-community/antsibull-docs/pull/401](https://github.com/ansible-community/antsibull-docs/pull/401) , [https://github.com/ansible-community/antsibull-docs/pull/402](https://github.com/ansible-community/antsibull-docs/pull/402) ). * Antsibull-docutils 1.3.0+ is now an explicit dependency ([https://github.com/ansible-community/antsibull-docs/pull/395](https://github.com/ansible-community/antsibull-docs/pull/395) ). * For plugin options that can be configured through other means (Ansible variables, INI entries, environment variables, keywords, CLI arguments), show a notice on precedence below the plugin's parameters if more than one such way is present for an option ([https://github.com/ansible-community/antsibull-docs/pull/400](https://github.com/ansible-community/antsibull-docs/pull/400) , [https://github.com/ansible-community/antsibull-docs/pull/403](https://github.com/ansible-community/antsibull-docs/pull/403) ). * When linting extra docs, verify that files referenced in toctrees exist ([https://github.com/ansible-community/antsibull-docs/issues/398](https://github.com/ansible-community/antsibull-docs/issues/398) , [https://github.com/ansible-community/antsibull-docs/pull/395](https://github.com/ansible-community/antsibull-docs/pull/395) ). ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#bugfixes_5 "Permanent link") * Fix bug that hid keyword config for plugin options for options that are only configurable this way ([https://github.com/ansible-community/antsibull-docs/pull/403](https://github.com/ansible-community/antsibull-docs/pull/403) ). v2.18.0[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v2180 "Permanent link") ----------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_9 "Permanent link") Feature and bugfix release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#minor-changes_6 "Permanent link") * Add `:anscollection:` role to allow referencing collections. The syntax is `` :anscollection:`namespace.name` ``, or `` :anscollection:`namespace.name#what` `` for more specific parts of the index page ([https://github.com/ansible-community/antsibull-docs/pull/393](https://github.com/ansible-community/antsibull-docs/pull/393) ). * Extend `:ansplugin:` role to allow referencing role entrypoints. The syntax is `` :ansplugin:`namespace.name.role_name#entrypoint` `` ([https://github.com/ansible-community/antsibull-docs/pull/393](https://github.com/ansible-community/antsibull-docs/pull/393) ). * The `lint-collection-docs` subcommand has a new option `--check-extra-docs-refs` that checks references to collections in extra documentation files (`docs/docsite/rst`) ([https://github.com/ansible-community/antsibull-docs/pull/392](https://github.com/ansible-community/antsibull-docs/pull/392) ). * The `lint-collection-docs`'s option `--plugin-docs` now also checks role entrypoints for existence ([https://github.com/ansible-community/antsibull-docs/pull/392](https://github.com/ansible-community/antsibull-docs/pull/392) ). ### Deprecated Features[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#deprecated-features "Permanent link") * The following default values for options to `antsibull-docs lint-collection-docs` are deprecated and will change in antsibull-docs 3.0.0: * `--plugin-docs` will be enabled by default; right now the default is `--no-plugin-docs`; * `--skip-rstcheck` will be enabled by default; right now the default is `--no-skip-rstcheck` (note that this applies to `--plugin-docs`, not to checking extra documentation); * `--check-extra-docs-refs` will be enabled by default; right now the default is `--no-check-extra-docs-refs`. We suggested to already now explicitly state the default value if you do not want the extra checks to be run ([https://github.com/ansible-community/antsibull-docs/pull/394](https://github.com/ansible-community/antsibull-docs/pull/394) ). ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#bugfixes_6 "Permanent link") * Ansible-core 2.19 now lists standard Jinja2 tests and filters as members of `ansible.builtin` with minimal documentation, but without a `name` field in `doc` ([https://github.com/ansible-community/antsibull-docs/pull/393](https://github.com/ansible-community/antsibull-docs/pull/393) ). v2.17.1[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v2171 "Permanent link") ----------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_10 "Permanent link") Bugfix release with updated antsibull-fileutils dependency. ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#bugfixes_7 "Permanent link") * Using the new util from `antsibull-fileutils >= 1.3.0` to prevent copying the collections tree into a temporary directory structure that already lives inside a `ansible_collections` tree, which triggers a bug in ansible-core ([https://github.com/ansible-community/antsibull-docs/pull/391](https://github.com/ansible-community/antsibull-docs/pull/391) ). v2.17.0[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v2170 "Permanent link") ----------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_11 "Permanent link") Feature and bugfix release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#minor-changes_7 "Permanent link") * Extend deprecation/removal note that collections can be installed manually after removal ([https://github.com/ansible-community/antsibull-docs/pull/371](https://github.com/ansible-community/antsibull-docs/pull/371) ). ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#bugfixes_8 "Permanent link") * Make sure that all errors are caught during documentation normalization. Until now exceptions derived from `BaseException` that are not derived from `Exception` are not handled correctly ([https://github.com/ansible-community/antsibull-docs/pull/389](https://github.com/ansible-community/antsibull-docs/pull/389) ). v2.16.3[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v2163 "Permanent link") ----------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_12 "Permanent link") Bugfix release. ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#bugfixes_9 "Permanent link") * Fix rendering of `HORIZONTALLINE` in reStructuredText output. An earlier fix for leading whitespace mangled the resulting `raw` directive ([https://github.com/ansible-community/antsibull-docs/pull/370](https://github.com/ansible-community/antsibull-docs/pull/370) ). * When `choices` are provided as a dictionary with explanations, links to options, return values, modules, plugins, and roles were not correctly rendered ([https://github.com/ansible-community/antsibull-docs/pull/369](https://github.com/ansible-community/antsibull-docs/pull/369) ). v2.16.2[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v2162 "Permanent link") ----------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_13 "Permanent link") Bugfix release. ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#bugfixes_10 "Permanent link") * Fix role section heading levels. Examples and attributes should be below role entrypoints ([https://github.com/ansible-community/antsibull-docs/issues/366](https://github.com/ansible-community/antsibull-docs/issues/366) , [https://github.com/ansible-community/antsibull-docs/pull/367](https://github.com/ansible-community/antsibull-docs/pull/367) ). v2.16.1[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v2161 "Permanent link") ----------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_14 "Permanent link") Bugfix release. ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#bugfixes_11 "Permanent link") * Also consider action plugin redirects/deprecations in runtime metadata for modules, since for users there is no difference. Also `ansible.builtin.yum` only has a action plugin redirect to `ansible.builtin.dnf`, so this is needed to ensure that a stub page generated for `ansible.builtin.yum` ([https://github.com/ansible-community/antsibull-docs/pull/360](https://github.com/ansible-community/antsibull-docs/pull/360) ). v2.16.0[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v2160 "Permanent link") ----------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_15 "Permanent link") Feature release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#minor-changes_8 "Permanent link") * Allow to cancel collection deprecations ([https://github.com/ansible-community/antsibull-docs/pull/352](https://github.com/ansible-community/antsibull-docs/pull/352) ). * Declare support for Python 3.13 ([https://github.com/ansible-community/antsibull-docs/pull/349](https://github.com/ansible-community/antsibull-docs/pull/349) ). * antsibull-docs now depends on antsibull-core >= 3.4.0 ([https://github.com/ansible-community/antsibull-docs/pull/352](https://github.com/ansible-community/antsibull-docs/pull/352) ). v2.15.0[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v2150 "Permanent link") ----------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_16 "Permanent link") Bugfix and feature release which migrates to Pydantic 2. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#minor-changes_9 "Permanent link") * Migrated all models to Pydantic 2. This is mostly transparent, except that validation error messages slightly change, and that some validation is more strict. For example, if a boolean is used instead of a string, say in a description, this now results in an error instead of a silent coercion. Numbers are still accepted for strings (for example `version_added` with float values like `2.14`) ([https://github.com/ansible-community/antsibull-docs/pull/331](https://github.com/ansible-community/antsibull-docs/pull/331) , [https://github.com/ansible-community/antsibull-core/pull/333](https://github.com/ansible-community/antsibull-core/pull/333) , [https://github.com/ansible-community/antsibull-core/pull/344](https://github.com/ansible-community/antsibull-core/pull/344) ). * This project now depends on antsibull-core >= 3.2.0 and pydantic 2 ([https://github.com/ansible-community/antsibull-docs/pull/330](https://github.com/ansible-community/antsibull-docs/pull/330) ). * Use Proxy configuration settings from the environment. Check out the [aiohttp documentation on Proxy support](https://docs.aiohttp.org/en/stable/client_advanced.html#proxy-support) for information on which environment variables are supported ([https://github.com/ansible/ansible-documentation/issues/1936](https://github.com/ansible/ansible-documentation/issues/1936) , [https://github.com/ansible-community/antsibull-docs/pull/346](https://github.com/ansible-community/antsibull-docs/pull/346) ). * Use language `ini` for example INI code blocks ([https://github.com/ansible-community/antsibull-docs/pull/335](https://github.com/ansible-community/antsibull-docs/pull/335) ). * When rendering the Ansible docsite with the `stable` and `devel` subcommands, information on deprecated collections is shown ([https://github.com/ansible-community/ansible-build-data/pull/450](https://github.com/ansible-community/ansible-build-data/pull/450) , [https://github.com/ansible-community/antsibull-docs/pull/330](https://github.com/ansible-community/antsibull-docs/pull/330) ). * When rendering the Ansible docsite with the `stable` and `devel` subcommands, stub pages for removed collections are added ([https://github.com/ansible-community/ansible-build-data/pull/459](https://github.com/ansible-community/ansible-build-data/pull/459) , [https://github.com/ansible-community/antsibull-docs/pull/341](https://github.com/ansible-community/antsibull-docs/pull/341) ). v2.14.0[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v2140 "Permanent link") ----------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_17 "Permanent link") Feature release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#minor-changes_10 "Permanent link") * Add dependency on antsibull-fileutils. Some functionality from antsibull-core is moving there, so we can use it from there directly ([https://github.com/ansible-community/antsibull-docs/pull/322](https://github.com/ansible-community/antsibull-docs/pull/322) ). * Add deprecation markers next to module/plugin/role descriptions in lists ([https://github.com/ansible-community/antsibull-docs/issues/141](https://github.com/ansible-community/antsibull-docs/issues/141) , [https://github.com/ansible-community/antsibull-docs/pull/320](https://github.com/ansible-community/antsibull-docs/pull/320) ). * Remove ansible-project Google Groups mailing list from ansible.builtin links ([https://github.com/ansible-community/antsibull-docs/pull/325](https://github.com/ansible-community/antsibull-docs/pull/325) ). v2.13.1[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v2131 "Permanent link") ----------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_18 "Permanent link") Bugfix release. ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#bugfixes_12 "Permanent link") * The output filename used by the `plugin` subcommand contained two dots before the `rst` extension ([https://github.com/ansible-community/antsibull-docs/issues/317](https://github.com/ansible-community/antsibull-docs/issues/317) , [https://github.com/ansible-community/antsibull-docs/pull/318](https://github.com/ansible-community/antsibull-docs/pull/318) ). v2.13.0[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v2130 "Permanent link") ----------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_19 "Permanent link") Bugfix and feature release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#minor-changes_11 "Permanent link") * Allow to disable adding the antsibull-docs version to the generated files with the `--no-add-antsibull-docs-version` command line flag, or the `add_antsibull_docs_version = false` setting in the antsibull-docs config file ([https://github.com/ansible-community/antsibull-docs/issues/304](https://github.com/ansible-community/antsibull-docs/issues/304) , [https://github.com/ansible-community/antsibull-docs/pull/308](https://github.com/ansible-community/antsibull-docs/pull/308) ). * Bump minimal required version of dependency antsibull-docs-parser to 1.1.0 This allows to use a new whitespace-removal feature ([https://github.com/ansible-community/antsibull-docs/pull/312](https://github.com/ansible-community/antsibull-docs/pull/312) ). * If you are using [argcomplete](https://pypi.org/project/argcomplete/) , you can now tab-complete `antsibull-docs` command lines. See [Activating global completion](https://pypi.org/project/argcomplete/#activating-global-completion) in the argcomplete README for how to enable tab completion globally. This will also tab-complete Ansible commands such as `ansible-playbook` and `ansible-test` ([https://github.com/ansible-community/antsibull-docs/pull/302](https://github.com/ansible-community/antsibull-docs/pull/302) ). * Most documentation generating subcommands now have a `--cleanup` parameter which allows to delete files and directories that were not created by antsibull-docs in the destination directory ([https://github.com/ansible-community/antsibull-docs/pull/315](https://github.com/ansible-community/antsibull-docs/pull/315) ). * No longer use `rsync` when creating a build script with the `sphinx-init` subcommand ([https://github.com/ansible-community/antsibull-docs/pull/315](https://github.com/ansible-community/antsibull-docs/pull/315) ). * Remove superfluous whitespace or escaped spaces from templates ([https://github.com/ansible-community/antsibull-docs/pull/313](https://github.com/ansible-community/antsibull-docs/pull/313) ). * Remove trailing whitespace and leading and trailing empty lines from rendered templates, and ensure they end with a newline if not empty ([https://github.com/ansible-community/antsibull-docs/pull/314](https://github.com/ansible-community/antsibull-docs/pull/314) ). ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#bugfixes_13 "Permanent link") * Fix RST escaping of the title in the collections per namespace list. This causes a space to vanish between namespace name and the word `Namespace` with newer versions of antsibull-docs-parser ([https://github.com/ansible-community/antsibull-docs/pull/311](https://github.com/ansible-community/antsibull-docs/pull/311) ). v2.12.0[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v2120 "Permanent link") ----------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_20 "Permanent link") Bugfix and feature release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#minor-changes_12 "Permanent link") * Allow to mention forums in the Communication section of collection links ([https://github.com/ansible-community/antsibull-docs/pull/288](https://github.com/ansible-community/antsibull-docs/pull/288) ). * Bump minimum dependency of `antsibull-docs-parser` to 1.0.2 or newer ([https://github.com/ansible-community/antsibull-docs/pull/290](https://github.com/ansible-community/antsibull-docs/pull/290) ). * The `lint-collection-docs` subcommand will now complain about unchanged default values in `docs/docsite/links.yml` taken from the [community collection template](https://github.com/ansible-collections/collection_template/) ([https://github.com/ansible-community/antsibull-docs/issues/273](https://github.com/ansible-community/antsibull-docs/issues/273) , [https://github.com/ansible-community/antsibull-docs/pull/277](https://github.com/ansible-community/antsibull-docs/pull/277) ). * The collection docs linter now reports empty markup, like `I()`, `L(,https://example.com)` ([https://github.com/ansible-community/antsibull-docs/pull/292](https://github.com/ansible-community/antsibull-docs/pull/292) ). ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#bugfixes_14 "Permanent link") * Improve handling of empty markup parameters for RST ([https://github.com/ansible-community/antsibull-docs/pull/290](https://github.com/ansible-community/antsibull-docs/pull/290) ). * Improve rendering of empty or broken changelogs ([https://github.com/ansible-community/antsibull-docs/pull/289](https://github.com/ansible-community/antsibull-docs/pull/289) ). * Remove leading spaces in paragraphs to avoid unintended RST blockquotes ([https://github.com/ansible-community/antsibull-docs/pull/289](https://github.com/ansible-community/antsibull-docs/pull/289) ). * Render errors as code blocks of language `text` instead of using the default lexer ([https://github.com/ansible-community/antsibull-docs/pull/289](https://github.com/ansible-community/antsibull-docs/pull/289) ). v2.11.0[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v2110 "Permanent link") ----------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_21 "Permanent link") Feature and bugfix release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#minor-changes_13 "Permanent link") * Support examples for role entrypoints ([https://github.com/ansible-community/antsibull-docs/pull/244](https://github.com/ansible-community/antsibull-docs/pull/244) ). ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#bugfixes_15 "Permanent link") * Fix handling of `choices` that are dictionaries for `type=list` ([https://github.com/ansible-community/antsibull-docs/pull/276](https://github.com/ansible-community/antsibull-docs/pull/276) ). * Fix handling of `default` for `type=list` if `choices` is present ([https://github.com/ansible-community/antsibull-docs/pull/276](https://github.com/ansible-community/antsibull-docs/pull/276) ). v2.10.0[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v2100 "Permanent link") ----------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_22 "Permanent link") Bugfix and feature release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#minor-changes_14 "Permanent link") * It is now possible to render the collection changelog as part of the collection docsite by using the `changelog` option in `docs/docsite/config.yml` ([https://github.com/ansible-community/antsibull-docs/issues/31](https://github.com/ansible-community/antsibull-docs/issues/31) , [https://github.com/ansible-community/antsibull-docs/pull/267](https://github.com/ansible-community/antsibull-docs/pull/267) ). ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#bugfixes_16 "Permanent link") * Fix internal links to options and return values in simplified RST output ([https://github.com/ansible-community/antsibull-docs/pull/269](https://github.com/ansible-community/antsibull-docs/pull/269) ). * Include role in role attribute references ([https://github.com/ansible-community/antsibull-docs/pull/269](https://github.com/ansible-community/antsibull-docs/pull/269) ). v2.9.0[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v290 "Permanent link") --------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_23 "Permanent link") Maintenance release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#minor-changes_15 "Permanent link") * Add support for the antsibull-core v3 ([https://github.com/ansible-community/antsibull-docs/pull/261](https://github.com/ansible-community/antsibull-docs/pull/261) ). v2.8.0[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v280 "Permanent link") --------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_24 "Permanent link") Bugfix and feature release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#minor-changes_16 "Permanent link") * Add support for "dark mode" to the option table styling ([https://github.com/ansible-community/antsibull-docs/pull/253](https://github.com/ansible-community/antsibull-docs/pull/253) , [https://github.com/ansible-community/antsibull-docs/pull/258](https://github.com/ansible-community/antsibull-docs/pull/258) ). * Add support for the latest antsibull-core v3 pre-release, `3.0.0a1` ([https://github.com/ansible-community/antsibull-docs/pull/250](https://github.com/ansible-community/antsibull-docs/pull/250) ). * Declare support for Python 3.12 ([https://github.com/ansible-community/antsibull-docs/pull/255](https://github.com/ansible-community/antsibull-docs/pull/255) ). * The colors used by the CSS provided by the Antsibull Sphinx extension can now be overridden ([https://github.com/ansible-community/antsibull-docs/pull/254](https://github.com/ansible-community/antsibull-docs/pull/254) ). ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#bugfixes_17 "Permanent link") * Fix duplicate docs detection (for aliases) for latest ansible-core devel ([https://github.com/ansible-community/antsibull-docs/pull/257](https://github.com/ansible-community/antsibull-docs/pull/257) ). v2.7.0[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v270 "Permanent link") --------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_25 "Permanent link") Bugfix and refactoring release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#minor-changes_17 "Permanent link") * Explicitly set up Galaxy context instead of relying on deprecated functionality ([https://github.com/ansible-community/antsibull-docs/pull/234](https://github.com/ansible-community/antsibull-docs/pull/234) ). ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#bugfixes_18 "Permanent link") * Fix schema for `seealso` in role entrypoints. Plugin references now work ([https://github.com/ansible-community/antsibull-docs/issues/237](https://github.com/ansible-community/antsibull-docs/issues/237) , [https://github.com/ansible-community/antsibull-docs/pull/240](https://github.com/ansible-community/antsibull-docs/pull/240) ). * Make error reporting for invalid references in `plugin` `seealso` entries more precise ([https://github.com/ansible-community/antsibull-docs/pull/240](https://github.com/ansible-community/antsibull-docs/pull/240) ). * Support new `ansible-doc --json` output field `plugin_name` ([https://github.com/ansible-community/antsibull-docs/pull/242](https://github.com/ansible-community/antsibull-docs/pull/242) ). * Use certain fields from library context instead of app context that are deprecated in the app context and will be removed from antsibull-core 3.0.0 ([https://github.com/ansible-community/antsibull-docs/pull/233](https://github.com/ansible-community/antsibull-docs/pull/233) ). v2.6.1[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v261 "Permanent link") --------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_26 "Permanent link") Bugfix release. ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#bugfixes_19 "Permanent link") * For role argument specs, allow `author`, `description`, and `todo` to be a string instead of a list of strings, similarly as with ansible-doc and with modules and plugins ([https://github.com/ansible-community/antsibull-docs/pull/227](https://github.com/ansible-community/antsibull-docs/pull/227) ). * Make sure that title underlines have the correct width for wide Unicode characters ([https://github.com/ansible-community/antsibull-docs/issues/228](https://github.com/ansible-community/antsibull-docs/issues/228) , [https://github.com/ansible-community/antsibull-docs/pull/229](https://github.com/ansible-community/antsibull-docs/pull/229) ). v2.6.0[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v260 "Permanent link") --------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_27 "Permanent link") Fix parsing of `EXAMPLES` and improve error message ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#minor-changes_18 "Permanent link") * Improve error messages when calls to `ansible-doc` fail ([https://github.com/ansible-community/antsibull-docs/pull/223](https://github.com/ansible-community/antsibull-docs/pull/223) ). ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#bugfixes_20 "Permanent link") * When `EXAMPLES` has the format specified by `# fmt: `, this value is used to determine the code block type ([https://github.com/ansible-community/antsibull-docs/pull/225](https://github.com/ansible-community/antsibull-docs/pull/225) ). v2.5.0[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v250 "Permanent link") --------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_28 "Permanent link") Release to support the updated Ansible Galaxy codebase. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#minor-changes_19 "Permanent link") * The default collection URL template has been changed from `https://galaxy.ansible.com/{namespace}/{name}` to `https://galaxy.ansible.com/ui/repo/published/{namespace}/{name}/` to adjust for the Galaxy codebase change on September 30th, 2023 ([https://github.com/ansible-community/antsibull-docs/issues/147](https://github.com/ansible-community/antsibull-docs/issues/147) , [https://github.com/ansible-community/antsibull-docs/pull/220](https://github.com/ansible-community/antsibull-docs/pull/220) ). v2.4.0[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v240 "Permanent link") --------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_29 "Permanent link") Bugfix and feature release. Improves support for other builders than `html`. There will be a follow-up release after [Ansible Galaxy](https://galaxy.ansible.com/) switched to the new `galaxy_ng` codebase, which is scheduled for September 30th. That release will only adjust the URLs to Galaxy, except potentially bugfixes. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#minor-changes_20 "Permanent link") * Add basic support for other HTML based Sphinx builders such as `epub` and `singlehtml` ([https://github.com/ansible-community/antsibull-docs/pull/201](https://github.com/ansible-community/antsibull-docs/pull/201) ). * Adjust default RST output to work better with Spinx's LaTeX builder ([https://github.com/ansible-community/antsibull-docs/pull/195](https://github.com/ansible-community/antsibull-docs/pull/195) ). * Allow specifying wildcards for the collection names for the `collections` subcommand if `--use-current` is specified ([https://github.com/ansible-community/antsibull-docs/pull/219](https://github.com/ansible-community/antsibull-docs/pull/219) ). * Antsibull-docs now depends on antsibull-core >= 2.1.0 ([https://github.com/ansible-community/antsibull-docs/pull/209](https://github.com/ansible-community/antsibull-docs/pull/209) ). * Create collection links with a custom directive. This makes them compatible with builders other than the HTML builder ([https://github.com/ansible-community/antsibull-docs/pull/200](https://github.com/ansible-community/antsibull-docs/pull/200) ). * Fix indent for nested options and return values with Spinx's LaTeX builder ([https://github.com/ansible-community/antsibull-docs/pull/198](https://github.com/ansible-community/antsibull-docs/pull/198) ). * Improve linting of option and return value names in semantic markup with respect to array stubs: forbid array stubs for dictionaries if the dictionary is not the last part of the option ([https://github.com/ansible-community/antsibull-docs/pull/208](https://github.com/ansible-community/antsibull-docs/pull/208) ). * Improve the info box for `ansible.builtin` plugins and modules to explain FQCN and link to the `collection` keyword docs ([https://github.com/ansible-community/antsibull-docs/pull/218](https://github.com/ansible-community/antsibull-docs/pull/218) ). * Improve the info box for modules, plugins, and roles in collections to show note that they are not included in `ansible-core` and show instructions on how to check whether the collection is installed ([https://github.com/ansible-community/antsibull-docs/pull/218](https://github.com/ansible-community/antsibull-docs/pull/218) ). * Insert the antsibull-docs version as a comment or metadata into the generated files ([https://github.com/ansible-community/antsibull-docs/pull/205](https://github.com/ansible-community/antsibull-docs/pull/205) ). * Make sure that the antsibull Sphinx extension contains the correct version (same as antsibull-docs itself) and licensing information (GPL-3.0-or-later), and that the version is kept up-to-date for new releases ([https://github.com/ansible-community/antsibull-docs/pull/202](https://github.com/ansible-community/antsibull-docs/pull/202) ). * Move roles from templates and structural styling from stylesheet to antsibull Sphinx extension. This makes sure that HTML tags such as `` and `` are used for bold and italic texts, and that the same formattings are used for the LaTeX builder ([https://github.com/ansible-community/antsibull-docs/pull/199](https://github.com/ansible-community/antsibull-docs/pull/199) ). * Support multiple filters in `ansible-doc` of ansible-core 2.16 and later. This makes building docsites and linting more efficient when documentation for more than one and less than all installed collections needs to be queried ([https://github.com/ansible-community/antsibull-docs/issues/193](https://github.com/ansible-community/antsibull-docs/issues/193) , [https://github.com/ansible-community/antsibull-docs/pull/213](https://github.com/ansible-community/antsibull-docs/pull/213) ). * The `current` subcommand now has a `--skip-ansible-builtin` option which skips building documentation for `ansible.builtin` ([https://github.com/ansible-community/antsibull-docs/pull/215](https://github.com/ansible-community/antsibull-docs/pull/215) ). * Use same colors for LaTeX builder's output as for HTML builder's output ([https://github.com/ansible-community/antsibull-docs/pull/199](https://github.com/ansible-community/antsibull-docs/pull/199) ). ### Deprecated Features[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#deprecated-features_1 "Permanent link") * The `--use-html-blobs` feature that inserts HTML blobs for the options and return value tables for the `ansible-docsite` output format is deprecated and will be removed soon. The HTML tables cause several features to break, such as references to options and return values. If you think this feature needs to stay, please create an issue in the [antsibull-docs repository](https://github.com/ansible-community/antsibull-docs/issues/) and provide good reasons for it ([https://github.com/ansible-community/antsibull-docs/pull/217](https://github.com/ansible-community/antsibull-docs/pull/217) ). ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#bugfixes_21 "Permanent link") * Document and ensure that the `collection` subcommand with `--use-current` can only be used with collection names ([https://github.com/ansible-community/antsibull-docs/pull/214](https://github.com/ansible-community/antsibull-docs/pull/214) ). * Fix FQCN detection ([https://github.com/ansible-community/antsibull-docs/pull/214](https://github.com/ansible-community/antsibull-docs/pull/214) ). * The `collection` subcommand claimed to support paths to directories, which was never supported. Removed the mention of paths from the help, and added validation ([https://github.com/ansible-community/antsibull-docs/pull/214](https://github.com/ansible-community/antsibull-docs/pull/214) ). * The `plugin` subcommand claimed to support paths to plugin files, which was never supported. Removed the mention of paths from the help ([https://github.com/ansible-community/antsibull-docs/pull/214](https://github.com/ansible-community/antsibull-docs/pull/214) ). * When running `antsibull-docs --help`, the correct program name is now shown for the `--version` option ([https://github.com/ansible-community/antsibull-docs/pull/209](https://github.com/ansible-community/antsibull-docs/pull/209) ). * When running `antsibull-docs --version`, the correct version is now shown also for editable installs and other installs that do not allow `importlib.metadata` to show the correct version ([https://github.com/ansible-community/antsibull-docs/pull/209](https://github.com/ansible-community/antsibull-docs/pull/209) ). * When using the `action_group` or `platform` attributes in a role, a RST symbol was used that was not defined ([https://github.com/ansible-community/antsibull-docs/pull/206](https://github.com/ansible-community/antsibull-docs/pull/206) ). ### Known Issues[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#known-issues "Permanent link") * When using Sphinx builders other than HTML and LaTeX, the indentation for nested options and return values is missing ([https://github.com/ansible-community/antsibull-docs/pull/195](https://github.com/ansible-community/antsibull-docs/pull/195) ). v2.3.1[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v231 "Permanent link") --------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_30 "Permanent link") Bugfix release with a CSS fix for the Sphinx extension. ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#bugfixes_22 "Permanent link") * Fix antsibull Sphinx extension CSS so that the option/return value anchors for module/plugin/role documentation can also be used on WebKit-based browsers such as Gnome Web and Safari ([https://github.com/ansible-community/antsibull-docs/issues/188](https://github.com/ansible-community/antsibull-docs/issues/188) , [https://github.com/ansible-community/antsibull-docs/pull/189](https://github.com/ansible-community/antsibull-docs/pull/189) ). v2.3.0[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v230 "Permanent link") --------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_31 "Permanent link") Bugfix and feature release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#minor-changes_21 "Permanent link") * Add a `:ansplugin:` role to the Sphinx extension. This allows to reference a module, plugin, or role with the `fqcn#type` syntax from semantic markup instead of having to manually compose a `ansible_collections.{fqcn}_{type}` label. An explicit reference title can also be provided with the `title ` syntax similar to the `:ref:` role ([https://github.com/ansible-community/antsibull-docs/pull/180](https://github.com/ansible-community/antsibull-docs/pull/180) ). * Add a new subcommand `lint-core-docs` which lints the ansible-core documentation ([https://github.com/ansible-community/antsibull-docs/pull/182](https://github.com/ansible-community/antsibull-docs/pull/182) ). * Add a new subcommand, `collection-plugins`, for rendering files for all plugins and roles in a collection without any indexes ([https://github.com/ansible-community/antsibull-docs/pull/177](https://github.com/ansible-community/antsibull-docs/pull/177) ). * Add support for different output formats. Next to the default format, `ansible-docsite`, a new **experimental** format `simplified-rst` is supported. Experimental means that it will likely change considerably in the next few releases until it stabilizes. Such changes will not be considered breaking changes, and could potentially even be bugfixes ([https://github.com/ansible-community/antsibull-docs/pull/177](https://github.com/ansible-community/antsibull-docs/pull/177) ). * Use Dart sass compiler instead of sassc to compile CSS for Sphinx extension ([https://github.com/ansible-community/antsibull-docs/issues/185](https://github.com/ansible-community/antsibull-docs/issues/185) , [https://github.com/ansible-community/antsibull-docs/pull/186](https://github.com/ansible-community/antsibull-docs/pull/186) ). * When parsing errors happen in the Sphinx extension, the extension now emits error messages during the build process in addition to error markup ([https://github.com/ansible-community/antsibull-docs/pull/187](https://github.com/ansible-community/antsibull-docs/pull/187) ). ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#bugfixes_23 "Permanent link") * Consider module/plugin aliases when linting references to other modules and plugins ([https://github.com/ansible-community/antsibull-docs/pull/184](https://github.com/ansible-community/antsibull-docs/pull/184) ). * Make sure that all aliases are actually listed for plugins ([https://github.com/ansible-community/antsibull-docs/pull/183](https://github.com/ansible-community/antsibull-docs/pull/183) ). * When looking for redirects, the `aliases` field and filesystem redirects in ansible-core were not properly considered. This ensures that all redirect stubs are created, and that no duplicates show up, not depending on whether ansible-core is installed in editable mode or not ([https://github.com/ansible-community/antsibull-docs/pull/183](https://github.com/ansible-community/antsibull-docs/pull/183) ). v2.2.0[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v220 "Permanent link") --------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_32 "Permanent link") Bugfix and feature release improving rendering and linting. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#minor-changes_22 "Permanent link") * Collection docs linter - also validate `seealso` module and plugin destinations ([https://github.com/ansible-community/antsibull-docs/issues/168](https://github.com/ansible-community/antsibull-docs/issues/168) , [https://github.com/ansible-community/antsibull-docs/pull/171](https://github.com/ansible-community/antsibull-docs/pull/171) ). * When linting collection plugin docs, make sure that array stubs `[...]` are used when referencing sub-options or sub-return values inside lists, and are not used outside lists and dictionaries ([https://github.com/ansible-community/antsibull-docs/pull/173](https://github.com/ansible-community/antsibull-docs/pull/173) ). ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#bugfixes_24 "Permanent link") * Fix the way the Sphinx extension creates nodes for options and return values so they look identical for internal references, external (intersphinx) references, and unresolved references ([https://github.com/ansible-community/antsibull-docs/pull/175](https://github.com/ansible-community/antsibull-docs/pull/175) ). * Make sure that `:ansopt:` and `:ansretval:` create the same references as the labels created in the RST files ([https://github.com/ansible-community/antsibull-docs/issues/167](https://github.com/ansible-community/antsibull-docs/issues/167) , [https://github.com/ansible-community/antsibull-docs/pull/172](https://github.com/ansible-community/antsibull-docs/pull/172) ). * Make sure that broken `:ansopt:` and `:ansretval:` parameters result in correctly rendered error messages ([https://github.com/ansible-community/antsibull-docs/pull/175](https://github.com/ansible-community/antsibull-docs/pull/175) ). * When trying to copying descriptions of non-existing plugins to `seealso`, references to these non-existing plugins were added in some cases, crashing the docs augmentation process ([https://github.com/ansible-community/antsibull-docs/pull/169](https://github.com/ansible-community/antsibull-docs/pull/169) ). v2.1.0[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v210 "Permanent link") --------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_33 "Permanent link") Feature and bugfix release with many improvements related to semantic markup and validation. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#minor-changes_23 "Permanent link") * Add option `--disallow-unknown-collection-refs` to disallow references to other collections than the one covered by `--validate-collection-refs` ([https://github.com/ansible-community/antsibull-docs/pull/157](https://github.com/ansible-community/antsibull-docs/pull/157) ). * Add option `--validate-collection-refs` to the `lint-collection-docs` subcommand to also control which references to plugin/module/role names in (other) collections and their options and return values should be validated ([https://github.com/ansible-community/antsibull-docs/pull/157](https://github.com/ansible-community/antsibull-docs/pull/157) ). * Add the new collection config field `envvar_directives` which allows to declare which environment variables are declared with an `.. envvar::` directive in the collection's extra docsite documentation. This is used, next to the plugin configuration information and the ansible-core configuration information, to determine whether an environment variable is referencable or not ([https://github.com/ansible-community/antsibull-docs/pull/166](https://github.com/ansible-community/antsibull-docs/pull/166) ). * Add the roles `:ansenvvar:` and `:ansenvvarref:` to the antsibull-docs Sphinx extension ([https://github.com/ansible-community/antsibull-docs/pull/166](https://github.com/ansible-community/antsibull-docs/pull/166) ). * Render `E(...)` markup with `:ansenvvarref:` or `:ansenvvar:` depending on whether the environment variable is known to be referencable or not ([https://github.com/ansible-community/antsibull-docs/pull/166](https://github.com/ansible-community/antsibull-docs/pull/166) ). * When linting markup in collection docs, validate plugin/module/role names, and also option/return value names for other plugins/modules/roles in the same collection, (transitively) dependent collections, and ansible.builtin ([https://github.com/ansible-community/antsibull-docs/pull/157](https://github.com/ansible-community/antsibull-docs/pull/157) ). * When linting semantic markup in collection docs, also accept aliases when checking `O()` values ([https://github.com/ansible-community/antsibull-docs/pull/155](https://github.com/ansible-community/antsibull-docs/pull/155) ). * When refering to markup in multi-paragraph texts, like `description`, now includes the paragraph number in error messages ([https://github.com/ansible-community/antsibull-docs/pull/163](https://github.com/ansible-community/antsibull-docs/pull/163) ). ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#bugfixes_25 "Permanent link") * Allow role entrypoint deprecations without having to specify the collection the role is removed from ([https://github.com/ansible-community/antsibull-docs/pull/156](https://github.com/ansible-community/antsibull-docs/pull/156) ). * Indent module/plugin and role entrypoint deprecations correctly if 'Why' or 'Alternative' texts need more than one line ([https://github.com/ansible-community/antsibull-docs/pull/156](https://github.com/ansible-community/antsibull-docs/pull/156) ). * When collecting collection dependencies for the `lint-collection-docs` subcommand, a bug prevented the duplicate detection to work ([https://github.com/ansible-community/antsibull-docs/pull/160](https://github.com/ansible-community/antsibull-docs/pull/160) ). v2.0.0[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v200 "Permanent link") --------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_34 "Permanent link") Major new release that drops support for older Python and Ansible/ansible-base/ansible-core versions. ### Major Changes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#major-changes "Permanent link") * Change pyproject build backend from `poetry-core` to `hatchling`. `pip install antsibull-docs` works exactly the same as before, but some users may be affected depending on how they build/install the project ([https://github.com/ansible-community/antsibull-docs/pull/115](https://github.com/ansible-community/antsibull-docs/pull/115) ). ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#minor-changes_24 "Permanent link") * Allow to use the currently installed ansible-core version for the `devel` and `stable` subcommands ([https://github.com/ansible-community/antsibull-docs/pull/121](https://github.com/ansible-community/antsibull-docs/pull/121) ). * Ansibull-docs now no longer depends directly on `sh` ([https://github.com/ansible-community/antsibull-docs/pull/122](https://github.com/ansible-community/antsibull-docs/pull/122) ). * Bump version range of antsibull-docs requirement written by `sphinx-init` subcommand to `>= 2.0.0, < 3.0.0`. Previously, this was set to `>=2.0.0a2, <3.0.0` ([https://github.com/ansible-community/antsibull-docs/pull/151](https://github.com/ansible-community/antsibull-docs/pull/151) ). * Now depends antsibull-core 2.0.0 or newer; antsibull-core 1.x.y is no longer supported ([https://github.com/ansible-community/antsibull-docs/pull/122](https://github.com/ansible-community/antsibull-docs/pull/122) ). * Remove residual compatability code for Python 3.6 and 3.7 ([https://github.com/ansible-community/antsibull-docs/pulls/70](https://github.com/ansible-community/antsibull-docs/pulls/70) ). * Support a per-collection docs config file `docs/docsite/config.yml`. It is also linted by the `lint-collection-docs` subcommand ([https://github.com/ansible-community/antsibull-docs/pull/134](https://github.com/ansible-community/antsibull-docs/pull/134) ). * The antsibull-docs requirement in the `requirements.txt` file created by the sphinx-init subcommand now has version range `>= 2.0.0, < 3.0.0` ([https://github.com/ansible-community/antsibull-docs/pull/126](https://github.com/ansible-community/antsibull-docs/pull/126) ). * The dependency [antsibull-docs-parser](https://github.com/ansible-community/antsibull-docs-parser) has been added and is used for processing Ansible markup ([https://github.com/ansible-community/antsibull-docs/pull/124](https://github.com/ansible-community/antsibull-docs/pull/124) ). ### Breaking Changes / Porting Guide[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#breaking-changes-porting-guide "Permanent link") * Disable flatmapping for all collections except community.general < 6.0.0 and community.network < 5.0.0. You can enable flatmapping for your collection by setting `flatmap: true` in `docs/docsite/config.yml` ([https://github.com/ansible-community/antsibull-docs/pull/134](https://github.com/ansible-community/antsibull-docs/pull/134) ). * Drop support for Python 3.6, 3.7, and 3.8 ([https://github.com/ansible-community/antsibull-docs/pull/115](https://github.com/ansible-community/antsibull-docs/pull/115) )." * No longer removes `PYTHONPATH` from the environment when calling `ansible`, `ansible-galaxy`, or `ansible-doc` outside a self-created venv ([https://github.com/ansible-community/antsibull-docs/pull/121](https://github.com/ansible-community/antsibull-docs/pull/121) ). * No longer supports Ansible 2.9, ansible-base 2.10, and ansible-core 2.11 and 2.12. The minimum required ansible-core version is 2.13. This allows for simpler and more efficient docs parsing and information retrieval ([https://github.com/ansible-community/antsibull-docs/pull/120](https://github.com/ansible-community/antsibull-docs/pull/120) ). * The `ansible-doc` and `ansible-internal` values for `doc_parsing_backend` in the configuration file have been removed. Change the value to `auto` for best compatibility ([https://github.com/ansible-community/antsibull-docs/pull/120](https://github.com/ansible-community/antsibull-docs/pull/120) ). ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#bugfixes_26 "Permanent link") * Bump version range of antsibull-docs requirement written by `sphinx-init` subcommand to `>= 2.0.0a2, < 3.0.0`. Previously, this was set to `>=2.0.0, <3.0.0` which could not be satisfied ([https://github.com/ansible-community/antsibull-docs/pull/149](https://github.com/ansible-community/antsibull-docs/pull/149) ). * Use `doc_parsing_backend` from the application context instead of the library context. This prevents removal of `doc_parsing_backend` from the antsibull-core library context ([https://github.com/ansible-community/antsibull-docs/pull/125](https://github.com/ansible-community/antsibull-docs/pull/125) ). v1.11.0[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v1110 "Permanent link") ----------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_35 "Permanent link") Feature release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#minor-changes_25 "Permanent link") * Add support for semantic markup in roles ([https://github.com/ansible-community/antsibull-docs/pull/113](https://github.com/ansible-community/antsibull-docs/pull/113) ). * Internal refactoring of markup code ([https://github.com/ansible-community/antsibull-docs/pull/108](https://github.com/ansible-community/antsibull-docs/pull/108) ). * The `lint-collection-docs` subcommand can be told not to run rstcheck when `--plugin-docs` is used by passing `--skip-rstcheck`. This speeds up testing for large collections ([https://github.com/ansible-community/antsibull-docs/pull/112](https://github.com/ansible-community/antsibull-docs/pull/112) ). * The `lint-collection-docs` subcommand will now also validate Ansible markup when `--plugin-docs` is passed. It can also ensure that no semantic markup is used with the new `--disallow-semantic-markup` option. This can for example be used by collections to avoid semantic markup being backported to older stable branches ([https://github.com/ansible-community/antsibull-docs/pull/112](https://github.com/ansible-community/antsibull-docs/pull/112) ). v1.10.0[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v1100 "Permanent link") ----------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_36 "Permanent link") Bugfix and feature release. ### Major Changes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#major-changes_1 "Permanent link") * Support new semantic markup in documentation ([https://github.com/ansible-community/antsibull-docs/pull/4](https://github.com/ansible-community/antsibull-docs/pull/4) ). ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#minor-changes_26 "Permanent link") * Add a note about the ordering of positional and named parameter to the plugin page. Also mention positional and keyword parameters for lookups ([https://github.com/ansible-community/antsibull-docs/pull/101](https://github.com/ansible-community/antsibull-docs/pull/101) ). * Update schema for roles argument spec to allow specifying attributes on the entrypoint level. These are now also rendered when present ([https://github.com/ansible-community/antsibull-docs/pull/103](https://github.com/ansible-community/antsibull-docs/pull/103) ). ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#bugfixes_27 "Permanent link") * Explicitly declare the `sh` dependency and limit it to before 2.0.0. Also explicitly declare the dependencies on `pydantic`, `semantic_version`, `aiohttp`, `twiggy`, and `PyYAML` ([https://github.com/ansible-community/antsibull-docs/pull/99](https://github.com/ansible-community/antsibull-docs/pull/99) ). * Restrict the `pydantic` dependency to major version 1 ([https://github.com/ansible-community/antsibull-docs/pull/102](https://github.com/ansible-community/antsibull-docs/pull/102) ). v1.9.0[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v190 "Permanent link") --------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_37 "Permanent link") Feature release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#minor-changes_27 "Permanent link") * Improve build script generated by `antsibull-docs sphinx-init` to change to the directory where the script is located, instead of hardcoding the script's path. This also fixed the existing bug that the path was not quoted ([https://github.com/ansible-community/antsibull-docs/issues/91](https://github.com/ansible-community/antsibull-docs/issues/91) , [https://github.com/ansible-community/antsibull-docs/pull/92](https://github.com/ansible-community/antsibull-docs/pull/92) ). * Show callback plugin type on callback plugin pages. Also write callback indexes by callback plugin type ([https://github.com/ansible-community/antsibull-docs/issues/89](https://github.com/ansible-community/antsibull-docs/issues/89) , [https://github.com/ansible-community/antsibull-docs/pull/90](https://github.com/ansible-community/antsibull-docs/pull/90) ). v1.8.2[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v182 "Permanent link") --------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_38 "Permanent link") Bugfix release. ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#bugfixes_28 "Permanent link") * Fix the new options `--extra-html-context` and `--extra-html-theme-options` of the `sphinx-init` subcommand ([https://github.com/ansible-community/antsibull-docs/pull/86](https://github.com/ansible-community/antsibull-docs/pull/86) ). v1.8.1[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v181 "Permanent link") --------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_39 "Permanent link") Bugfix release. ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#bugfixes_29 "Permanent link") * When creating toctrees for breadcrumbs, place subtree for a plugin type in the plugin type's section ([https://github.com/ansible-community/antsibull-docs/pull/83](https://github.com/ansible-community/antsibull-docs/pull/83) ). v1.8.0[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v180 "Permanent link") --------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_40 "Permanent link") Feature and bugfix release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#minor-changes_28 "Permanent link") * Add new options `--project`, `--copyright`, `--title`, `--html-short-title`, `--extra-conf`, `--extra-html-context`, and `--extra-html-theme-options` to the `sphinx-init` subcommand to allow to customize the generated `conf.py` Sphinx configuration ([https://github.com/ansible-community/antsibull-docs/pull/77](https://github.com/ansible-community/antsibull-docs/pull/77) ). * Automatically use a module's or plugin's short description as the "See also" description if no description is provided ([https://github.com/ansible-community/antsibull-docs/issues/64](https://github.com/ansible-community/antsibull-docs/issues/64) , [https://github.com/ansible-community/antsibull-docs/pull/74](https://github.com/ansible-community/antsibull-docs/pull/74) ). * It is now possible to provide a path to an existing file to be used as `rst/index.rst` for `antsibull-docs sphinx-init` ([https://github.com/ansible-community/antsibull-docs/pull/68](https://github.com/ansible-community/antsibull-docs/pull/68) ). * Make compatible with antsibull-core 2.x.y ([https://github.com/ansible-community/antsibull-docs/pull/78](https://github.com/ansible-community/antsibull-docs/pull/78) ). * Remove support for `forced_action_plugin`, a module attribute that was removed during the development phase of attributes ([https://github.com/ansible-community/antsibull-docs/pull/63](https://github.com/ansible-community/antsibull-docs/pull/63) ). * Stop mentioning the version features were added for Ansible if the Ansible version is before 2.7 ([https://github.com/ansible-community/antsibull-docs/pull/76](https://github.com/ansible-community/antsibull-docs/pull/76) ). * The default `index.rst` created by `antsibull-docs sphinx-init` includes the new environment variable index ([https://github.com/ansible-community/antsibull-docs/pull/80](https://github.com/ansible-community/antsibull-docs/pull/80) ). * Use correct markup (`envvar` role) for environment variables. Compile an index of all environment variables used by plugins ([https://github.com/ansible-community/antsibull-docs/pull/73](https://github.com/ansible-community/antsibull-docs/pull/73) ). ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#bugfixes_30 "Permanent link") * Make sure that `build.sh` created by the `sphinx-init` subcommand sets proper permissions for antsibull-docs on the `temp-rst` directory it creates ([https://github.com/ansible-community/antsibull-docs/pull/79](https://github.com/ansible-community/antsibull-docs/pull/79) ). v1.7.4[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v174 "Permanent link") --------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_41 "Permanent link") Bugfix release. ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#bugfixes_31 "Permanent link") * Removed `sphinx` restriction in `requirements.txt` file created by `antsibull-docs sphinx-init` since the bug in `sphinx-rtd-theme` has been fixed ([https://github.com/ansible-community/antsibull-docs/pull/69](https://github.com/ansible-community/antsibull-docs/pull/69) ). * The license header for the template for the `rst/index.rst` file created by `antsibull-docs sphinx-init` was commented incorrectly and thus showed up in the templated file ([https://github.com/ansible-community/antsibull-docs/pull/67](https://github.com/ansible-community/antsibull-docs/pull/67) ). * When using `--squash-hierarchy`, do not mention the list of collections on the collection's index page ([https://github.com/ansible-community/antsibull-docs/pull/72](https://github.com/ansible-community/antsibull-docs/pull/72) ). v1.7.3[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v173 "Permanent link") --------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_42 "Permanent link") Bugfix release. ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#bugfixes_32 "Permanent link") * Fix rendering of the `action_group` attribute ([https://github.com/ansible-community/antsibull-docs/pull/62](https://github.com/ansible-community/antsibull-docs/pull/62) ). v1.7.2[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v172 "Permanent link") --------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_43 "Permanent link") Bugfix release. ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#bugfixes_33 "Permanent link") * Fix `version_added` processing for ansible.builtin 0.x to represent this as `Ansible 0.x` instead of `ansible-core 0.x` ([https://github.com/ansible-community/antsibull-docs/pull/61](https://github.com/ansible-community/antsibull-docs/pull/61) ). v1.7.1[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v171 "Permanent link") --------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_44 "Permanent link") Bugfix release. ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#bugfixes_34 "Permanent link") * Prevent crash during `stable` docsite build when `_python` entry is present in deps file ([https://github.com/ansible-community/antsibull-docs/pull/57](https://github.com/ansible-community/antsibull-docs/pull/57) ). v1.7.0[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v170 "Permanent link") --------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_45 "Permanent link") Bugfix and feature release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#minor-changes_29 "Permanent link") * Add `--intersphinx` option to the `sphinx-init` subcommand to allow adding additional `intersphinx_mapping` entries to `conf.py` ([https://github.com/ansible-community/antsibull-docs/issues/35](https://github.com/ansible-community/antsibull-docs/issues/35) , [https://github.com/ansible-community/antsibull-docs/pull/44](https://github.com/ansible-community/antsibull-docs/pull/44) ). * Allow the `toctree` entries for in a collection's `docs/docsite/extra-docs.yml` to be a dictionary with `ref` and `title` keys instead of just a reference as a string ([https://github.com/ansible-community/antsibull-docs/pull/45](https://github.com/ansible-community/antsibull-docs/pull/45) ). * Antsibull-docs now depends on [packaging](https://pypi.org/project/packaging/) ([https://github.com/ansible-community/antsibull-docs/pull/49](https://github.com/ansible-community/antsibull-docs/pull/49) ). * The collection index pages now contain the supported versions of ansible-core of the collection in case collection's `meta/runtime.yml` specifies `requires_ansible` ([https://github.com/ansible-community/antsibull-docs/issues/48](https://github.com/ansible-community/antsibull-docs/issues/48) , [https://github.com/ansible-community/antsibull-docs/pull/49](https://github.com/ansible-community/antsibull-docs/pull/49) ). * The output of the `lint-collection-docs` command has been improved; in particular multi-line messages are now indented ([https://github.com/ansible-community/antsibull-docs/pull/52](https://github.com/ansible-community/antsibull-docs/pull/52) ). * Use `ansible --version` to figure out ansible-core version when ansible-core is not installed for the same Python interpreter / venv that is used for antsibull-docs ([https://github.com/ansible-community/antsibull-docs/pull/50](https://github.com/ansible-community/antsibull-docs/pull/50) ). * Use code formatting for all values, such as choice entries, defaults, and samples ([https://github.com/ansible-community/antsibull-docs/issues/38](https://github.com/ansible-community/antsibull-docs/issues/38) , [https://github.com/ansible-community/antsibull-docs/pull/42](https://github.com/ansible-community/antsibull-docs/pull/42) ). ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#bugfixes_35 "Permanent link") * Avoid long aliases list to make left column too wide ([https://github.com/ansible-collections/amazon.aws/issues/1101](https://github.com/ansible-collections/amazon.aws/issues/1101) , [https://github.com/ansible-community/antsibull-docs/pull/54](https://github.com/ansible-community/antsibull-docs/pull/54) ). * Make `lint-collection-docs --plugin-docs` subcommand actually work ([https://github.com/ansible-community/antsibull-docs/pull/47](https://github.com/ansible-community/antsibull-docs/pull/47) ). v1.6.1[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v161 "Permanent link") --------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_46 "Permanent link") Bugfix release for ansible-core 2.14. ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#bugfixes_36 "Permanent link") * Fix formulation of top-level `version_added` ([https://github.com/ansible-community/antsibull-docs/pull/43](https://github.com/ansible-community/antsibull-docs/pull/43) ). v1.6.0[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v160 "Permanent link") --------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_47 "Permanent link") Bugfix and feature release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#minor-changes_30 "Permanent link") * Allow to specify choices as dictionary instead of list ([https://github.com/ansible-community/antsibull-docs/pull/36](https://github.com/ansible-community/antsibull-docs/pull/36) ). * Use JSON serializer to format choices ([https://github.com/ansible-community/antsibull-docs/pull/37](https://github.com/ansible-community/antsibull-docs/pull/37) ). * Use special serializer to format INI values in examples ([https://github.com/ansible-community/antsibull-docs/pull/37](https://github.com/ansible-community/antsibull-docs/pull/37) ). ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#bugfixes_37 "Permanent link") * Avoid collection names with `_` in them appear wrongly escaped in the HTML output ([https://github.com/ansible-community/antsibull-docs/pull/41](https://github.com/ansible-community/antsibull-docs/pull/41) ). * For INI examples which have no default, write `VALUE` as intended instead of `None` ([https://github.com/ansible-community/antsibull-docs/pull/37](https://github.com/ansible-community/antsibull-docs/pull/37) ). * Format lists correctly for INI examples ([https://github.com/ansible-community/antsibull-docs/pull/37](https://github.com/ansible-community/antsibull-docs/pull/37) ). * The `sphinx-init` subcommand's `requirement.txt` file avoids Sphinx 5.2.0.post0, which triggers a bug in sphinx-rtd-theme which happens to be the parent theme of the default theme sphinx\_ansible\_theme used by `sphinx-init` ([https://github.com/ansible-community/antsibull-docs/issues/39](https://github.com/ansible-community/antsibull-docs/issues/39) , [https://github.com/ansible-community/antsibull-docs/pull/40](https://github.com/ansible-community/antsibull-docs/pull/40) ). v1.5.0[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v150 "Permanent link") --------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_48 "Permanent link") Feature and bugfix release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#minor-changes_31 "Permanent link") * Detect filter and test plugin aliases and avoid them being emitted multiple times. Instead insert redirects so that stub pages will be created ([https://github.com/ansible-community/antsibull-docs/pull/33](https://github.com/ansible-community/antsibull-docs/pull/33) ). * Replace `ansible.builtin` with `ansible-core`, `ansible-base`, or `Ansible` in version added collection names. Also write ` ` instead of ` of ` ([https://github.com/ansible-community/antsibull-docs/pull/34](https://github.com/ansible-community/antsibull-docs/pull/34) ). ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#bugfixes_38 "Permanent link") * Fix escaping of collection names in version added statements, and fix collection names for roles options ([https://github.com/ansible-community/antsibull-docs/pull/34](https://github.com/ansible-community/antsibull-docs/pull/34) ). v1.4.0[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v140 "Permanent link") --------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_49 "Permanent link") Feature and bugfix release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#minor-changes_32 "Permanent link") * The `sphinx-init` subcommand now also creates an `antsibull-docs.cfg` file and moves configuration settings from CLI flags in `build.sh` to this configuration file ([https://github.com/ansible-community/antsibull-docs/pull/26](https://github.com/ansible-community/antsibull-docs/pull/26) ). * There are two new options for explicitly specified configuration files named `collection_url` and `collection_install`. These allow to override the URLs pointing to collections (default link to galaxy.ansible.com), and the commands to install collections (use `ansible-galaxy collection install` by default). This can be useful when documenting (internal) collections that are not available on Ansible Galaxy. The default `antsibull-docs.cfg` generated by the `sphinx-init` subcommand shows how this can be configured ([https://github.com/ansible-community/antsibull-docs/issues/15](https://github.com/ansible-community/antsibull-docs/issues/15) , [https://github.com/ansible-community/antsibull-docs/pull/26](https://github.com/ansible-community/antsibull-docs/pull/26) ). * When generating plugin error pages, or showing non-fatal errors in plugins or roles, link to the collection's issue tracker instead of the collection's URL if available ([https://github.com/ansible-community/antsibull-docs/pull/29](https://github.com/ansible-community/antsibull-docs/pull/29) ). ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#bugfixes_39 "Permanent link") * Make handling of bad documentation more robust when certain values are `None` while the keys are present ([https://github.com/ansible-community/antsibull-docs/pull/32](https://github.com/ansible-community/antsibull-docs/pull/32) ). v1.3.0[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v130 "Permanent link") --------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_50 "Permanent link") Feature and bugfix release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#minor-changes_33 "Permanent link") * Ensure that values for `default`, `choices`, and `sample` use the types specified for the option / return value ([https://github.com/ansible-community/antsibull-docs/pull/19](https://github.com/ansible-community/antsibull-docs/pull/19) ). * If a plugin or module has requirements listed, add a disclaimer next to the installation line at the top that further requirements are needed ([https://github.com/ansible-community/antsibull-docs/issues/23](https://github.com/ansible-community/antsibull-docs/issues/23) , [https://github.com/ansible-community/antsibull-docs/pull/24](https://github.com/ansible-community/antsibull-docs/pull/24) ). * Show the 'you might already have this collection installed if you are using the `ansible` package' disclaimer for plugins only for official docsite builds (subcommands `devel` and `stable`). Also include this disclaimer for roles on official docsite builds ([https://github.com/ansible-community/antsibull-docs/pull/25](https://github.com/ansible-community/antsibull-docs/pull/25) ). * Use `true` and `false` for booleans instead of `yes` and `no` ([https://github.com/ansible-community/community-topics/issues/116](https://github.com/ansible-community/community-topics/issues/116) , [https://github.com/ansible-community/antsibull-docs/pull/19](https://github.com/ansible-community/antsibull-docs/pull/19) ). * When processing formatting directives, make sure to properly escape all other text for RST respectively HTML instead of including it verbatim ([https://github.com/ansible-community/antsibull-docs/issues/21](https://github.com/ansible-community/antsibull-docs/issues/21) , [https://github.com/ansible-community/antsibull-docs/pull/22](https://github.com/ansible-community/antsibull-docs/pull/22) ). ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#bugfixes_40 "Permanent link") * Improve indentation of HTML blocks for tables to avoid edge cases which generate invalid RST ([https://github.com/ansible-community/antsibull-docs/pull/22](https://github.com/ansible-community/antsibull-docs/pull/22) ). v1.2.2[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v122 "Permanent link") --------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_51 "Permanent link") Bugfix release. ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#bugfixes_41 "Permanent link") * Fix rstcheck-core support ([https://github.com/ansible-community/antsibull-docs/pull/20](https://github.com/ansible-community/antsibull-docs/pull/20) ). v1.2.1[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v121 "Permanent link") --------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_52 "Permanent link") Bugfix release. ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#bugfixes_42 "Permanent link") * Do not escape `<`, `>`, `&`, and `'` in JSONified defaults and examples as the [Jinja2 tojson filter](https://jinja.palletsprojects.com/en/2.11.x/templates/#tojson) does. Also improve formatting by making sure `,` is followed by a space ([https://github.com/ansible-community/antsibull-docs/pull/18](https://github.com/ansible-community/antsibull-docs/pull/18) ). * The collection filter was ignored when parsing the `ansible-galaxy collection list` output for the docs build ([https://github.com/ansible-community/antsibull-docs/issues/16](https://github.com/ansible-community/antsibull-docs/issues/16) , [https://github.com/ansible-community/antsibull-docs/pull/17](https://github.com/ansible-community/antsibull-docs/pull/17) ). v1.2.0[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v120 "Permanent link") --------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_53 "Permanent link") Feature and bugfix release. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#minor-changes_34 "Permanent link") * Support plugin `seealso` from the [semantic markup specification](https://hackmd.io/VjN60QSoRSSeRfvGmOH1lQ?both) ([https://github.com/ansible-community/antsibull-docs/pull/8](https://github.com/ansible-community/antsibull-docs/pull/8) ). * The `lint-collection-docs` subcommand has a new boolean flag `--plugin-docs` which renders the plugin docs to RST and validates them with rstcheck. This can be used as a lighter version of rendering the docsite in CI ([https://github.com/ansible-community/antsibull-docs/pull/12](https://github.com/ansible-community/antsibull-docs/pull/12) ). * The files in the source repository now follow the [REUSE Specification](https://reuse.software/spec/) . The only exceptions are changelog fragments in `changelogs/fragments/` ([https://github.com/ansible-community/antsibull-docs/pull/14](https://github.com/ansible-community/antsibull-docs/pull/14) ). ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#bugfixes_43 "Permanent link") * Make sure that `_input` does not show up twice for test or filter arguments when the plugin mentions it in `positional` ([https://github.com/ansible-community/antsibull-docs/pull/10](https://github.com/ansible-community/antsibull-docs/pull/10) ). * Mark rstcheck 4.x and 5.x as compatible. Support rstcheck 6.x as well ([https://github.com/ansible-community/antsibull-docs/pull/13](https://github.com/ansible-community/antsibull-docs/pull/13) ). v1.1.0[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v110 "Permanent link") --------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_54 "Permanent link") Feature release with support for ansible-core 2.14's sidecar docs feature. ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#minor-changes_35 "Permanent link") * If lookup plugins have a single return value starting with `_`, that return value is now labelled `Return value` ([https://github.com/ansible-community/antsibull-docs/pull/6](https://github.com/ansible-community/antsibull-docs/pull/6) ). * If lookup plugins have an option called `_terms`, it is now shown in its own section `Terms`, and not in the regular `Parameters` section ([https://github.com/ansible-community/antsibull-docs/pull/6](https://github.com/ansible-community/antsibull-docs/pull/6) ). * More robust handling of parsing errors when ansible-doc was unable to extract documentation ([https://github.com/ansible-community/antsibull-docs/pull/6](https://github.com/ansible-community/antsibull-docs/pull/6) ). * Support parameter type `any`, and show `raw` as `any` ([https://github.com/ansible-community/antsibull-docs/pull/6](https://github.com/ansible-community/antsibull-docs/pull/6) ). * Support test and filter plugins when ansible-core 2.14+ is used. This works with the current `devel` branch of ansible-core ([https://github.com/ansible-community/antsibull-docs/pull/6](https://github.com/ansible-community/antsibull-docs/pull/6) ). v1.0.1[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v101 "Permanent link") --------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_55 "Permanent link") Bugfix release. ### Bugfixes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#bugfixes_44 "Permanent link") * Make sure that aliases of module/plugin options and return values that result in identical RST labels under docutil's normalization are only emitted once ([https://github.com/ansible-community/antsibull-docs/pull/7](https://github.com/ansible-community/antsibull-docs/pull/7) ). * Properly escape module/plugin option and return value slugs in generated HTML ([https://github.com/ansible-community/antsibull-docs/pull/7](https://github.com/ansible-community/antsibull-docs/pull/7) ). v1.0.0[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v100 "Permanent link") --------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_56 "Permanent link") First stable release. ### Major Changes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#major-changes_2 "Permanent link") * From version 1.0.0 on, antsibull-docs is sticking to semantic versioning and aims at providing no backwards compatibility breaking changes **to the command line API (antsibull-docs)** during a major release cycle. We explicitly exclude code compatibility. **antsibull-docs is not supposed to be used as a library,** and when used as a library it might not conform to semantic versioning ([https://github.com/ansible-community/antsibull-docs/pull/2](https://github.com/ansible-community/antsibull-docs/pull/2) ). ### Minor Changes[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#minor-changes_36 "Permanent link") * Only mention 'These are the collections with docs hosted on docs.ansible.com' for `stable` and `devel` subcommands ([https://github.com/ansible-community/antsibull-docs/pull/3](https://github.com/ansible-community/antsibull-docs/pull/3) ). * Stop using some API from antsibull-core that is being removed ([https://github.com/ansible-community/antsibull-docs/pull/1](https://github.com/ansible-community/antsibull-docs/pull/1) ). v0.1.0[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#v010 "Permanent link") --------------------------------------------------------------------------------------------- ### Release Summary[¶](https://docs.ansible.com/projects/antsibull-docs/changelog/#release-summary_57 "Permanent link") Initial release. The `antsibull-docs` tool is compatible to the one from antsibull 0.43.0. --- # Working with dynamic inventory — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * [Building Ansible inventories](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/index.html) * Working with dynamic inventory * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/inventory_guide/intro_dynamic_inventory.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Working with dynamic inventory[](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_dynamic_inventory.html#working-with-dynamic-inventory "Link to this heading") =========================================================================================================================================================================================== If your Ansible inventory fluctuates over time, with hosts spinning up and shutting down in response to business demands, the static inventory solutions described in [How to build your inventory](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#inventory) will not serve your needs. You may need to track hosts from multiple sources: cloud providers, LDAP, [Cobbler](https://cobbler.github.io/) , and/or enterprise CMDB systems. Ansible integrates all of these options through a dynamic external inventory system. Ansible supports two ways to connect with external inventory: [Inventory plugins](https://docs.ansible.com/projects/ansible-core/devel/plugins/inventory.html#inventory-plugins) and inventory scripts. Inventory plugins take advantage of the most recent updates to the Ansible Core code. We recommend plugins over scripts for dynamic inventory. You can [write your own plugin](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_inventory.html#developing-inventory) to connect to additional dynamic inventory sources. You can still use inventory scripts if you choose. When we implemented inventory plugins, we ensured backwards compatibility through the script inventory plugin. The examples below illustrate how to use inventory scripts. If you prefer a GUI for handling dynamic inventory, the inventory database on AWX or [Red Hat Ansible Automation Platform](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/tower.html#ansible-platform) syncs with all your dynamic inventory sources, provides web and REST access to the results, and offers a graphical inventory editor. With a database record of all of your hosts, you can correlate past event history and see which hosts have had failures on their last playbook runs. [Inventory script example: Cobbler](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_dynamic_inventory.html#id3) [](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_dynamic_inventory.html#inventory-script-example-cobbler "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Ansible integrates seamlessly with [Cobbler](https://cobbler.github.io/) , a Linux installation server originally written by Michael DeHaan and now led by James Cammarata, who works for Ansible. While primarily used to kickoff OS installations and manage DHCP and DNS, Cobbler has a generic layer that can represent data for multiple configuration management systems (even at the same time) and serve as a ‘lightweight CMDB’. To tie your Ansible inventory to Cobbler, copy [this script](https://raw.githubusercontent.com/ansible-community/contrib-scripts/main/inventory/cobbler.py) to `/etc/ansible` and `chmod +x` the file. Run `cobblerd` any time you use Ansible and use the `-i` command line option (for example, `-i /etc/ansible/cobbler.py`) to communicate with Cobbler using Cobbler’s XMLRPC API. Add a `cobbler.ini` file in `/etc/ansible` so Ansible knows where the Cobbler server is and some cache improvements can be used. For example: \[cobbler\] # Set Cobbler's hostname or IP address host = http://127.0.0.1/cobbler\_api # API calls to Cobbler can be slow. For this reason, we cache the results of an API # call. Set this to the path you want cache files to be written to. Two files # will be written to this directory: # - ansible-cobbler.cache # - ansible-cobbler.index cache\_path = /tmp # The number of seconds a cache file is considered valid. After this many # seconds, a new API call will be made, and the cache file will be updated. cache\_max\_age = 900 First test the script by running `/etc/ansible/cobbler.py` directly. You should see some JSON data output, but it may not have anything in it just yet. Let’s explore what this does. In Cobbler, assume a scenario somewhat like the following: cobbler profile add \--name\=webserver \--distro\=CentOS6-x86\_64 cobbler profile edit \--name\=webserver \--mgmt-classes\="webserver" \--ksmeta\="a=2 b=3" cobbler system edit \--name\=foo \--dns-name\="foo.example.com" \--mgmt-classes\="atlanta" \--ksmeta\="c=4" cobbler system edit \--name\=bar \--dns-name\="bar.example.com" \--mgmt-classes\="atlanta" \--ksmeta\="c=5" In the example above, the system ‘foo.example.com’ is addressable by ansible directly, but is also addressable when using the group names ‘webserver’ or ‘atlanta’. Since Ansible uses SSH, it contacts system foo over ‘foo.example.com’, only, never just ‘foo’. Similarly, if you tried “ansible foo”, it would not find the system… but “ansible ‘foo\*’” would do, because the system DNS name starts with ‘foo’. The script provides more than host and group info. In addition, as a bonus, when the ‘setup’ module is run (which happens automatically when using playbooks), the variables ‘a’, ‘b’, and ‘c’ will all be auto-populated in the templates: \# file: /srv/motd.j2 Welcome, I am templated with a value of a={{ a }}, b={{ b }}, and c={{ c }} Which could be executed just like this: ansible webserver \-m setup ansible webserver \-m template \-a "src=/tmp/motd.j2 dest=/etc/motd" Note The name ‘webserver’ came from Cobbler, as did the variables for the config file. You can still pass in your own variables like normal in Ansible, but variables from the external inventory script will override any that have the same name. So, with the template above (`motd.j2`), this results in the following data being written to `/etc/motd` for system ‘foo’: Welcome, I am templated with a value of a=2, b=3, and c=4 And on system ‘bar’ (bar.example.com): Welcome, I am templated with a value of a=2, b=3, and c=5 And technically, though there is no major good reason to do it, this also works: ansible webserver \-m ansible.builtin.shell \-a "echo {{ a }}" So, in other words, you can use those variables in arguments/actions as well. [Other inventory scripts](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_dynamic_inventory.html#id4) [](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_dynamic_inventory.html#other-inventory-scripts "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- In Ansible 2.10 and later, inventory scripts moved to their associated collections. Many are now in the [ansible-community/contrib-scripts repository](https://github.com/ansible-community/contrib-scripts/tree/main/inventory) . We recommend you use [Inventory plugins](https://docs.ansible.com/projects/ansible-core/devel/plugins/inventory.html#inventory-plugins) instead. [Using inventory directories and multiple inventory sources](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_dynamic_inventory.html#id5) [](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_dynamic_inventory.html#using-inventory-directories-and-multiple-inventory-sources "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- If the location given to `-i` in Ansible is a directory (or as so configured in `ansible.cfg`), Ansible can use multiple inventory sources at the same time. When doing so, it is possible to mix both dynamic and statically managed inventory sources in the same ansible run. Instant hybrid cloud! In an inventory directory, executable files are treated as dynamic inventory sources and most other files as static sources. Files which end with any of the following are ignored: ~, .orig, .bak, .ini, .cfg, .retry, .pyc, .pyo You can replace this list with your own selection by configuring an `inventory_ignore_extensions` list in `ansible.cfg`, or setting the [`ANSIBLE_INVENTORY_IGNORE`](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/config.html#envvar-ANSIBLE_INVENTORY_IGNORE) environment variable. The value in either case must be a comma-separated list of patterns, as shown above. Any `group_vars` and `host_vars` subdirectories in an inventory directory are interpreted as expected, making inventory directories a powerful way to organize different sets of configurations. See [Passing multiple inventory sources](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#using-multiple-inventory-sources) for more information. [Static groups of dynamic groups](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_dynamic_inventory.html#id6) [](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_dynamic_inventory.html#static-groups-of-dynamic-groups "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- When defining groups of groups in the static inventory file, the child groups must also be defined in the static inventory file, otherwise ansible returns an error. If you want to define a static group of dynamic child groups, define the dynamic groups as empty in the static inventory file. For example: \[tag\_Name\_staging\_foo\] \[tag\_Name\_staging\_bar\] \[staging:children\] tag\_Name\_staging\_foo tag\_Name\_staging\_bar See also [How to build your inventory](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#intro-inventory) All about static inventory files [Communication](https://docs.ansible.com/projects/ansible-core/devel/community/communication.html#communication) Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide --- # Testing philosophy - Ansible Molecule [Skip to content](https://docs.ansible.com/projects/molecule/philosophy/#testing-philosophy) [](https://github.com/ansible/molecule/blob/main/docs/philosophy.md "Edit this page") [](https://github.com/ansible/molecule/raw/main/docs/philosophy.md "View source of this page") Testing philosophy[¶](https://docs.ansible.com/projects/molecule/philosophy/#testing-philosophy "Permanent link") ================================================================================================================== This document explores the fundamental principles of automation testing and how Molecule addresses the core needs of modern Ansible development across all domains. What a testing suite provides[¶](https://docs.ansible.com/projects/molecule/philosophy/#what-a-testing-suite-provides "Permanent link") ---------------------------------------------------------------------------------------------------------------------------------------- Testing frameworks serve as the foundation for reliable software development and deployment across diverse domains. Whether developing applications, managing infrastructure, configuring systems, orchestrating deployments, or integrating with external services, a comprehensive testing suite addresses several critical areas that ensure code quality, operational confidence, and maintainable systems. ### Essential functionality requirements[¶](https://docs.ansible.com/projects/molecule/philosophy/#essential-functionality-requirements "Permanent link") **Resource lifecycle management** Testing requires precise control over test environments, whether they're compute resources, application instances, database states, test data, or external service configurations. This includes the ability to create clean, isolated environments for each test run, manage their state throughout the testing process, and reliably tear them down afterward. The framework must handle dependencies between components, ensure proper cleanup even when tests fail, and provide mechanisms for debugging by preserving failed environments when needed. **Test isolation and reproducibility** Each test must run in a predictable, isolated environment that doesn't interfere with other tests or external systems. For infrastructure testing, this means isolated compute resources. For application testing, this requires consistent application states and configuration baselines. For integration testing, this involves controlled staging environments. For API testing, this includes isolated service endpoints or mocked external dependencies. Reproducibility ensures that test results remain consistent across different execution environments, team members, and CI/CD pipelines regardless of the testing domain. **Flexible execution strategies** Modern development workflows demand flexibility in how and when tests execute. This includes support for different test sequences (syntax validation, unit testing, integration testing, end-to-end scenarios), selective test execution for rapid development cycles, parallel processing capabilities for complex multi-component systems, and the ability to share state between related tests when appropriate. The framework must accommodate both developer workflows (quick iteration on code changes) and automated pipeline requirements (comprehensive validation before deployment). **Configuration adaptability** Testing frameworks must support diverse patterns and use cases. This includes multiple platform support (from bare metal to cloud to containers), configurable provisioning strategies (infrastructure, applications, services), environment-specific variable management (development, staging, production), and integration with existing toolchains (CI/CD, monitoring, secret management, external APIs). The configuration system should be both powerful enough for complex multi-tier applications and simple enough for basic testing scenarios. ### Configuration flexibility requirements[¶](https://docs.ansible.com/projects/molecule/philosophy/#configuration-flexibility-requirements "Permanent link") **Multi-platform support** Software systems span diverse platforms and domains: infrastructure (containers, VMs, cloud services, bare metal), applications (web servers, databases, microservices), network devices (routers, switches, firewalls), cloud services (AWS, Azure, GCP), and external systems (REST APIs, SaaS platforms, monitoring tools). Testing frameworks must abstract platform differences while allowing domain-specific optimizations. This includes unified interfaces for common operations, platform-specific configuration options, and consistent behavior across different testing domains. **Variable and secret management** Testing environments require careful handling of configuration data, secrets, and environment-specific variables across all testing domains. This includes database connection strings, API keys, service endpoints, infrastructure credentials, application configuration parameters, and environment-specific overrides. The framework must provide secure secret injection, hierarchical variable override systems, environment-specific configuration, and integration with external secret management systems while supporting the diverse credential types needed for comprehensive testing. **Extensibility and integration** Testing frameworks serve as components in larger development ecosystems spanning infrastructure, applications, and business processes. They must integrate cleanly with CI/CD pipelines, monitoring systems, artifact repositories, development tools, deployment platforms, and external service providers. This requires well-defined APIs, plugin architectures, standardized output formats that other tools can consume, and the ability to coordinate with diverse external systems that modern software development typically interacts with. ### Lifecycle management capabilities[¶](https://docs.ansible.com/projects/molecule/philosophy/#lifecycle-management-capabilities "Permanent link") **Environment provisioning** The framework must create test environments that accurately reflect production conditions while remaining cost-effective and fast to provision. For infrastructure testing, this includes compute resources, networking, and storage. For application testing, this involves application instances, databases, and service dependencies. For API integration testing, this requires mock services or sandboxed external systems. For system testing, this includes multi-tier environments with realistic data flows. The framework must support template-based provisioning, dependency management, network isolation, and resource quota management across all these domains. **State management** Complex testing scenarios require sophisticated state management across multiple domains. This includes checkpointing successful infrastructure states, preserving application configurations between test phases, maintaining database states for integration testing, managing external service interactions, and coordinating state across distributed systems. The framework must support sharing state between test phases, managing concurrent access to shared resources, and providing rollback capabilities when tests fail unexpectedly, regardless of whether the testing targets infrastructure, applications, or external services. **Cleanup and resource recovery** Reliable cleanup prevents resource leaks and ensures consistent test environments across all testing domains. The framework must track all created resources (infrastructure, application instances, database entries, external service configurations), handle cleanup in the presence of failures, provide manual cleanup tools for debugging, and integrate with monitoring systems to detect orphaned resources. This includes cleaning up cloud resources, stopping application services, resetting database states, and reverting external system configurations. **Observability and debugging** When tests fail, teams need comprehensive visibility into what happened across all system layers. This includes detailed logging from infrastructure provisioning, application deployment logs, API interaction traces, configuration change tracking, and performance metrics. The framework must support artifact collection (logs, configurations, state dumps), state snapshots at multiple levels, and integration with debugging tools. It should make it easy to reproduce failures locally and provide enough context to quickly identify root causes whether they stem from infrastructure issues, application configuration problems, external service failures, or system logic errors. Testing workflow fundamentals[¶](https://docs.ansible.com/projects/molecule/philosophy/#testing-workflow-fundamentals "Permanent link") ---------------------------------------------------------------------------------------------------------------------------------------- Effective testing follows a structured workflow that ensures comprehensive validation while maintaining efficiency and reliability. This workflow applies across all testing domains, from unit testing to integration testing to end-to-end system validation. ### Core testing phases[¶](https://docs.ansible.com/projects/molecule/philosophy/#core-testing-phases "Permanent link") **Environment provisioning** The testing process begins with creating clean, isolated environments that accurately represent production conditions. This includes provisioning infrastructure resources (compute, networking, storage), deploying application dependencies (databases, message queues, caching layers), and configuring external service connections (APIs, monitoring endpoints, third-party integrations). The provisioning phase must be fast enough for developer workflows while being comprehensive enough to catch environment-specific issues. **Dependency resolution** Before executing the system under test, the testing framework must ensure all required dependencies are available. This includes software modules, external libraries, configuration files, secrets, and any prerequisite services. Dependency resolution must handle version constraints, conflict detection, and both public and private repositories while supporting offline development scenarios. **Change application and convergence** The core testing phase applies the system logic being tested. This involves executing scripts, configurations, or procedures against the test environment and ensuring they complete successfully. The framework must capture detailed execution logs, handle failures gracefully, and provide mechanisms for incremental development and debugging. This phase validates that the system logic works correctly in realistic conditions. **Idempotence verification** A critical aspect of system testing involves verifying that operations can be run multiple times without causing unintended changes. The framework must re-execute the same system logic and confirm that no changes occur on subsequent runs. This validates that the system properly detects existing states and only makes necessary modifications, preventing drift and ensuring predictable behavior. **Functional verification** After applying changes, the testing framework must validate that the desired outcomes were achieved. This includes verifying infrastructure states (resources created, configurations applied), application behavior (services running, endpoints responding), integration functionality (APIs accessible, data flowing correctly), and business process outcomes (workflows completing, notifications sent). Verification must be comprehensive enough to catch subtle issues while being fast enough for rapid iteration. **Side effect detection** System changes can have unintended consequences beyond their primary objectives. The testing framework must detect side effects such as unexpected resource modifications, service disruptions, security policy changes, performance impacts, or external system effects. This phase helps identify potential issues before they impact production environments. **Resource cleanup and destruction** The final phase involves cleaning up all resources created during testing. This includes infrastructure resources, application instances, database entries, temporary files, external service configurations, and any other artifacts created during the test process. Proper cleanup prevents resource leaks, controls costs, and ensures clean states for subsequent test runs. ### Testing strategy considerations[¶](https://docs.ansible.com/projects/molecule/philosophy/#testing-strategy-considerations "Permanent link") **Isolation vs. efficiency trade-offs** Testing frameworks must balance complete isolation (which ensures clean tests but increases resource usage and execution time) with resource sharing (which improves efficiency but introduces potential cross-test dependencies). The optimal strategy depends on the specific automation being tested, available resources, and team workflows. **Incremental vs. comprehensive testing** During development, teams need fast feedback loops that validate changes quickly. In CI/CD pipelines, comprehensive testing ensures production readiness. The framework must support both incremental testing (validating specific changes) and comprehensive testing (full end-to-end validation) while allowing teams to choose appropriate strategies for different contexts. **State preservation vs. fresh environments** Some testing scenarios benefit from preserving state between test phases (performance testing, migration validation, integration testing), while others require completely fresh environments (unit testing, isolation verification). The framework must support both approaches and allow teams to choose based on their specific testing requirements. How Molecule addresses testing suite requirements[¶](https://docs.ansible.com/projects/molecule/philosophy/#how-molecule-addresses-testing-suite-requirements "Permanent link") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Molecule specifically addresses the unique challenges of testing Ansible automation across all domains while providing the comprehensive testing suite capabilities outlined above. The framework's design reflects deep understanding of both general testing principles and the specific needs of modern automation, whether targeting infrastructure, applications, deployments, integrations, or business processes. ### Ansible-centric testing design[¶](https://docs.ansible.com/projects/molecule/philosophy/#ansible-centric-testing-design "Permanent link") **Playbook-driven lifecycle management** Molecule leverages Ansible's declarative nature by using playbooks to manage the entire test lifecycle across all automation domains. Whether testing infrastructure provisioning, application deployment, configuration management, or external service integration, this approach ensures consistency between test environments and production patterns while providing familiar syntax for Ansible practitioners. The same playbook constructs used for production automation can be used for test environment setup, making tests more representative of real-world usage. **Native integration with Ansible constructs** Rather than wrapping Ansible as an external tool, Molecule integrates directly with Ansible's inventory system, variable hierarchy, and module ecosystem. This tight integration includes native support for external inventory sources, allowing teams to test using existing inventory patterns, dynamic inventory scripts, and inventory plugins. The framework works seamlessly whether you're testing infrastructure modules (cloud resources, networking), application modules (services, configurations), integration modules (APIs, databases), or custom modules. This eliminates impedance mismatches and ensures that test environments accurately reflect production Ansible usage patterns regardless of the automation domain. ### Sequence configuration and workflow control[¶](https://docs.ansible.com/projects/molecule/philosophy/#sequence-configuration-and-workflow-control "Permanent link") **Testing phase to action mapping** Molecule implements the core testing phases through a comprehensive action system that maps directly to testing workflow fundamentals: | Testing Phase | Molecule Action | Purpose | | --- | --- | --- | | Environment provisioning | `create` | Provisions test infrastructure and environments | | Dependency resolution | `dependency` | Installs required roles, collections, and dependencies | | Environment preparation | `prepare` | Configures environments before applying automation logic | | Change application | `converge` | Executes the automation being tested | | Idempotence verification | `idempotence` | Re-runs automation to verify no unintended changes | | Side effect detection | `side_effect` | Executes additional automation to test for unintended consequences | | Functional verification | `verify` | Validates that desired outcomes were achieved | | Resource cleanup | `cleanup` | Removes temporary files and intermediate artifacts | | Resource destruction | `destroy` | Cleans up all provisioned resources | **Configurable test sequences** Molecule's sequence system provides fine-grained control over test execution flow by allowing teams to define custom sequences that match their specific testing requirements. Since its inception in 2015, Molecule's default sequences have been optimized through real-world usage at scale to satisfy most users' testing workflows. However, enterprise environments often have specific workflow requirements that differ from these defaults. Molecule addresses this by allowing sequences to be modified, committed as part of the codebase, and shared between team members, ensuring consistent testing approaches across development teams. Actions can be reordered, removed, or repeated based on testing needs: `[](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-0-1) # Full comprehensive testing sequence [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-0-2) scenario: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-0-3) test_sequence: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-0-4) - dependency # Install requirements [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-0-5) - create # Provision environment [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-0-6) - prepare # Configure environment [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-0-7) - converge # Apply automation [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-0-8) - idempotence # Verify idempotence [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-0-9) - side_effect # Test side effects [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-0-10) - verify # Functional verification [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-0-11) - cleanup # Clean temporary artifacts [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-0-12) - destroy # Remove all resources [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-0-13) [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-0-14) # Rapid development sequence (skips verification phases) [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-0-15) scenario: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-0-16) test_sequence: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-0-17) - dependency [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-0-18) - create [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-0-19) - converge [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-0-20) - destroy [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-0-21) [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-0-22) # Integration testing sequence (preserves state between phases) [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-0-23) scenario: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-0-24) test_sequence: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-0-25) - dependency [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-0-26) - create [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-0-27) - prepare [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-0-28) - converge [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-0-29) - verify [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-0-30) - side_effect [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-0-31) - verify [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-0-32) # Note: cleanup and destroy omitted for state preservation` **Command-line subcommand mapping** Each action in a test sequence corresponds to a specific `molecule` subcommand, allowing developers to execute individual phases during development while ensuring complete automated testing in CI/CD pipelines: | Command | Action | Usage | | --- | --- | --- | | `molecule dependency` | Installs roles and collections | Development setup and CI/CD preparation | | `molecule create` | Provisions test environments | Environment setup for all testing phases | | `molecule prepare` | Configures test environments | Custom environment preparation | | `molecule converge` | Applies automation being tested | Core development and validation workflow | | `molecule idempotence` | Verifies idempotent behavior | Quality assurance and CI/CD validation | | `molecule side_effect` | Tests for unintended effects | Comprehensive testing and regression detection | | `molecule verify` | Validates expected outcomes | Functional testing and acceptance criteria | | `molecule cleanup` | Removes temporary artifacts | Resource management and cost optimization | | `molecule destroy` | Cleans up all resources | Environment teardown and reset | | `molecule test` | Runs complete sequence | Full automated testing workflow | **Selective execution and debugging** Developers can execute any subset of the test sequence, enabling rapid iteration during development and focused debugging when tests fail. This flexibility supports both quick feedback loops (testing playbook logic changes) and comprehensive validation (full deployment workflows): `[](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-1-1) # Quick development iteration [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-1-2) molecule converge # Apply changes [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-1-3) molecule verify # Check outcomes [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-1-4) [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-1-5) # Debug environment issues [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-1-6) molecule create # Set up environment [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-1-7) molecule prepare # Configure environment [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-1-8) # Manually investigate environment state [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-1-9) [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-1-10) # Test idempotence specifically [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-1-11) molecule converge # Apply automation [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-1-12) molecule idempotence # Verify no changes on re-run [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-1-13) [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-1-14) # Full comprehensive testing [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-1-15) molecule test # Run complete sequence` ### Native inventory integration and management[¶](https://docs.ansible.com/projects/molecule/philosophy/#native-inventory-integration-and-management "Permanent link") **Direct integration with Ansible inventory systems** Molecule provides comprehensive support for native Ansible inventory integration, enabling teams to test automation against existing inventory sources rather than relying solely on Molecule-generated inventory from platform configurations. This native inventory capability allows testing automation against the same inventory systems and patterns used in production environments, ensuring true production parity while testing against appropriate lab, staging, or test systems. **External inventory sources** Molecule supports the full spectrum of Ansible inventory sources through direct integration with the `ansible-playbook` command: * **Static inventory files**: Use existing YAML or INI inventory files that define lab, staging, or test resources * **Dynamic inventory scripts**: Leverage cloud provider inventories, CMDB systems, or custom inventory scripts * **Inventory plugins**: Integration with Ansible's inventory plugin ecosystem (AWS, Azure, GCP, Kubernetes, etc.) * **Constructed inventories**: Dynamic grouping and variable assignment based on existing inventory data * **Mixed inventory sources**: Combine multiple inventory types within the same testing scenario * **Multi-source patterns**: Separate infrastructure provider inventory from molecule-specific configuration inventory * **File-based data sharing**: Use temporary files to persist and share host-specific data between actions **Native inventory workflow patterns** Teams can configure Molecule to use external inventory sources by leveraging the `ansible.executor.args.ansible_playbook` configuration to pass inventory parameters directly to `ansible-playbook`. Targeting can be achieved either through `--limit` flags at the molecule level or through `hosts:` directives at the individual playbook level: `[](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-1) # Using external static inventory directory [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-2) ansible: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-3) executor: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-4) args: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-5) ansible_playbook: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-6) - --inventory=${MOLECULE_SCENARIO_DIRECTORY}/inventory/ [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-7) [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-8) # Using cloud inventory plugin [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-9) ansible: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-10) executor: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-11) args: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-12) ansible_playbook: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-13) - --inventory=aws_ec2.yml [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-14) [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-15) # Using existing enterprise inventory with selective targeting [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-16) ansible: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-17) executor: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-18) args: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-19) ansible_playbook: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-20) - --inventory=/path/to/enterprise/inventory/ [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-21) - --limit=staging_environment [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-22) [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-23) # Using multiple inventory sources [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-24) ansible: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-25) executor: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-26) args: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-27) ansible_playbook: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-28) - --inventory=static_hosts.yml [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-29) - --inventory=dynamic_script.py [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-30) - --inventory=constructed_groups.yml [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-31) [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-32) # Combining infrastructure provider inventory with molecule-specific configuration [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-33) ansible: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-34) executor: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-35) args: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-36) ansible_playbook: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-37) - --inventory=aws_ec2.yml # Cloud provider dynamic inventory [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-38) - --inventory=${MOLECULE_SCENARIO_DIRECTORY}/molecule_config.yml # Molecule-specific config [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-39) [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-40) # Using inventory from parent directory (shared across scenarios) [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-41) ansible: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-42) executor: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-43) args: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-44) ansible_playbook: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-45) - --inventory=../shared_inventory/ [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-46) [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-47) # Alternative: Using ansible.cfg for inventory configuration [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-48) ansible: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-49) cfg: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-50) defaults: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-51) host_key_checking: false [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-52) inventory: ../shared_inventory/ [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-53) executor: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-54) args: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-55) ansible_playbook: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-2-56) - --limit=staging_environment` ### Benefits of native inventory integration[¶](https://docs.ansible.com/projects/molecule/philosophy/#benefits-of-native-inventory-integration "Permanent link") * **Single source of truth**: Reuse existing inventory definitions that contain both production and lab/staging/test systems, eliminating inventory duplication and ensuring consistency across environments * **Production parity**: Test using the same inventory systems and patterns as production deployments while targeting appropriate lab or staging systems, ensuring that test environments accurately reflect real-world usage patterns * **Selective targeting**: Use Ansible's `--limit` functionality with existing inventory to target specific environments (lab, staging) without duplicating inventory definitions * **Existing resource utilization**: Leverage already-provisioned infrastructure for testing without requiring Molecule to manage resource lifecycles * **Inventory validation**: Test inventory plugins, dynamic scripts, and constructed configurations as part of the automation testing process * **Enterprise integration**: Use existing CMDB, monitoring, or asset management systems as inventory sources for comprehensive testing * **Multi-source flexibility**: Combine infrastructure provider inventory (cloud/hyperscaler) with molecule-specific configuration inventory for separation of concerns * **Multi-action data sharing**: Use simple file-based patterns to share host-specific data between create, converge, verify, and destroy actions * **Multi-environment testing**: Test automation against development, lab, and staging systems from the same inventory source using different targeting strategies * **Reduced complexity**: Eliminate the need for complex inventory generation and focus on testing automation logic against realistic inventory structures **Single source of truth patterns** A key advantage of native inventory integration is the ability to reuse existing inventory definitions that already contain multiple environments, eliminating the need to duplicate or manage inventory within the testing suite: `[](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-3-1) # Example: Existing enterprise inventory structure [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-3-2) # /opt/ansible/inventory/hosts.yml [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-3-3) all: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-3-4) children: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-3-5) web_servers: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-3-6) children: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-3-7) web_production: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-3-8) hosts: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-3-9) web-prod-01: { environment: production } [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-3-10) web-prod-02: { environment: production } [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-3-11) web_staging: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-3-12) hosts: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-3-13) web-stage-01: { environment: staging } [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-3-14) web-stage-02: { environment: staging } [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-3-15) web_lab: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-3-16) hosts: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-3-17) web-lab-01: { environment: lab } [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-3-18) web-lab-02: { environment: lab } [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-3-19) [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-3-20) # Molecule scenarios using the same inventory with selective targeting [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-3-21) # scenario1/molecule.yml - Test against staging systems [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-3-22) ansible: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-3-23) executor: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-3-24) args: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-3-25) ansible_playbook: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-3-26) - --inventory=/opt/ansible/inventory/ [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-3-27) - --limit=web_staging [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-3-28) [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-3-29) # scenario2/molecule.yml - Test against lab systems [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-3-30) ansible: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-3-31) executor: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-3-32) args: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-3-33) ansible_playbook: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-3-34) - --inventory=/opt/ansible/inventory/ [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-3-35) - --limit=web_lab [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-3-36) [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-3-37) # scenario3/molecule.yml - Test against specific environment [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-3-38) ansible: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-3-39) executor: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-3-40) args: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-3-41) ansible_playbook: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-3-42) - --inventory=/opt/ansible/inventory/ [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-3-43) - --limit=environment_staging` **Alternative targeting approaches** Beyond using `--limit` at the molecule level, teams can also target specific groups directly in playbooks using Ansible's `hosts:` directive: `[](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-4-1) # create.yml - Target only staging web servers [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-4-2) --- [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-4-3) - name: Create staging web infrastructure [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-4-4) hosts: web_staging [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-4-5) gather_facts: false [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-4-6) tasks: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-4-7) - name: Provision staging web servers [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-4-8) # provisioning tasks here [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-4-9) [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-4-10) # converge.yml - Target lab database servers [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-4-11) --- [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-4-12) - name: Configure lab databases [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-4-13) hosts: database_lab [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-4-14) gather_facts: false [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-4-15) tasks: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-4-16) - name: Configure database settings [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-4-17) # configuration tasks here [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-4-18) [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-4-19) # verify.yml - Target specific environment group [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-4-20) --- [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-4-21) - name: Verify test environment [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-4-22) hosts: environment_test [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-4-23) gather_facts: false [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-4-24) tasks: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-4-25) - name: Run verification tests [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-4-26) # verification tasks here` This approach ensures: * **Consistency**: Same inventory structure across all environments * **No duplication**: Single inventory source maintained by operations teams * **Selective targeting**: Choose between `--limit` flags or playbook `hosts:` directives * **Flexible targeting**: Mix and match targeting approaches within the same scenario * **Action-level control**: Different playbooks can target different groups from the same inventory * **Production alignment**: Test scenarios use identical inventory patterns as production deployments **Multi-source inventory patterns** A powerful approach involves combining enterprise infrastructure configuration inventory with molecule-specific test instance definitions. This pattern separates concerns: the infrastructure inventory provides enterprise-level AWS configuration (VPCs, subnets, security groups, required tags), while the molecule inventory defines the specific test instances to be created using that infrastructure: `[](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-5-1) # Example: AWS enterprise infrastructure + Molecule test instances [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-5-2) # molecule.yml [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-5-3) ansible: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-5-4) executor: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-5-5) args: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-5-6) ansible_playbook: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-5-7) - --inventory=aws_infrastructure.yml # Enterprise AWS infrastructure config [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-5-8) - --inventory=${MOLECULE_SCENARIO_DIRECTORY}/molecule_config.yml # Test instances to create [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-5-9) [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-5-10) # aws_infrastructure.yml (enterprise infrastructure configuration) [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-5-11) all: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-5-12) vars: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-5-13) aws_secret: "{{ vault_aws_secret }}" [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-5-14) [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-5-15) # molecule_config.yml (molecule-specific test instances and configuration) [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-5-16) all: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-5-17) vars: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-5-18) ansible_user: ubuntu [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-5-19) children: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-5-20) web_servers: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-5-21) hosts: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-5-22) web-test-01: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-5-23) instance_type: t3.small` This multi-source approach provides: * **Separation of concerns**: Enterprise infrastructure configuration vs. test instance definitions * **Secure credential management**: Use Ansible Vault for sensitive AWS credentials and test secrets * **Enterprise compliance**: Ensure all test instances use required tags, security groups, and compliance settings * **Infrastructure reuse**: Leverage existing enterprise VPCs, subnets, and security configurations for testing * **Provider agnostic**: Works with any cloud provider or infrastructure management system * **Consistent provisioning**: All test instances follow enterprise standards and governance policies * **Reduced maintenance**: Infrastructure team manages enterprise config, testing team manages test instances * **Environment flexibility**: Same enterprise configuration works across different testing scenarios and regions This pattern directly demonstrates several [testing framework requirements](https://docs.ansible.com/projects/molecule/philosophy/#essential-functionality-requirements) : * **Configuration adaptability**: Supporting diverse infrastructure patterns and enterprise integration requirements * **Variable and secret management**: Secure handling of enterprise credentials while maintaining test-specific configurations * **Multi-platform support**: Abstract enterprise infrastructure complexity while enabling test-specific instance definitions * **Extensibility and integration**: Clean integration with existing enterprise toolchains and governance policies **Multi-scenario/multi-action data sharing** When using native inventory patterns, teams often need to share host-specific data between different Molecule actions (create, converge, verify, destroy). This is especially valuable when using `--shared-state`, where the `default` scenario's create action provisions infrastructure and other scenarios need access to resource-specific data captured during that initial provisioning. A simple and effective approach uses temporary files to pass data from one action to subsequent actions: `[](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-1) # Example: Sharing infrastructure and host-specific data between actions [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-2) # default/create.yml - Generate shared infrastructure and host-specific data during provisioning [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-3) --- [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-4) - name: Store infrastructure and host-specific data for other scenarios [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-5) hosts: localhost [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-6) gather_facts: false [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-7) vars: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-8) execution_vars: "{{ molecule_ephemeral_directory }}/execution_vars/" [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-9) tasks: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-10) - name: Ensure execution vars directory exists [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-11) ansible.builtin.file: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-12) path: "{{ execution_vars }}" [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-13) state: directory [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-14) mode: "0755" [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-15) [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-16) - name: Capture build details [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-17) ansible.builtin.command: echo "Initializing host {{ item }} at {{ ansible_date_time.iso8601 }}" [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-18) loop: "{{ groups['molecule'] }}" [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-19) register: results [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-20) [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-21) - name: Write host-specific data files for each molecule host [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-22) ansible.builtin.copy: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-23) dest: "{{ execution_vars }}host_{{ item.item }}.yml" [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-24) content: "{{ data | to_yaml }}" [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-25) mode: "0644" [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-26) vars: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-27) data: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-28) host_specific_value: "{{ item.stdout }}" [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-29) loop: "{{ results.results }}" [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-30) [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-31) # other-scenario/converge.yml - Load host-specific data [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-32) --- [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-33) - name: Configure applications with host-specific data [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-34) hosts: molecule [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-35) gather_facts: false [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-36) vars: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-37) execution_vars: "{{ molecule_ephemeral_directory }}/execution_vars/" [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-38) vars_files: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-39) - "{{ execution_vars }}host_{{ inventory_hostname }}.yml" [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-40) tasks: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-41) - name: Display host-specific data unique to this host [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-42) ansible.builtin.debug: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-43) msg: "Host-specific value: {{ host_specific_value }}" [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-44) [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-45) # default/destroy.yml - Clean up temp files after instances are destroyed [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-46) --- [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-47) - name: Final cleanup of host-specific data [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-48) hosts: localhost [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-49) gather_facts: false [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-50) vars: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-51) execution_vars: "{{ molecule_ephemeral_directory }}/execution_vars/" [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-52) tasks: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-53) - name: Destroying resources [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-54) ansible.builtin.debug: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-55) msg: "Tearing down infrastructure for host: {{ item }}" [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-56) loop: "{{ groups['molecule'] }}" [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-57) [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-58) - name: Remove execution vars directory [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-59) ansible.builtin.file: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-60) path: "{{ execution_vars }}" [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-61) state: absent [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-62) recurse: true [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-6-63) ignore_errors: true` This multi-action data sharing approach provides: * **Cross-action data persistence**: Enable `create` action on localhost to share captured data with subsequent actions on target hosts * **Localhost-to-host data flow**: Demonstrate how localhost operations can provide data for individual host operations * **File-based state sharing**: Use ephemeral directory files to bridge the gap between separate ansible-playbook executions * **Per-host data isolation**: Each host gets its own data file while sharing the same capture mechanism * **Action independence**: Each action can independently access host-specific data from previous actions without complex delegation * **Simple cleanup**: Single directory removal cleans up all execution data files efficiently **Advanced inventory patterns** Native inventory support enables sophisticated testing patterns that mirror production deployment workflows: `[](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-7-1) # Testing with constructed inventory for dynamic grouping [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-7-2) # inventory/01-static.yml [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-7-3) all: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-7-4) hosts: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-7-5) web-01: { role: web, environment: lab } [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-7-6) web-02: { role: web, environment: staging } [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-7-7) db-01: { role: database, environment: lab } [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-7-8) [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-7-9) # inventory/02-constructed.yml [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-7-10) plugin: ansible.builtin.constructed [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-7-11) strict: false [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-7-12) groups: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-7-13) web_servers: role == 'web' [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-7-14) databases: role == 'database' [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-7-15) lab: environment == 'lab' [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-7-16) staging: environment == 'staging' [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-7-17) [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-7-18) # Molecule configuration using this inventory [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-7-19) ansible: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-7-20) executor: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-7-21) args: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-7-22) ansible_playbook: [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-7-23) - --inventory=${MOLECULE_SCENARIO_DIRECTORY}/inventory/` **Cross-scenario inventory coordination** For testing scenarios that require coordination between multiple test runs, teams can use shared inventory directories that multiple scenarios reference: `[](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-8-1) project/ [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-8-2) ├── molecule/ [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-8-3) │ ├── inventory/ # Shared inventory directory [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-8-4) │ │ ├── hosts.yml [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-8-5) │ │ ├── constructed.yml [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-8-6) │ │ └── group_vars/ [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-8-7) │ ├── infrastructure/ [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-8-8) │ │ └── molecule.yml # Points to ../inventory/ [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-8-9) │ ├── application/ [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-8-10) │ │ └── molecule.yml # Points to ../inventory/ [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-8-11) │ └── integration/ [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-8-12) │ └── molecule.yml # Points to ../inventory/` This approach provides inventory coordination benefits while maintaining standard Ansible inventory patterns and eliminating dependency on Molecule-specific inventory management features. **Testing strategy considerations** Teams must balance isolation, resource efficiency, and test reliability when designing their testing approach. Native inventory support enables flexible strategies that can be tailored to specific requirements: **Complete isolation scenarios (recommended for):** * **Independent feature testing**: Each test scenario uses separate inventory and infrastructure to avoid interference * **Unit testing**: Fast, focused tests that validate specific automation logic against isolated resources * **Regression testing**: Ensuring new changes don't break existing functionality in clean environments * **CI/CD pipelines**: Parallel test execution where isolation prevents race conditions and resource conflicts * **Development workflows**: Individual developers use isolated environments for experimentation and iteration **Resource sharing scenarios (recommended for):** * **Integration testing**: Multiple scenarios test against the same infrastructure using shared inventory sources * **Performance testing**: Establishing baselines and measuring changes over time against consistent environments * **Cost-sensitive environments**: Cloud testing where infrastructure costs are significant and resource reuse is beneficial * **Long-running test suites**: Complex scenarios where infrastructure setup time exceeds test execution time * **Production parity testing**: Testing against existing lab or staging inventory sources that mirror production patterns **Implementation strategies** Native inventory support enables various approaches to resource management and test isolation: `[](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-9-1) # Complete isolation - each scenario manages its own resources [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-9-2) molecule test --scenario-name feature-test --report --command-borders [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-9-3) # Uses scenario-specific inventory and infrastructure [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-9-4) [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-9-5) # Shared inventory coordination - multiple scenarios use common inventory [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-9-6) molecule test --scenario-name infrastructure-test --report --command-borders # Uses ../shared_inventory/ [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-9-7) molecule test --scenario-name application-test --report --command-borders # Uses ../shared_inventory/ [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-9-8) molecule test --scenario-name integration-test --report --command-borders # Uses ../shared_inventory/ [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-9-9) [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-9-10) # External inventory testing - test against existing systems [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-9-11) molecule test --scenario-name staging-validation --report --command-borders # Uses --inventory=staging_hosts.yml [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-9-12) molecule test --scenario-name lab-verification --report --command-borders # Uses --inventory=lab_inventory.py [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-9-13) [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-9-14) # Single source of truth with selective targeting [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-9-15) molecule test --scenario-name web-staging --report --command-borders # Uses enterprise inventory --limit=web_staging [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-9-16) molecule test --scenario-name db-lab --report --command-borders # Uses enterprise inventory --limit=database_lab [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-9-17) molecule test --scenario-name app-test --report --command-borders # Uses enterprise inventory --limit=environment_test [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-9-18) [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-9-19) # Playbook-level targeting (no --limit needed) [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-9-20) molecule test --scenario-name staging-deployment --report --command-borders # Playbooks use hosts: web_staging, hosts: db_staging [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-9-21) molecule test --scenario-name lab-testing --report --command-borders # Playbooks use hosts: lab_environment [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-9-22) molecule test --scenario-name multi-tier --report --command-borders # Different actions target different groups [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-9-23) [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-9-24) # Multi-source inventory patterns [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-9-25) molecule test --scenario-name cloud-discovery --report --command-borders # Uses cloud inventory + molecule config [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-9-26) molecule test --scenario-name hybrid-infrastructure --report --command-borders # Uses multiple provider inventories + test config [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-9-27) molecule test --scenario-name dynamic-targeting --report --command-borders # Cloud provider discovers, molecule configures [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-9-28) [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-9-29) # Multi-action data sharing patterns [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-9-30) molecule test --scenario-name host-specific-data --report --command-borders # Uses file-based vars sharing between actions [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-9-31) molecule test --scenario-name secret-propagation --report --command-borders # Shares secrets from create to converge/verify [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-9-32) molecule test --scenario-name dynamic-configuration --report --command-borders # Generates host configs in create, uses in other actions [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-9-33) [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-9-34) # Shared-state with data propagation [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-9-35) molecule test --all --shared-state --report --command-borders # Default creates infrastructure, other scenarios use shared data [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-9-36) molecule test --scenario-name app-deploy --shared-state --report --command-borders # Uses infrastructure data from default scenario [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-9-37) molecule test --scenario-name integration --shared-state --report --command-borders # Accesses database/LB endpoints from default [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-9-38) [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-9-39) # Mixed approach for comprehensive testing [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-9-40) molecule test --scenario-name isolated-unit --report --command-borders # Isolated resources [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-9-41) molecule test --scenario-name shared-integration --report --command-borders # Shared inventory [](https://docs.ansible.com/projects/molecule/philosophy/#__codelineno-9-42) molecule test --scenario-name lab-validation --report --command-borders # External inventory` This flexibility allows teams to optimize their testing strategies based on resource constraints, execution time requirements, and test isolation needs while maintaining the reliability and reproducibility essential for effective automation testing through native Ansible inventory integration. ### Configuration flexibility and extensibility[¶](https://docs.ansible.com/projects/molecule/philosophy/#configuration-flexibility-and-extensibility "Permanent link") **Using Ansible as the default driver** Molecule leverages Ansible as its default driver, providing significant benefits for automation testing across all domains. This approach enables teams to use the same Ansible knowledge, playbooks, and patterns for both test environment management and production automation. By using Ansible's declarative syntax for infrastructure provisioning, application deployment, and service configuration, teams maintain consistency between test environments and production patterns. This reduces learning curves, improves test reliability through familiar constructs, and ensures that test scenarios closely mirror real-world automation usage regardless of the target domain. **Dependency management integration** Molecule integrates with Ansible Galaxy for dependency resolution, ensuring that test environments include all required roles and collections regardless of their domain focus. Whether testing infrastructure automation, application deployment, network configuration, or external service integration, this integration supports both public and private repositories while handling version constraints and conflict resolution across all types of Ansible content. **Using Ansible as provisioner and verifier** Molecule uses Ansible as both the provisioner and verifier, providing unified automation execution and validation logic across all testing scenarios. This approach ensures that teams use the same Ansible skills, modules, and patterns for both test execution and validation that they use in production automation. Whether provisioning infrastructure, deploying applications, configuring services, or validating outcomes, Ansible's extensive module ecosystem provides consistent interfaces for all automation domains. This unified approach reduces complexity, leverages existing team expertise, and ensures that test validation logic can be easily understood and maintained by any team member familiar with Ansible. ### Resource lifecycle optimization[¶](https://docs.ansible.com/projects/molecule/philosophy/#resource-lifecycle-optimization "Permanent link") **Efficient environment provisioning** Molecule optimizes test environment creation through template reuse, incremental updates, and parallel provisioning where supported by the underlying platform. These optimizations work across all automation domains: infrastructure resources, application instances, database configurations, and external service setups. The framework reduces test execution time while maintaining isolation guarantees regardless of whether you're testing infrastructure provisioning, application deployment, or complex integration scenarios. **Intelligent cleanup strategies** The framework provides multiple cleanup strategies, from complete teardown to selective resource removal across all automation domains. This flexibility supports both cost optimization (cleaning up expensive cloud resources) and debugging workflows where preserving failed environments aids troubleshooting (maintaining application logs, database states, or external service configurations for post-test analysis). **Integration with automation as code** Molecule's approach aligns naturally with automation as code principles, treating test environments as versioned, repeatable, and auditable across all domains. Whether managing infrastructure, applications, integrations, or business processes, this alignment ensures that testing practices support broader automation maturity goals and DevOps transformation initiatives. Through this comprehensive approach, Molecule transforms Ansible testing from an ad-hoc activity into a structured, repeatable practice that scales from individual development through enterprise deployment pipelines. The framework's design acknowledges that effective testing must balance thoroughness with practicality across all automation domains, providing the tools teams need to implement testing strategies that actually get used regardless of whether they're automating infrastructure, applications, integrations, or complex business processes. Molecule's evolution with Ansible[¶](https://docs.ansible.com/projects/molecule/philosophy/#molecules-evolution-with-ansible "Permanent link") ----------------------------------------------------------------------------------------------------------------------------------------------- As Ansible has emerged as the de facto DSL for automation, Molecule's development continues with deeper Ansible integration as the primary focus. Rather than broadening tool support, Molecule's evolution prioritizes making the Molecule + Ansible experience seamless, intuitive, and powerful while maintaining backward compatibility for existing workflows. ### Current and planned integration enhancements[¶](https://docs.ansible.com/projects/molecule/philosophy/#current-and-planned-integration-enhancements "Permanent link") **Enhanced collection testing support** Molecule's native inventory integration capabilities provide comprehensive support for Ansible collection testing scenarios. This includes automatic collection detection to streamline testing workflows, improved collection dependency resolution, and optimized testing patterns that reflect how collections are developed and deployed in enterprise environments using existing inventory systems. **Unified user experience** Visual and functional alignment with Ansible's output patterns ensures that teams experience consistent interfaces across their automation toolkit. This includes UI changes that better integrate Molecule's test output with standard Ansible playbook output, making the transition between development, testing, and deployment workflows more natural and reducing cognitive overhead for automation practitioners. **Deeper inventory integration** More obvious and tighter integration with Ansible's inventory systems eliminates friction between test and production inventory patterns. This includes comprehensive native support for external inventory sources (static files, dynamic scripts, and inventory plugins), improved inventory validation during testing, and clearer mapping between test inventory structures and production deployment patterns. Teams can seamlessly test automation using production inventory patterns against appropriate lab and staging systems while maintaining flexibility for cross-scenario coordination through standard Ansible inventory patterns. **Extended executor support** Support for modern Ansible execution environments through tools like ansible-navigator enables testing within the same containerized environments used for production automation. This ensures test environments more accurately reflect production execution contexts while supporting the shift toward standardized, reproducible automation execution environments. **Streamlined automation workflows** Automatic detection and configuration of Ansible collections, roles, and dependencies reduces manual configuration overhead while ensuring that testing workflows automatically adapt to evolving automation codebases. This includes intelligent detection of collection structures, automatic dependency resolution, and seamless integration with Ansible Galaxy workflows. ### Strategic direction[¶](https://docs.ansible.com/projects/molecule/philosophy/#strategic-direction "Permanent link") Molecule's roadmap focuses on becoming the definitive testing solution for Ansible automation rather than a generic testing framework. This specialization enables deeper integration, more intuitive workflows, and better alignment with Ansible ecosystem patterns while ensuring that teams can leverage their existing Ansible expertise throughout their entire testing lifecycle. The framework's evolution maintains backward compatibility with existing workflows while progressively enhancing the Ansible-native experience, ensuring that teams can adopt new capabilities at their own pace without disrupting established testing practices. Back to top --- # Collection Index — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * Collection Index * * * * Collection Index[](https://docs.ansible.com/projects/ansible-core/devel/collections/index.html#collection-index "Link to this heading") ========================================================================================================================================= These are the collections with docs hosted on [docs.ansible.com](https://docs.ansible.com/) . * [ansible.builtin](https://docs.ansible.com/projects/ansible-core/devel/collections/ansible/builtin/index.html#plugins-in-ansible-builtin) --- # Network Getting Started — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * Network Getting Started * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/network/getting_started/index.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Network Getting Started[](https://docs.ansible.com/projects/ansible/latest/network/getting_started/index.html#network-getting-started "Link to this heading") =============================================================================================================================================================== Ansible collections support a wide range of vendors, device types, and actions, so you can manage your entire network with a single automation tool. With Ansible, you can: * Automate repetitive tasks to speed routine network changes and free up your time for more strategic work * Leverage the same simple, powerful, and agentless automation tool for network tasks that operations and development use * Separate the data model (in a playbook or role) from the execution layer (through Ansible modules) to manage heterogeneous network devices * Benefit from community and vendor-generated sample playbooks and roles to help accelerate network automation projects * Communicate securely with network hardware over SSH or HTTPS **Who should use this guide?** This guide is intended for network engineers using Ansible for the first time. If you understand networks but have never used Ansible, work through the guide from start to finish. This guide is also useful for experienced Ansible users automating network tasks for the first time. You can use Ansible commands, playbooks and modules to configure hubs, switches, routers, bridges and other network devices. But network modules are different from Linux/Unix and Windows modules, and you must understand some network-specific concepts to succeed. If you understand Ansible but have never automated a network task, start with the second section. This guide introduces basic Ansible concepts and guides you through your first Ansible commands, playbooks and inventory entries. Getting Started Guide * [Basic Concepts](https://docs.ansible.com/projects/ansible/latest/network/getting_started/basic_concepts.html) * [Control node](https://docs.ansible.com/projects/ansible/latest/network/getting_started/basic_concepts.html#control-node) * [Managed nodes](https://docs.ansible.com/projects/ansible/latest/network/getting_started/basic_concepts.html#managed-nodes) * [Inventory](https://docs.ansible.com/projects/ansible/latest/network/getting_started/basic_concepts.html#inventory) * [Playbooks](https://docs.ansible.com/projects/ansible/latest/network/getting_started/basic_concepts.html#playbooks) * [Modules](https://docs.ansible.com/projects/ansible/latest/network/getting_started/basic_concepts.html#modules) * [Plugins](https://docs.ansible.com/projects/ansible/latest/network/getting_started/basic_concepts.html#plugins) * [Collections](https://docs.ansible.com/projects/ansible/latest/network/getting_started/basic_concepts.html#collections) * [How Network Automation is Different](https://docs.ansible.com/projects/ansible/latest/network/getting_started/network_differences.html) * [Execution on the control node](https://docs.ansible.com/projects/ansible/latest/network/getting_started/network_differences.html#execution-on-the-control-node) * [Multiple communication protocols](https://docs.ansible.com/projects/ansible/latest/network/getting_started/network_differences.html#multiple-communication-protocols) * [Collections organized by network platform](https://docs.ansible.com/projects/ansible/latest/network/getting_started/network_differences.html#collections-organized-by-network-platform) * [Privilege Escalation: `enable` mode, `become`, and `authorize`](https://docs.ansible.com/projects/ansible/latest/network/getting_started/network_differences.html#privilege-escalation-enable-mode-become-and-authorize) * [Run Your First Command and Playbook](https://docs.ansible.com/projects/ansible/latest/network/getting_started/first_playbook.html) * [Prerequisites](https://docs.ansible.com/projects/ansible/latest/network/getting_started/first_playbook.html#prerequisites) * [Install Ansible](https://docs.ansible.com/projects/ansible/latest/network/getting_started/first_playbook.html#install-ansible) * [Establish a manual connection to a managed node](https://docs.ansible.com/projects/ansible/latest/network/getting_started/first_playbook.html#establish-a-manual-connection-to-a-managed-node) * [Run your first network Ansible command](https://docs.ansible.com/projects/ansible/latest/network/getting_started/first_playbook.html#run-your-first-network-ansible-command) * [Create and run your first network Ansible Playbook](https://docs.ansible.com/projects/ansible/latest/network/getting_started/first_playbook.html#create-and-run-your-first-network-ansible-playbook) * [Gathering facts from network devices](https://docs.ansible.com/projects/ansible/latest/network/getting_started/first_playbook.html#gathering-facts-from-network-devices) * [Build Your Inventory](https://docs.ansible.com/projects/ansible/latest/network/getting_started/first_inventory.html) * [Basic inventory](https://docs.ansible.com/projects/ansible/latest/network/getting_started/first_inventory.html#basic-inventory) * [Add variables to the inventory](https://docs.ansible.com/projects/ansible/latest/network/getting_started/first_inventory.html#add-variables-to-the-inventory) * [Group variables within inventory](https://docs.ansible.com/projects/ansible/latest/network/getting_started/first_inventory.html#group-variables-within-inventory) * [Variable syntax](https://docs.ansible.com/projects/ansible/latest/network/getting_started/first_inventory.html#variable-syntax) * [Group inventory by platform](https://docs.ansible.com/projects/ansible/latest/network/getting_started/first_inventory.html#group-inventory-by-platform) * [Verifying the inventory](https://docs.ansible.com/projects/ansible/latest/network/getting_started/first_inventory.html#verifying-the-inventory) * [Protecting sensitive variables with `ansible-vault`](https://docs.ansible.com/projects/ansible/latest/network/getting_started/first_inventory.html#protecting-sensitive-variables-with-ansible-vault) * [Use Ansible network roles](https://docs.ansible.com/projects/ansible/latest/network/getting_started/network_roles.html) * [Understanding roles](https://docs.ansible.com/projects/ansible/latest/network/getting_started/network_roles.html#understanding-roles) * [Beyond the basics](https://docs.ansible.com/projects/ansible/latest/network/getting_started/intermediate_concepts.html) * [A typical Ansible filetree](https://docs.ansible.com/projects/ansible/latest/network/getting_started/intermediate_concepts.html#a-typical-ansible-filetree) * [Tracking changes to inventory and playbooks: source control with git](https://docs.ansible.com/projects/ansible/latest/network/getting_started/intermediate_concepts.html#tracking-changes-to-inventory-and-playbooks-source-control-with-git) * [Working with network connection options](https://docs.ansible.com/projects/ansible/latest/network/getting_started/network_connection_options.html) * [Setting timeout options](https://docs.ansible.com/projects/ansible/latest/network/getting_started/network_connection_options.html#setting-timeout-options) * [Resources and next steps](https://docs.ansible.com/projects/ansible/latest/network/getting_started/network_resources.html) * [Community](https://docs.ansible.com/projects/ansible/latest/network/getting_started/network_resources.html#community) * [Documents](https://docs.ansible.com/projects/ansible/latest/network/getting_started/network_resources.html#documents) * [Events (on video and in person)](https://docs.ansible.com/projects/ansible/latest/network/getting_started/network_resources.html#events-on-video-and-in-person) * [GitHub repos](https://docs.ansible.com/projects/ansible/latest/network/getting_started/network_resources.html#github-repos) * [Chat channels](https://docs.ansible.com/projects/ansible/latest/network/getting_started/network_resources.html#chat-channels) --- # Network Advanced Topics — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * Network Advanced Topics * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/network/user_guide/index.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Network Advanced Topics[](https://docs.ansible.com/projects/ansible/latest/network/user_guide/index.html#network-advanced-topics "Link to this heading") ========================================================================================================================================================== Once you have mastered the basics of network automation with Ansible, as presented in [Network Getting Started](https://docs.ansible.com/projects/ansible/latest/network/getting_started/index.html#network-getting-started) , use this guide understand platform-specific details, optimization, and troubleshooting tips for Ansible for network automation. **Who should use this guide?** This guide is intended for network engineers using Ansible for automation. It covers advanced topics. If you understand networks and Ansible, this guide is for you. You may read through the entire guide if you choose, or use the links below to find the specific information you need. If you’re new to Ansible, or new to using Ansible for network automation, start with the [Network Getting Started](https://docs.ansible.com/projects/ansible/latest/network/getting_started/index.html#network-getting-started) . Advanced Topics * [Network Resource Modules](https://docs.ansible.com/projects/ansible/latest/network/user_guide/network_resource_modules.html) * [Network resource module states](https://docs.ansible.com/projects/ansible/latest/network/user_guide/network_resource_modules.html#network-resource-module-states) * [Using network resource modules](https://docs.ansible.com/projects/ansible/latest/network/user_guide/network_resource_modules.html#using-network-resource-modules) * [Example: Verifying the network device configuration has not changed](https://docs.ansible.com/projects/ansible/latest/network/user_guide/network_resource_modules.html#example-verifying-the-network-device-configuration-has-not-changed) * [Example: Acquiring and updating VLANs on a network device](https://docs.ansible.com/projects/ansible/latest/network/user_guide/network_resource_modules.html#example-acquiring-and-updating-vlans-on-a-network-device) * [Ansible Network Examples](https://docs.ansible.com/projects/ansible/latest/network/user_guide/network_best_practices_2.5.html) * [Prerequisites](https://docs.ansible.com/projects/ansible/latest/network/user_guide/network_best_practices_2.5.html#prerequisites) * [Groups and variables in an inventory file](https://docs.ansible.com/projects/ansible/latest/network/user_guide/network_best_practices_2.5.html#groups-and-variables-in-an-inventory-file) * [Example 1: collecting facts and creating backup files with a playbook](https://docs.ansible.com/projects/ansible/latest/network/user_guide/network_best_practices_2.5.html#example-1-collecting-facts-and-creating-backup-files-with-a-playbook) * [Example 2: simplifying playbooks with platform-independent modules](https://docs.ansible.com/projects/ansible/latest/network/user_guide/network_best_practices_2.5.html#example-2-simplifying-playbooks-with-platform-independent-modules) * [Implementation Notes](https://docs.ansible.com/projects/ansible/latest/network/user_guide/network_best_practices_2.5.html#implementation-notes) * [Troubleshooting](https://docs.ansible.com/projects/ansible/latest/network/user_guide/network_best_practices_2.5.html#troubleshooting) * [Parsing semi-structured text with Ansible](https://docs.ansible.com/projects/ansible/latest/network/user_guide/cli_parsing.html) * [Understanding the CLI parser](https://docs.ansible.com/projects/ansible/latest/network/user_guide/cli_parsing.html#understanding-the-cli-parser) * [Parsing the CLI](https://docs.ansible.com/projects/ansible/latest/network/user_guide/cli_parsing.html#parsing-the-cli) * [Advanced use cases](https://docs.ansible.com/projects/ansible/latest/network/user_guide/cli_parsing.html#advanced-use-cases) * [Validate data against set criteria with Ansible](https://docs.ansible.com/projects/ansible/latest/network/user_guide/validate.html) * [Understanding the validate plugin](https://docs.ansible.com/projects/ansible/latest/network/user_guide/validate.html#understanding-the-validate-plugin) * [Structuring the data](https://docs.ansible.com/projects/ansible/latest/network/user_guide/validate.html#structuring-the-data) * [Defining the criteria to validate against](https://docs.ansible.com/projects/ansible/latest/network/user_guide/validate.html#defining-the-criteria-to-validate-against) * [Validating the data](https://docs.ansible.com/projects/ansible/latest/network/user_guide/validate.html#validating-the-data) * [Network Debug and Troubleshooting Guide](https://docs.ansible.com/projects/ansible/latest/network/user_guide/network_debug_troubleshooting.html) * [How to troubleshoot](https://docs.ansible.com/projects/ansible/latest/network/user_guide/network_debug_troubleshooting.html#how-to-troubleshoot) * [Troubleshooting socket path issues](https://docs.ansible.com/projects/ansible/latest/network/user_guide/network_debug_troubleshooting.html#troubleshooting-socket-path-issues) * [Category “Unable to open shell”](https://docs.ansible.com/projects/ansible/latest/network/user_guide/network_debug_troubleshooting.html#category-unable-to-open-shell) * [Timeout issues](https://docs.ansible.com/projects/ansible/latest/network/user_guide/network_debug_troubleshooting.html#timeout-issues) * [Playbook issues](https://docs.ansible.com/projects/ansible/latest/network/user_guide/network_debug_troubleshooting.html#playbook-issues) * [Proxy Issues](https://docs.ansible.com/projects/ansible/latest/network/user_guide/network_debug_troubleshooting.html#proxy-issues) * [Miscellaneous Issues](https://docs.ansible.com/projects/ansible/latest/network/user_guide/network_debug_troubleshooting.html#miscellaneous-issues) * [Working with command output and prompts in network modules](https://docs.ansible.com/projects/ansible/latest/network/user_guide/network_working_with_command_output.html) * [Conditionals in networking modules](https://docs.ansible.com/projects/ansible/latest/network/user_guide/network_working_with_command_output.html#conditionals-in-networking-modules) * [Handling prompts in network modules](https://docs.ansible.com/projects/ansible/latest/network/user_guide/network_working_with_command_output.html#handling-prompts-in-network-modules) * [Ansible Network FAQ](https://docs.ansible.com/projects/ansible/latest/network/user_guide/faq.html) * [How can I improve performance for network playbooks?](https://docs.ansible.com/projects/ansible/latest/network/user_guide/faq.html#how-can-i-improve-performance-for-network-playbooks) * [Why is my output sometimes replaced with `********`?](https://docs.ansible.com/projects/ansible/latest/network/user_guide/faq.html#why-is-my-output-sometimes-replaced-with) * [Why do the `*_config` modules always return `changed=true` with abbreviated commands?](https://docs.ansible.com/projects/ansible/latest/network/user_guide/faq.html#why-do-the-config-modules-always-return-changed-true-with-abbreviated-commands) * [Platform Options](https://docs.ansible.com/projects/ansible/latest/network/user_guide/platform_index.html) * [CloudEngine OS Platform Options](https://docs.ansible.com/projects/ansible/latest/network/user_guide/platform_ce.html) * [CNOS Platform Options](https://docs.ansible.com/projects/ansible/latest/network/user_guide/platform_cnos.html) * [Dell OS6 Platform Options](https://docs.ansible.com/projects/ansible/latest/network/user_guide/platform_dellos6.html) * [Dell OS9 Platform Options](https://docs.ansible.com/projects/ansible/latest/network/user_guide/platform_dellos9.html) * [Dell OS10 Platform Options](https://docs.ansible.com/projects/ansible/latest/network/user_guide/platform_dellos10.html) * [ENOS Platform Options](https://docs.ansible.com/projects/ansible/latest/network/user_guide/platform_enos.html) * [EOS Platform Options](https://docs.ansible.com/projects/ansible/latest/network/user_guide/platform_eos.html) * [ERIC\_ECCLI Platform Options](https://docs.ansible.com/projects/ansible/latest/network/user_guide/platform_eric_eccli.html) * [EXOS Platform Options](https://docs.ansible.com/projects/ansible/latest/network/user_guide/platform_exos.html) * [FRR Platform Options](https://docs.ansible.com/projects/ansible/latest/network/user_guide/platform_frr.html) * [ICX Platform Options](https://docs.ansible.com/projects/ansible/latest/network/user_guide/platform_icx.html) * [IOS Platform Options](https://docs.ansible.com/projects/ansible/latest/network/user_guide/platform_ios.html) * [IOS-XR Platform Options](https://docs.ansible.com/projects/ansible/latest/network/user_guide/platform_iosxr.html) * [IronWare Platform Options](https://docs.ansible.com/projects/ansible/latest/network/user_guide/platform_ironware.html) * [Junos OS Platform Options](https://docs.ansible.com/projects/ansible/latest/network/user_guide/platform_junos.html) * [Meraki Platform Options](https://docs.ansible.com/projects/ansible/latest/network/user_guide/platform_meraki.html) * [Pluribus NETVISOR Platform Options](https://docs.ansible.com/projects/ansible/latest/network/user_guide/platform_netvisor.html) * [NOS Platform Options](https://docs.ansible.com/projects/ansible/latest/network/user_guide/platform_nos.html) * [NXOS Platform Options](https://docs.ansible.com/projects/ansible/latest/network/user_guide/platform_nxos.html) * [RouterOS Platform Options](https://docs.ansible.com/projects/ansible/latest/network/user_guide/platform_routeros.html) * [SLX-OS Platform Options](https://docs.ansible.com/projects/ansible/latest/network/user_guide/platform_slxos.html) * [VOSS Platform Options](https://docs.ansible.com/projects/ansible/latest/network/user_guide/platform_voss.html) * [VyOS Platform Options](https://docs.ansible.com/projects/ansible/latest/network/user_guide/platform_vyos.html) * [WeOS 4 Platform Options](https://docs.ansible.com/projects/ansible/latest/network/user_guide/platform_weos4.html) * [Netconf enabled Platform Options](https://docs.ansible.com/projects/ansible/latest/network/user_guide/platform_netconf_enabled.html) * [Settings by Platform](https://docs.ansible.com/projects/ansible/latest/network/user_guide/platform_index.html#settings-by-platform) --- # Python 3 Support — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * Python 3 Support * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/reference_appendices/python_3_support.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Python 3 Support[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/python_3_support.html#python-3-support "Link to this heading") ========================================================================================================================================================= Ansible 2.5 and above work with Python 3. Previous to 2.5, using Python 3 was considered a tech preview. This topic discusses how to set up your control node and managed machines to use Python 3. See [Control Node Requirements](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#control-node-requirements) and [Managed Node Requirements](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#managed-node-requirements) for the specific versions supported. On the control node side[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/python_3_support.html#on-the-control-node-side "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The easiest way to run **/usr/bin/ansible** under Python 3 is to install it with the Python3 version of pip. This will make the default **/usr/bin/ansible** run with Python3: $ pip3 install ansible $ ansible \--version | grep "python version" python version \= 3.10.5 (main, Jun 9 2022, 00:00:00) \[GCC 12.1.1 20220507 (Red Hat 12.1.1-1)\] (/usr/bin/python) If you are running Ansible [Running the devel branch from a clone](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#from-source) and want to use Python 3 with your source checkout, run your command through `python3`. For example: $ source ./hacking/env-setup $ python3 $(which ansible) localhost \-m ping $ python3 $(which ansible-playbook) sample-playbook.yml Note Individual Linux distribution packages may be packaged for Python2 or Python3. When running from distro packages you’ll only be able to use Ansible with the Python version for which it was installed. Sometimes distros will provide a means of installing for several Python versions (through a separate package or through some commands that are run after install). You’ll need to check with your distro to see if that applies in your case. Using Python 3 on the managed machines with commands and playbooks[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/python_3_support.html#using-python-3-on-the-managed-machines-with-commands-and-playbooks "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * Ansible will automatically detect and use Python 3 on many platforms that ship with it. To explicitly configure a Python 3 interpreter, set the `ansible_python_interpreter` inventory variable at a group or host level to the location of a Python 3 interpreter, such as **/usr/bin/python3**. The default interpreter path may also be set in `ansible.cfg`. See also [Interpreter Discovery](https://docs.ansible.com/projects/ansible/latest/reference_appendices/interpreter_discovery.html#interpreter-discovery) for more information. \# Example inventory that makes an alias for localhost that uses Python3 localhost-py3 ansible\_host\=localhost ansible\_connection=local ansible\_python\_interpreter=/usr/bin/python3 \# Example of setting a group of hosts to use Python3 \[py3\_hosts\] ubuntu16 fedora27 \[py3\_hosts:vars\] ansible\_python\_interpreter\=/usr/bin/python3 See also [How to build your inventory](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#intro-inventory) for more information. * Run your command or playbook: $ ansible localhost-py3 \-m ping $ ansible-playbook sample-playbook.yml Note that you can also use the \-e command line option to manually set the python interpreter when you run a command. This can be useful if you want to test whether a specific module or playbook has any bugs under Python 3. For example: $ ansible localhost \-m ping \-e 'ansible\_python\_interpreter=/usr/bin/python3' $ ansible-playbook sample-playbook.yml \-e 'ansible\_python\_interpreter=/usr/bin/python3' What to do if an incompatibility is found[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/python_3_support.html#what-to-do-if-an-incompatibility-is-found "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- We have spent several releases squashing bugs and adding new tests so that Ansible’s core feature set runs under both Python 2 and Python 3. However, bugs may still exist in edge cases and many of the modules shipped with Ansible are maintained by the community and not all of those may be ported yet. If you find a bug running under Python 3 you can submit a bug report on [Ansible’s GitHub project](https://github.com/ansible/ansible/issues/) . Be sure to mention Python3 in the bug report so that the right people look at it. If you would like to fix the code and submit a pull request on github, you can refer to [Ansible and Python 3](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_python_3.html#developing-python-3) for information on how we fix common Python3 compatibility issues in the Ansible codebase. --- # Ansible Automation Hub — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * Ansible Automation Hub * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/reference_appendices/automationhub.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Ansible Automation Hub[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/automationhub.html#ansible-automation-hub "Link to this heading") ================================================================================================================================================================== [Ansible Automation Hub](https://www.ansible.com/products/automation-hub) is the official location to discover and download certified [collections](https://catalog.redhat.com/software/search?type=Ansible%20Collection&p=1) , included as part of an Ansible Automation Platform subscription. These content collections contain modules, plugins, roles, and playbooks in a downloadable package. Ansible Automation Hub gives you direct access to trusted content collections from Red Hat and Certified Partners. You can find content by topic or Ansible Partner organizations. Ansible Automation Hub is the downstream Red Hat supported product version of Ansible Galaxy. Find out more about Ansible Automation Hub features and how to access it at [Ansible Automation Hub](https://www.ansible.com/products/automation-hub) . Ansible Automation Hub is part of the Red Hat Ansible Automation Platform subscription, and comes bundled with support from Red Hat, Inc. --- # Connection methods and details — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * [Building Ansible inventories](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/index.html) * Connection methods and details * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/inventory_guide/connection_details.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Connection methods and details[](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/connection_details.html#connection-methods-and-details "Link to this heading") ====================================================================================================================================================================================== This section shows you how to expand and refine the connection methods Ansible uses for your inventory. ControlPersist and paramiko[](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/connection_details.html#controlpersist-and-paramiko "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- By default, Ansible uses native OpenSSH, because it supports ControlPersist (a performance feature), Kerberos, and options in `~/.ssh/config` such as Jump Host setup. If your control machine uses an older version of OpenSSH that does not support ControlPersist, Ansible will fall back to a Python implementation of OpenSSH called ‘paramiko’. Setting a remote user[](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/connection_details.html#setting-a-remote-user "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------- By default, Ansible connects to all remote devices with the username you are using on the control node. If that username does not exist on a remote device, you can set a different username for the connection. If you just need to do some tasks as a different user, look at [Understanding privilege escalation: become](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_privilege_escalation.html#become) . You can set the connection user in a playbook: \--- \- name: update webservers hosts: webservers remote\_user: admin tasks: \- name: thing to do first in this playbook \# ... as a host variable in inventory: other1.example.com ansible\_connection=ssh ansible\_user=myuser other2.example.com ansible\_connection=ssh ansible\_user=myotheruser or as a group variable in inventory: cloud: hosts: cloud1: my\_backup.cloud.com cloud2: my\_backup2.cloud.com vars: ansible\_user: admin See also [ssh – connect via ssh client binary](https://docs.ansible.com/projects/ansible/2.9/plugins/connection/ssh.html#ssh-connection "(in Ansible v2.9)") Details on the `remote_user` keyword and `ansible_user` variable. [Controlling how Ansible behaves: precedence rules](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/general_precedence.html#general-precedence-rules) Details on Ansible precedence rules. Setting up SSH keys[](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/connection_details.html#setting-up-ssh-keys "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------- By default, Ansible assumes you are using SSH keys to connect to remote machines. SSH keys are encouraged, but you can use password authentication if needed with the `--ask-pass` option. If you need to provide a password for [privilege escalation](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_privilege_escalation.html#become) (sudo, pbrun, and so on), use `--ask-become-pass`. Note Ansible does not expose a channel to allow communication between the user and the ssh process to accept a password manually to decrypt an ssh key when using the ssh connection plugin (which is the default). The use of `ssh-agent` is highly recommended. To set up SSH agent to avoid retyping passwords, you can do: $ ssh-agent bash $ ssh-add ~/.ssh/id\_rsa Depending on your setup, you may wish to use Ansible’s `--private-key` command line option to specify a pem file instead. You can also add the private key file: $ ssh-agent bash $ ssh-add ~/.ssh/keypair.pem Another way to add private key files without using ssh-agent is using `ansible_ssh_private_key_file` in an inventory file as explained here: [How to build your inventory](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#intro-inventory) . Running against localhost[](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/connection_details.html#running-against-localhost "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can run commands against the control node by using “localhost” or “127.0.0.1” for the server name: $ ansible localhost \-m ping \-e 'ansible\_python\_interpreter="/usr/bin/env python"' You can specify localhost explicitly by adding this to your inventory file: localhost ansible\_connection\=local ansible\_python\_interpreter\="/usr/bin/env python" Managing host key checking[](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/connection_details.html#managing-host-key-checking "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ Ansible enables host key checking by default. Checking host keys guards against server spoofing and man-in-the-middle attacks, but it does require some maintenance. If a host is reinstalled and has a different key in ‘known\_hosts’, this will result in an error message until corrected. If a new host is not in ‘known\_hosts’ your control node may prompt for confirmation of the key, which results in an interactive experience if using Ansible, from say, cron. You might not want this. If you understand the implications and wish to disable this behavior, you can do so by editing `/etc/ansible/ansible.cfg` or `~/.ansible.cfg`: \[defaults\] host\_key\_checking = False Alternatively, this can be set by the [`ANSIBLE_HOST_KEY_CHECKING`](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/config.html#envvar-ANSIBLE_HOST_KEY_CHECKING) environment variable: $ export ANSIBLE\_HOST\_KEY\_CHECKING\=False Also note that host key checking in `paramiko` mode is reasonably slow, therefore switching to ‘ssh’ is also recommended when using this feature. Other connection methods[](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/connection_details.html#other-connection-methods "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Ansible can use a variety of connection methods beyond SSH. You can select any connection plugin, including managing things locally and managing chroot, lxc, and jail containers. A mode called ‘ansible-pull’ can also invert the system and have systems ‘phone home’ with scheduled Git checkouts to pull configuration directives from a central repository. --- # Installing Ansible on specific operating systems — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * [Installation Guide](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/index.html) * Installing Ansible on specific operating systems * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/installation_guide/installation_distros.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Installing Ansible on specific operating systems[](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/installation_distros.html#installing-ansible-on-specific-operating-systems "Link to this heading") =============================================================================================================================================================================================================================== Note These instructions come from their respective communities. If you encounter bugs or issues, file them with that community to update these instructions. Ansible maintains only the `pip install` instructions. You can always [install the ansible package from PyPI using pip](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#intro-installation-guide) on most systems. The community also packages and maintains Ansible for various Linux distributions. This guide shows you how to install Ansible from different distribution package repositories. Requirements for adding new distributions[](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/installation_distros.html#requirements-for-adding-new-distributions "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Package maintainers who want to add instructions for another distribution to this guide must meet the following requirements: * Ensure the distribution provides a reasonably up-to-date version of `ansible`. * Keep `ansible-core` and `ansible` versions synchronized to the extent that the build system allows. * Provide a way to contact the distribution maintainers as part of the instructions. * Distribution maintainers are also encouraged to join and monitor the [Ansible Packaging](https://matrix.to/#/#packaging:ansible.com) Matrix room. Installing Ansible on Fedora Linux[](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/installation_distros.html#installing-ansible-on-fedora-linux "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Fedora Linux provides both the full Ansible package and the minimal ansible-core package through the standard repositories. Install the full `ansible` package: $ sudo dnf install ansible Install the minimal `ansible-core` package: $ sudo dnf install ansible-core Fedora repositories include several Ansible collections as standalone packages that you can install alongside `ansible-core`. For example, install the `community.general` collection: $ sudo dnf install ansible-collection-community-general See the [Fedora Packages index](https://packages.fedoraproject.org/search?query=ansible-collection) for a complete list of Ansible collections packaged in Fedora. Contact the package maintainers by [filing a bug](https://bugzilla.redhat.com/enter_bug.cgi) against the `Fedora` product in Red Hat Bugzilla. Installing Ansible from EPEL[](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/installation_distros.html#installing-ansible-from-epel "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- If you use CentOS Stream, Almalinux, Rocky Linux, or related distributions, you can install `ansible` or Ansible collections from the community-maintained [EPEL](https://docs.fedoraproject.org/en-US/epel/) (Extra Packages for Enterprise Linux) repository: 1. [Enable the EPEL repository](https://docs.fedoraproject.org/en-US/epel/#_quickstart) . 2. Use the same `dnf` commands as for Fedora Linux. Contact the package maintainers by [filing a bug](https://bugzilla.redhat.com/enter_bug.cgi) against the `Fedora EPEL` product in Red Hat Bugzilla. Installing Ansible on OpenSUSE Tumbleweed/Leap[](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/installation_distros.html#installing-ansible-on-opensuse-tumbleweed-leap "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- OpenSUSE provides Ansible packages through the standard package manager. $ sudo zypper install ansible See the [OpenSUSE Support Portal](https://en.opensuse.org/Portal:Support) for additional help with Ansible on OpenSUSE. Installing Ansible on Ubuntu[](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/installation_distros.html#installing-ansible-on-ubuntu "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Ubuntu provides Ansible packages through a Personal Package Archive (PPA) that contains more recent versions than the standard repositories. Ubuntu builds are available [in a PPA here](https://launchpad.net/~ansible/+archive/ubuntu/ansible) . Configure the PPA on your system and install Ansible: $ sudo apt update $ sudo apt install software-properties-common $ sudo add-apt-repository \--yes \--update ppa:ansible/ansible $ sudo apt install ansible File any issues in [the PPA’s issue tracker](https://github.com/ansible-community/ppa/issues) . Installing Ansible on Debian[](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/installation_distros.html#installing-ansible-on-debian "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Debian users can choose between the standard repository or the Ubuntu PPA for more recent versions. While Ansible is available from the [main Debian repository](https://packages.debian.org/stable/ansible) , this version can be outdated. For a more recent version, Debian users can use the Ubuntu PPA according to the following table: | Debian | | Ubuntu | UBUNTU\_CODENAME | | --- | --- | --- | --- | | Debian 13 (Trixie) | \-> | Ubuntu 24.04 (Noble) | `noble` | | Debian 12 (Bookworm) | \-> | Ubuntu 22.04 (Jammy) | `jammy` | | Debian 11 (Bullseye) | \-> | Ubuntu 20.04 (Focal) | `focal` | The following example assumes that you already have `wget` and `gpg` installed. Add the repository and install Ansible. Set `UBUNTU_CODENAME=...` based on the table above (we use `jammy` in this example): $ UBUNTU\_CODENAME\=jammy $ wget \-O- "https://keyserver.ubuntu.com/pks/lookup?fingerprint=on&op=get&search=0x6125E2A8C77F2818FB7BD15B93C4A3FD7BB9C367" | sudo gpg \--dearmor \-o /usr/share/keyrings/ansible-archive-keyring.gpg $ echo "deb \[signed-by=/usr/share/keyrings/ansible-archive-keyring.gpg\] http://ppa.launchpad.net/ansible/ansible/ubuntu $UBUNTU\_CODENAME main" | sudo tee /etc/apt/sources.list.d/ansible.list $ sudo apt update && sudo apt install ansible Note Use double quotes around the keyserver URL and in the “echo deb” command like in the example above. These commands download the signing key and add an entry to apt’s sources pointing to the PPA. Previously, you may have used `apt-key add`. The `apt-key add` approach is now [deprecated](https://askubuntu.com/a/1307181) for security reasons (on Debian, Ubuntu, and elsewhere). As such, we do NOT add the key to `/etc/apt/trusted.gpg.d/` or to `/etc/apt/trusted.gpg` where the key would be allowed to sign releases from ANY repository. Installing Ansible on Arch Linux[](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/installation_distros.html#installing-ansible-on-arch-linux "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Arch Linux provides both the full Ansible package and ansible-core through the standard package repositories. Install the full `ansible` package: $ sudo pacman \-S ansible Install the minimal `ansible-core` package: $ sudo pacman \-S ansible-core Arch Linux repositories include several Ansible ecosystem packages as standalone packages that you can install alongside `ansible-core`. See the [Arch Linux Packages index](https://archlinux.org/packages/?sort=&q=ansible) for a complete list of Ansible packages in Arch Linux. Contact the package maintainers by [opening an issue](https://gitlab.archlinux.org/archlinux/packaging/packages) in the related package GitLab repository. Installing Ansible on Windows[](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/installation_distros.html#installing-ansible-on-windows "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You cannot use a Windows system for the Ansible control node. See [Using Windows as the control node](https://docs.ansible.com/projects/ansible-core/devel/os_guide/intro_windows.html#windows-control-node) See also [Installing Ansible on Arch Linux](https://wiki.archlinux.org/title/Ansible#Installation) Distro-specific installation on Arch Linux [Installing Ansible on Clear Linux](https://clearlinux.org/software/bundle/ansible) Distro-specific installation on Clear Linux --- # Testing Strategies — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * Testing Strategies * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/reference_appendices/test_strategies.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Testing Strategies[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/test_strategies.html#testing-strategies "Link to this heading") ================================================================================================================================================================ Integrating Testing With Ansible Playbooks[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/test_strategies.html#integrating-testing-with-ansible-playbooks "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Many times, people ask, “how can I best integrate testing with Ansible playbooks?” There are many options. Ansible is actually designed to be a “fail-fast” and ordered system, therefore it makes it easy to embed testing directly in Ansible playbooks. In this chapter, we’ll go into some patterns for integrating tests of infrastructure and discuss the right level of testing that may be appropriate. Note This is a chapter about testing the application you are deploying, not the chapter on how to test Ansible modules during development. For that content, please hop over to the Development section. By incorporating a degree of testing into your deployment workflow, there will be fewer surprises when code hits production and, in many cases, tests can be used in production to prevent failed updates from migrating across an entire installation. Since it is push-based, it is also very easy to run the steps on the localhost or testing servers. Ansible lets you insert as many checks and balances into your upgrade workflow as you would like to have. The Right Level of Testing[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/test_strategies.html#the-right-level-of-testing "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Ansible resources are models of desired-state. As such, it should not be necessary to test that services are started, packages are installed, or other such things. Ansible is the system that will ensure these things are declaratively true. Instead, assert these things in your playbooks. tasks: \- ansible.builtin.service: name: foo state: started enabled: true If you think the service may not be started, the best thing to do is request it to be started. If the service fails to start, Ansible will yell appropriately. (This should not be confused with whether the service is doing something functional, which we’ll show more about how to do later). Check Mode As A Drift Test[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/test_strategies.html#check-mode-as-a-drift-test "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- In the above setup, `--check` mode in Ansible can be used as a layer of testing as well. If running a deployment playbook against an existing system, using the `--check` flag to the ansible command will report if Ansible thinks it would have had to have made any changes to bring the system into a desired state. This can let you know up front if there is any need to deploy onto the given system. Ordinarily, scripts and commands don’t run in check mode, so if you want certain steps to execute in normal mode even when the `--check` flag is used, such as calls to the script module, disable check mode for those tasks: roles: \- webserver tasks: \- ansible.builtin.script: verify.sh check\_mode: false Modules That Are Useful for Testing[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/test_strategies.html#modules-that-are-useful-for-testing "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Certain playbook modules are particularly good for testing. Below is an example that ensures a port is open: tasks: \- ansible.builtin.wait\_for: host: "{{ inventory\_hostname }}" port: 22 delegate\_to: localhost Here’s an example of using the URI module to make sure a web service returns: tasks: \- action: uri url=https://www.example.com return\_content=yes register: webpage \- fail: msg: 'service is not happy' when: "'AWESOME' not in webpage.content" It is easy to push an arbitrary script (in any language) on a remote host and the script will automatically fail if it has a non-zero return code: tasks: \- ansible.builtin.script: test\_script1 \- ansible.builtin.script: test\_script2 --parameter value --parameter2 value If using roles (you should be, roles are great!), scripts pushed by the script module can live in the ‘files/’ directory of a role. And the assert module makes it very easy to validate various kinds of truth: tasks: \- ansible.builtin.shell: /usr/bin/some-command --parameter value register: cmd\_result \- ansible.builtin.assert: that: \- "'not ready' not in cmd\_result.stderr" \- "'gizmo enabled' in cmd\_result.stdout" Should you feel the need to test for the existence of files that are not declaratively set by your Ansible configuration, the ‘stat’ module is a great choice: tasks: \- ansible.builtin.stat: path: /path/to/something register: p \- ansible.builtin.assert: that: \- p.stat.exists and p.stat.isdir As mentioned above, there’s no need to check things like the return codes of commands. Ansible is checking them automatically. Rather than checking for a user to exist, consider using the user module to make it exist. Ansible is a fail-fast system, so when there is an error creating that user, it will stop the playbook run. You do not have to check up behind it. Testing Lifecycle[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/test_strategies.html#testing-lifecycle "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------- If writing some degree of basic validation of your application into your playbooks, they will run every time you deploy. As such, deploying into a local development VM and a staging environment will both validate that things are according to plan ahead of your production deploy. Your workflow may be something like this: \- Use the same playbook all the time with embedded tests in development - Use the playbook to deploy to a staging environment (with the same playbooks) that simulates production - Run an integration test battery written by your QA team against staging - Deploy to production, with the same integrated tests. Something like an integration test battery should be written by your QA team if you are a production webservice. This would include things like Selenium tests or automated API tests and would usually not be something embedded into your Ansible playbooks. However, it does make sense to include some basic health checks into your playbooks, and in some cases it may be possible to run a subset of the QA battery against remote nodes. This is what the next section covers. Integrating Testing With Rolling Updates[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/test_strategies.html#integrating-testing-with-rolling-updates "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ If you have read into [Controlling where tasks run: delegation and local actions](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_delegation.html#playbooks-delegation) it may quickly become apparent that the rolling update pattern can be extended, and you can use the success or failure of the playbook run to decide whether to add a machine into a load balancer or not. This is the great culmination of embedded tests: \--- \- hosts: webservers serial: 5 pre\_tasks: \- name: take out of load balancer pool ansible.builtin.command: /usr/bin/take\_out\_of\_pool {{ inventory\_hostname }} delegate\_to: 127.0.0.1 tasks: \- ansible.builtin.include\_role: name: "{{ item }}" loop: \- common \- webserver \- name: run any notified handlers ansible.builtin.meta: flush\_handlers \- name: test the configuration ansible.builtin.include\_role: name: apply\_testing\_checks post\_tasks: \- name: add back to load balancer pool ansible.builtin.command: /usr/bin/add\_back\_to\_pool {{ inventory\_hostname }} delegate\_to: 127.0.0.1 Of course in the above, the “take out of the pool” and “add back” steps would be replaced with a call to an Ansible load balancer module or appropriate shell command. You might also have steps that use a monitoring module to start and end an outage window for the machine. However, what you can see from the above is that tests are used as a gate – if the “apply\_testing\_checks” step is not performed, the machine will not go back into the pool. Read the delegation chapter about “max\_fail\_percentage” and you can also control how many failing tests will stop a rolling update from proceeding. This above approach can also be modified to run a step from a testing machine remotely against a machine: \--- \- hosts: webservers serial: 5 pre\_tasks: \- name: take out of load balancer pool ansible.builtin.command: /usr/bin/take\_out\_of\_pool {{ inventory\_hostname }} delegate\_to: 127.0.0.1 roles: \- common \- webserver tasks: \- ansible.builtin.script: /srv/qa\_team/app\_testing\_script.sh --server {{ inventory\_hostname }} delegate\_to: testing\_server post\_tasks: \- name: add back to load balancer pool ansible.builtin.command: /usr/bin/add\_back\_to\_pool {{ inventory\_hostname }} delegate\_to: 127.0.0.1 In the above example, a script is run from the testing server against a remote node prior to bringing it back into the pool. In the event of a problem, fix the few servers that fail using Ansible’s automatically generated retry file to repeat the deploy on just those servers. Achieving Continuous Deployment[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/test_strategies.html#achieving-continuous-deployment "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ If desired, the above techniques may be extended to enable continuous deployment practices. The workflow may look like this: \- Write and use automation to deploy local development VMs - Have a CI system like Jenkins deploy to a staging environment on every code change - The deploy job calls testing scripts to pass/fail a build on every deploy - If the deploy job succeeds, it runs the same deploy playbook against production inventory Some Ansible users use the above approach to deploy a half-dozen or dozen times an hour without taking all of their infrastructure offline. A culture of automated QA is vital if you wish to get to this level. If you are still doing a large amount of manual QA, you should still make the decision on whether to deploy manually as well, but it can still help to work in the rolling update patterns of the previous section and incorporate some basic health checks using modules like ‘script’, ‘stat’, ‘uri’, and ‘assert’. Conclusion[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/test_strategies.html#conclusion "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------ Ansible believes you should not need another framework to validate basic things of your infrastructure is true. This is the case because Ansible is an order-based system that will fail immediately on unhandled errors for a host, and prevent further configuration of that host. This forces errors to the top and shows them in a summary at the end of the Ansible run. However, as Ansible is designed as a multi-tier orchestration system, it makes it very easy to incorporate tests into the end of a playbook run, either using loose tasks or roles. When used with rolling updates, testing steps can decide whether to put a machine back into a load balanced pool or not. Finally, because Ansible errors propagate all the way up to the return code of the Ansible program itself, and Ansible by default runs in an easy push-based mode, Ansible is a great step to put into a build environment if you wish to use it to roll out systems as part of a Continuous Integration/Continuous Delivery pipeline, as is covered in sections above. The focus should not be on infrastructure testing, but on application testing, so we strongly encourage getting together with your QA team and ask what sort of tests would make sense to run every time you deploy development VMs, and which sort of tests they would like to run against the staging environment on every deploy. Obviously at the development stage, unit tests are great too. But don’t unit test your playbook. Ansible describes states of resources declaratively, so you don’t have to. If there are cases where you want to be sure of something though, that’s great, and things like stat/assert are great go-to modules for that purpose. In all, testing is a very organizational and site-specific thing. Everybody should be doing it, but what makes the most sense for your environment will vary with what you are deploying and who is using it – but everyone benefits from a more robust and reliable deployment system. See also [Collection Index](https://docs.ansible.com/projects/ansible-core/devel/collections/index.html#list-of-collections) Browse existing collections, modules, and plugins [Working with playbooks](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks.html#working-with-playbooks) An introduction to playbooks [Controlling where tasks run: delegation and local actions](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_delegation.html#playbooks-delegation) Delegation, useful for working with load balancers, clouds, and locally executed steps. [Communication](https://docs.ansible.com/projects/ansible-core/devel/community/communication.html#communication) Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide --- # Building an inventory — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * [Getting started with Ansible](https://docs.ansible.com/projects/ansible-core/devel/getting_started/index.html) * Building an inventory * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/getting_started/get_started_inventory.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Building an inventory[](https://docs.ansible.com/projects/ansible-core/devel/getting_started/get_started_inventory.html#building-an-inventory "Link to this heading") ======================================================================================================================================================================= Inventories organize managed nodes in centralized files that provide Ansible with system information and network locations. Using an inventory file, Ansible can manage a large number of hosts with a single command. To complete the following steps, you will need the IP address or fully qualified domain name (FQDN) of at least one host system. For demonstration purposes, the host could be running locally in a container or a virtual machine. You must also ensure that your public SSH key is added to the `authorized_keys` file on each host. Continue getting started with Ansible and build an inventory as follows: 1. Create a file named `inventory.ini` in the `ansible_quickstart` directory that you created in the [preceding step](https://docs.ansible.com/projects/ansible-core/devel/getting_started/get_started_ansible.html#get-started-ansible) . 2. Add a new `[myhosts]` group to the `inventory.ini` file and specify the IP address or fully qualified domain name (FQDN) of each host system. \[myhosts\] 192.0.2.50 192.0.2.51 192.0.2.52 3. Verify your inventory. ansible-inventory \-i inventory.ini \--list 4. Ping the `myhosts` group in your inventory. ansible myhosts \-m ping \-i inventory.ini Note Pass the `-u` option with the `ansible` command if the username is different on the control node and the managed node(s). 192.0.2.50 | SUCCESS => { "ansible\_facts": { "discovered\_interpreter\_python": "/usr/bin/python3" }, "changed": false, "ping": "pong" } 192.0.2.51 | SUCCESS => { "ansible\_facts": { "discovered\_interpreter\_python": "/usr/bin/python3" }, "changed": false, "ping": "pong" } 192.0.2.52 | SUCCESS => { "ansible\_facts": { "discovered\_interpreter\_python": "/usr/bin/python3" }, "changed": false, "ping": "pong" } Congratulations, you have successfully built an inventory. Continue getting started with Ansible by [creating a playbook](https://docs.ansible.com/projects/ansible-core/devel/getting_started/get_started_playbook.html#get-started-playbook) . Inventories in INI or YAML format[](https://docs.ansible.com/projects/ansible-core/devel/getting_started/get_started_inventory.html#inventories-in-ini-or-yaml-format "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can create inventories in either `INI` files or in `YAML`. In most cases, such as the example in the preceding steps, `INI` files are straightforward and easy to read for a small number of managed nodes. Creating an inventory in `YAML` format becomes a sensible option as the number of managed nodes increases. For example, the following is an equivalent of the `inventory.ini` that declares unique names for managed nodes and uses the `ansible_host` field: myhosts: hosts: my\_host\_01: ansible\_host: 192.0.2.50 my\_host\_02: ansible\_host: 192.0.2.51 my\_host\_03: ansible\_host: 192.0.2.52 Tips for building inventories[](https://docs.ansible.com/projects/ansible-core/devel/getting_started/get_started_inventory.html#tips-for-building-inventories "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * Ensure that group names are meaningful and unique. Group names are also case sensitive. * Avoid spaces, hyphens, and preceding numbers (use `floor_19`, not `19th_floor`) in group names. * Group hosts in your inventory logically according to their **What**, **Where**, and **When**. What Group hosts according to the topology, for example: db, web, leaf, spine. Where Group hosts by geographic location, for example: datacenter, region, floor, building. When Group hosts by stage, for example: development, test, staging, production. ### Use metagroups[](https://docs.ansible.com/projects/ansible-core/devel/getting_started/get_started_inventory.html#use-metagroups "Link to this heading") Create a metagroup that organizes multiple groups in your inventory with the following syntax: metagroupname: children: The following inventory illustrates a basic structure for a data center. This example inventory contains a `network` metagroup that includes all network devices and a `datacenter` metagroup that includes the `network` group and all webservers. leafs: hosts: leaf01: ansible\_host: 192.0.2.100 leaf02: ansible\_host: 192.0.2.110 spines: hosts: spine01: ansible\_host: 192.0.2.120 spine02: ansible\_host: 192.0.2.130 network: children: leafs: spines: webservers: hosts: webserver01: ansible\_host: 192.0.2.140 webserver02: ansible\_host: 192.0.2.150 datacenter: children: network: webservers: ### Create variables[](https://docs.ansible.com/projects/ansible-core/devel/getting_started/get_started_inventory.html#create-variables "Link to this heading") Variables set values for managed nodes, such as the IP address, FQDN, operating system, and SSH user, so you do not need to pass them when running Ansible commands. Variables can apply to specific hosts. webservers: hosts: webserver01: ansible\_host: 192.0.2.140 http\_port: 80 webserver02: ansible\_host: 192.0.2.150 http\_port: 443 Variables can also apply to all hosts in a group. webservers: hosts: webserver01: ansible\_host: 192.0.2.140 http\_port: 80 webserver02: ansible\_host: 192.0.2.150 http\_port: 443 vars: ansible\_user: my\_server\_user See also [How to build your inventory](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#intro-inventory) Learn more about inventories in `YAML` or `INI` format. [Adding variables to inventory](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#variables-in-inventory) Find out more about inventory variables and their syntax. [Ansible Vault](https://docs.ansible.com/projects/ansible-core/devel/vault_guide/vault.html#vault) Find out how to encrypt sensitive content in your inventory such as passwords and keys. --- # Playbook Keywords — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * Playbook Keywords * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/templates/playbooks_keywords.rst.j2?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Playbook Keywords[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/playbooks_keywords.html#playbook-keywords "Link to this heading") ================================================================================================================================================================= These are the keywords available on common playbook objects. Keywords are one of several sources for configuring Ansible behavior. See [Controlling how Ansible behaves: precedence rules](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/general_precedence.html#general-precedence-rules) for details on the relative precedence of each source. Note Please note: * Aliases for the directives are not reflected here, nor are mutable ones. For example, [action](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Action) in task can be substituted by the name of any Ansible module. * The keywords do not have `version_added` information at this time * Some keywords set defaults for the objects inside of them rather than for the objects themselves [Play](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/playbooks_keywords.html#id2) [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/playbooks_keywords.html#play "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- > any\_errors\_fatal > > Force any un-handled task errors on any host to propagate to all hosts and end the play. > > become > > Boolean that controls if privilege escalation is used or not on [Task](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Task) > execution. Implemented by the become plugin. See [Become plugins](https://docs.ansible.com/projects/ansible-core/devel/plugins/become.html#become-plugins) > . > > become\_exe > > Path to the executable used to elevate privileges. Implemented by the become plugin. See [Become plugins](https://docs.ansible.com/projects/ansible-core/devel/plugins/become.html#become-plugins) > . > > become\_flags > > A string of flag(s) to pass to the privilege escalation program when [become](https://docs.ansible.com/projects/ansible/2.9/reference_appendices/playbooks_keywords.html#term-50 "(in Ansible v2.9)") > is True. > > become\_method > > Which method of privilege escalation to use (such as sudo or su). > > become\_user > > User that you ‘become’ after using privilege escalation. The remote/login user must have permissions to become this user. > > check\_mode > > A boolean that controls if a task is run normally or avoids changes to the target and tries to report what it would have done (check mode/dry run). See [Validating tasks: check mode and diff mode](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_checkmode.html#check-mode-dry) > . > > collections > > List of collection namespaces to search for modules, plugins, and roles. See [Using collections in a playbook](https://docs.ansible.com/projects/ansible-core/devel/collections_guide/collections_using_playbooks.html#collections-using-playbook) > > Note > > Tasks within a role do not inherit the value of `collections` from the play. To have a role search a list of collections, use the `collections` keyword in `meta/main.yml` within a role. > > connection > > Allows you to change the connection plugin used for tasks to execute on the target. See [Using connection plugins](https://docs.ansible.com/projects/ansible-core/devel/plugins/connection.html#using-connection) > . > > debugger > > Enable debugging tasks based on the state of the task result. See [Debugging tasks](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_debugger.html#playbook-debugger) > . > > diff > > Toggle to make tasks return ‘diff’ information or not. > > environment > > A dictionary that gets converted into environment vars to be provided for the task upon execution. This can ONLY be used with modules. This is not supported for any other type of plugins nor Ansible itself nor its configuration, it just sets the variables for the code responsible for executing the task. This is not a recommended way to pass in confidential data. > > fact\_path > > Set the fact path option for the fact gathering plugin controlled by [gather\_facts](https://docs.ansible.com/projects/ansible/2.9/reference_appendices/playbooks_keywords.html#term-gather_facts "(in Ansible v2.9)") > . > > force\_handlers > > Will force notified handler execution for hosts even if they failed during the play. Will not trigger if the play itself fails. > > gather\_facts > > A boolean that controls if the play will automatically run the ‘setup’ task to gather facts for the hosts. > > gather\_subset > > Allows you to pass subset options to the fact gathering plugin controlled by [gather\_facts](https://docs.ansible.com/projects/ansible/2.9/reference_appendices/playbooks_keywords.html#term-gather_facts "(in Ansible v2.9)") > . > > gather\_timeout > > Allows you to set the timeout for the fact gathering plugin controlled by [gather\_facts](https://docs.ansible.com/projects/ansible/2.9/reference_appendices/playbooks_keywords.html#term-gather_facts "(in Ansible v2.9)") > . > > handlers > > A section with tasks that are treated as handlers, these won’t get executed normally, only when notified after each section of tasks is complete. A handler’s listen field is not templatable. > > hosts > > A list of groups, hosts or host pattern that translates into a list of hosts that are the play’s target. > > ignore\_errors > > Boolean that allows you to ignore task failures and continue with play. It does not affect connection errors. > > ignore\_unreachable > > Boolean that allows you to ignore task failures due to an unreachable host and continue with the play. This does not affect other task errors (see [ignore\_errors](https://docs.ansible.com/projects/ansible/2.9/reference_appendices/playbooks_keywords.html#term-63 "(in Ansible v2.9)") > ) but is useful for groups of volatile/ephemeral hosts. > > max\_fail\_percentage > > can be used to abort the run after a given percentage of hosts in the current batch has failed. This only works on linear or linear-derived strategies. > > module\_defaults > > Specifies default parameter values for modules. > > name > > Identifier. Can be used for documentation, or in tasks/handlers. > > no\_log > > Boolean that controls information disclosure. > > order > > Controls the sorting of hosts as they are used for executing the play. Possible values are inventory (default), sorted, reverse\_sorted, reverse\_inventory and shuffle. > > port > > Used to override the default port used in a connection. > > post\_tasks > > A list of tasks to execute after the [tasks](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Tasks) > section. > > pre\_tasks > > A list of tasks to execute before [roles](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Roles) > . > > remote\_user > > User used to log into the target via the connection plugin. > > roles > > List of roles to be imported into the play > > run\_once > > Boolean that will bypass the host loop, forcing the task to attempt to execute on the first host available and afterward apply any results and facts to all active hosts in the same batch. > > serial > > Explicitly define how Ansible batches the execution of the current play on the play’s target. See [Setting the batch size with serial](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_strategies.html#rolling-update-batch-size) > . > > strategy > > Allows you to choose the strategy plugin to use for the play. See [Strategy plugins](https://docs.ansible.com/projects/ansible-core/devel/plugins/strategy.html#strategy-plugins) > . > > tags > > Tags applied to the task or included tasks, this allows selecting subsets of tasks from the command line. > > tasks > > Main list of tasks to execute in the play, they run after [roles](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Roles) > and before [post\_tasks](https://docs.ansible.com/projects/ansible/2.9/reference_appendices/playbooks_keywords.html#term-post_tasks "(in Ansible v2.9)") > . > > throttle > > Limit the number of concurrent task runs on task, block and playbook level. This is independent of the forks and serial settings, but cannot be set higher than those limits. For example, if forks is set to 10 and the throttle is set to 15, at most 10 hosts will be operated on in parallel. > > timeout > > Time limit for the task action to execute in, if exceeded, Ansible will interrupt the process. Timeout does not include templating or looping. > > validate\_argspec > > UNDOCUMENTED!! > > vars > > Dictionary/map of variables > > vars\_files > > List of files that contain vars to include in the play. > > vars\_prompt > > list of variables to prompt for. [Role](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/playbooks_keywords.html#id3) [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/playbooks_keywords.html#role "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- > any\_errors\_fatal > > Force any un-handled task errors on any host to propagate to all hosts and end the play. > > become > > Boolean that controls if privilege escalation is used or not on [Task](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Task) > execution. Implemented by the become plugin. See [Become plugins](https://docs.ansible.com/projects/ansible-core/devel/plugins/become.html#become-plugins) > . > > become\_exe > > Path to the executable used to elevate privileges. Implemented by the become plugin. See [Become plugins](https://docs.ansible.com/projects/ansible-core/devel/plugins/become.html#become-plugins) > . > > become\_flags > > A string of flag(s) to pass to the privilege escalation program when [become](https://docs.ansible.com/projects/ansible/2.9/reference_appendices/playbooks_keywords.html#term-50 "(in Ansible v2.9)") > is True. > > become\_method > > Which method of privilege escalation to use (such as sudo or su). > > become\_user > > User that you ‘become’ after using privilege escalation. The remote/login user must have permissions to become this user. > > check\_mode > > A boolean that controls if a task is run normally or avoids changes to the target and tries to report what it would have done (check mode/dry run). See [Validating tasks: check mode and diff mode](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_checkmode.html#check-mode-dry) > . > > collections > > List of collection namespaces to search for modules, plugins, and roles. See [Using collections in a playbook](https://docs.ansible.com/projects/ansible-core/devel/collections_guide/collections_using_playbooks.html#collections-using-playbook) > > Note > > Tasks within a role do not inherit the value of `collections` from the play. To have a role search a list of collections, use the `collections` keyword in `meta/main.yml` within a role. > > connection > > Allows you to change the connection plugin used for tasks to execute on the target. See [Using connection plugins](https://docs.ansible.com/projects/ansible-core/devel/plugins/connection.html#using-connection) > . > > debugger > > Enable debugging tasks based on the state of the task result. See [Debugging tasks](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_debugger.html#playbook-debugger) > . > > delegate\_facts > > Boolean that allows you to apply facts to a delegated host instead of inventory\_hostname. > > delegate\_to > > Host to execute task instead of the target (inventory\_hostname). Connection vars from the delegated host will also be used for the task. > > diff > > Toggle to make tasks return ‘diff’ information or not. > > environment > > A dictionary that gets converted into environment vars to be provided for the task upon execution. This can ONLY be used with modules. This is not supported for any other type of plugins nor Ansible itself nor its configuration, it just sets the variables for the code responsible for executing the task. This is not a recommended way to pass in confidential data. > > ignore\_errors > > Boolean that allows you to ignore task failures and continue with play. It does not affect connection errors. > > ignore\_unreachable > > Boolean that allows you to ignore task failures due to an unreachable host and continue with the play. This does not affect other task errors (see [ignore\_errors](https://docs.ansible.com/projects/ansible/2.9/reference_appendices/playbooks_keywords.html#term-63 "(in Ansible v2.9)") > ) but is useful for groups of volatile/ephemeral hosts. > > module\_defaults > > Specifies default parameter values for modules. > > name > > Identifier. Can be used for documentation, or in tasks/handlers. > > no\_log > > Boolean that controls information disclosure. > > port > > Used to override the default port used in a connection. > > remote\_user > > User used to log into the target via the connection plugin. > > run\_once > > Boolean that will bypass the host loop, forcing the task to attempt to execute on the first host available and afterward apply any results and facts to all active hosts in the same batch. > > tags > > Tags applied to the task or included tasks, this allows selecting subsets of tasks from the command line. > > throttle > > Limit the number of concurrent task runs on task, block and playbook level. This is independent of the forks and serial settings, but cannot be set higher than those limits. For example, if forks is set to 10 and the throttle is set to 15, at most 10 hosts will be operated on in parallel. > > timeout > > Time limit for the task action to execute in, if exceeded, Ansible will interrupt the process. Timeout does not include templating or looping. > > vars > > Dictionary/map of variables > > when > > Conditional expression, determines if an iteration of a task is run or not. [Block](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/playbooks_keywords.html#id4) [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/playbooks_keywords.html#block "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- > always > > List of tasks, in a block, that execute no matter if there is an error in the block or not. > > any\_errors\_fatal > > Force any un-handled task errors on any host to propagate to all hosts and end the play. > > become > > Boolean that controls if privilege escalation is used or not on [Task](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Task) > execution. Implemented by the become plugin. See [Become plugins](https://docs.ansible.com/projects/ansible-core/devel/plugins/become.html#become-plugins) > . > > become\_exe > > Path to the executable used to elevate privileges. Implemented by the become plugin. See [Become plugins](https://docs.ansible.com/projects/ansible-core/devel/plugins/become.html#become-plugins) > . > > become\_flags > > A string of flag(s) to pass to the privilege escalation program when [become](https://docs.ansible.com/projects/ansible/2.9/reference_appendices/playbooks_keywords.html#term-50 "(in Ansible v2.9)") > is True. > > become\_method > > Which method of privilege escalation to use (such as sudo or su). > > become\_user > > User that you ‘become’ after using privilege escalation. The remote/login user must have permissions to become this user. > > block > > List of tasks in a block. > > check\_mode > > A boolean that controls if a task is run normally or avoids changes to the target and tries to report what it would have done (check mode/dry run). See [Validating tasks: check mode and diff mode](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_checkmode.html#check-mode-dry) > . > > collections > > List of collection namespaces to search for modules, plugins, and roles. See [Using collections in a playbook](https://docs.ansible.com/projects/ansible-core/devel/collections_guide/collections_using_playbooks.html#collections-using-playbook) > > Note > > Tasks within a role do not inherit the value of `collections` from the play. To have a role search a list of collections, use the `collections` keyword in `meta/main.yml` within a role. > > connection > > Allows you to change the connection plugin used for tasks to execute on the target. See [Using connection plugins](https://docs.ansible.com/projects/ansible-core/devel/plugins/connection.html#using-connection) > . > > debugger > > Enable debugging tasks based on the state of the task result. See [Debugging tasks](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_debugger.html#playbook-debugger) > . > > delegate\_facts > > Boolean that allows you to apply facts to a delegated host instead of inventory\_hostname. > > delegate\_to > > Host to execute task instead of the target (inventory\_hostname). Connection vars from the delegated host will also be used for the task. > > diff > > Toggle to make tasks return ‘diff’ information or not. > > environment > > A dictionary that gets converted into environment vars to be provided for the task upon execution. This can ONLY be used with modules. This is not supported for any other type of plugins nor Ansible itself nor its configuration, it just sets the variables for the code responsible for executing the task. This is not a recommended way to pass in confidential data. > > ignore\_errors > > Boolean that allows you to ignore task failures and continue with play. It does not affect connection errors. > > ignore\_unreachable > > Boolean that allows you to ignore task failures due to an unreachable host and continue with the play. This does not affect other task errors (see [ignore\_errors](https://docs.ansible.com/projects/ansible/2.9/reference_appendices/playbooks_keywords.html#term-63 "(in Ansible v2.9)") > ) but is useful for groups of volatile/ephemeral hosts. > > module\_defaults > > Specifies default parameter values for modules. > > name > > Identifier. Can be used for documentation, or in tasks/handlers. > > no\_log > > Boolean that controls information disclosure. > > notify > > List of handlers to notify when the task returns a ‘changed=True’ status. > > port > > Used to override the default port used in a connection. > > remote\_user > > User used to log into the target via the connection plugin. > > rescue > > List of tasks in a [block](https://docs.ansible.com/projects/ansible/2.9/reference_appendices/playbooks_keywords.html#term-block "(in Ansible v2.9)") > that run if there is a task error in the main [block](https://docs.ansible.com/projects/ansible/2.9/reference_appendices/playbooks_keywords.html#term-block "(in Ansible v2.9)") > list. > > run\_once > > Boolean that will bypass the host loop, forcing the task to attempt to execute on the first host available and afterward apply any results and facts to all active hosts in the same batch. > > tags > > Tags applied to the task or included tasks, this allows selecting subsets of tasks from the command line. > > throttle > > Limit the number of concurrent task runs on task, block and playbook level. This is independent of the forks and serial settings, but cannot be set higher than those limits. For example, if forks is set to 10 and the throttle is set to 15, at most 10 hosts will be operated on in parallel. > > timeout > > Time limit for the task action to execute in, if exceeded, Ansible will interrupt the process. Timeout does not include templating or looping. > > vars > > Dictionary/map of variables > > when > > Conditional expression, determines if an iteration of a task is run or not. [Task](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/playbooks_keywords.html#id5) [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/playbooks_keywords.html#task "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- > action > > The ‘action’ to execute for a task, it normally translates into a C(module) or action plugin. > > any\_errors\_fatal > > Force any un-handled task errors on any host to propagate to all hosts and end the play. > > args > > A secondary way to add arguments into a task. Takes a dictionary in which keys map to options and values. > > async > > Run a task asynchronously if the C(action) supports this; the value is the maximum runtime in seconds. > > become > > Boolean that controls if privilege escalation is used or not on [Task](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Task) > execution. Implemented by the become plugin. See [Become plugins](https://docs.ansible.com/projects/ansible-core/devel/plugins/become.html#become-plugins) > . > > become\_exe > > Path to the executable used to elevate privileges. Implemented by the become plugin. See [Become plugins](https://docs.ansible.com/projects/ansible-core/devel/plugins/become.html#become-plugins) > . > > become\_flags > > A string of flag(s) to pass to the privilege escalation program when [become](https://docs.ansible.com/projects/ansible/2.9/reference_appendices/playbooks_keywords.html#term-50 "(in Ansible v2.9)") > is True. > > become\_method > > Which method of privilege escalation to use (such as sudo or su). > > become\_user > > User that you ‘become’ after using privilege escalation. The remote/login user must have permissions to become this user. > > changed\_when > > Conditional expression that overrides the task’s normal ‘changed’ status. > > check\_mode > > A boolean that controls if a task is run normally or avoids changes to the target and tries to report what it would have done (check mode/dry run). See [Validating tasks: check mode and diff mode](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_checkmode.html#check-mode-dry) > . > > collections > > List of collection namespaces to search for modules, plugins, and roles. See [Using collections in a playbook](https://docs.ansible.com/projects/ansible-core/devel/collections_guide/collections_using_playbooks.html#collections-using-playbook) > > Note > > Tasks within a role do not inherit the value of `collections` from the play. To have a role search a list of collections, use the `collections` keyword in `meta/main.yml` within a role. > > connection > > Allows you to change the connection plugin used for tasks to execute on the target. See [Using connection plugins](https://docs.ansible.com/projects/ansible-core/devel/plugins/connection.html#using-connection) > . > > debugger > > Enable debugging tasks based on the state of the task result. See [Debugging tasks](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_debugger.html#playbook-debugger) > . > > delay > > Number of seconds to delay between retries. This setting is only used in combination with [until](https://docs.ansible.com/projects/ansible/2.9/reference_appendices/playbooks_keywords.html#term-until "(in Ansible v2.9)") > . > > delegate\_facts > > Boolean that allows you to apply facts to a delegated host instead of inventory\_hostname. > > delegate\_to > > Host to execute task instead of the target (inventory\_hostname). Connection vars from the delegated host will also be used for the task. > > diff > > Toggle to make tasks return ‘diff’ information or not. > > environment > > A dictionary that gets converted into environment vars to be provided for the task upon execution. This can ONLY be used with modules. This is not supported for any other type of plugins nor Ansible itself nor its configuration, it just sets the variables for the code responsible for executing the task. This is not a recommended way to pass in confidential data. > > failed\_when > > Conditional expression that overrides the task’s normal ‘failed’ status. > > ignore\_errors > > Boolean that allows you to ignore task failures and continue with play. It does not affect connection errors. > > ignore\_unreachable > > Boolean that allows you to ignore task failures due to an unreachable host and continue with the play. This does not affect other task errors (see [ignore\_errors](https://docs.ansible.com/projects/ansible/2.9/reference_appendices/playbooks_keywords.html#term-63 "(in Ansible v2.9)") > ) but is useful for groups of volatile/ephemeral hosts. > > local\_action > > Same as action but also implies `delegate_to: localhost` > > loop > > Takes a list for the task to iterate over, saving each list element into the `item` variable (configurable via loop\_control) > > loop\_control > > Several keys here allow you to modify/set loop behavior in a task. See [Adding controls to loops](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_loops.html#loop-control) > . > > module\_defaults > > Specifies default parameter values for modules. > > name > > Identifier. Can be used for documentation, or in tasks/handlers. > > no\_log > > Boolean that controls information disclosure. > > notify > > List of handlers to notify when the task returns a ‘changed=True’ status. > > poll > > Sets the polling interval in seconds for async tasks (default 10s). > > port > > Used to override the default port used in a connection. > > register > > Name of variable that will contain task status and module return data. > > remote\_user > > User used to log into the target via the connection plugin. > > retries > > Number of retries before giving up in a [until](https://docs.ansible.com/projects/ansible/2.9/reference_appendices/playbooks_keywords.html#term-until "(in Ansible v2.9)") > loop. This setting is only used in combination with [until](https://docs.ansible.com/projects/ansible/2.9/reference_appendices/playbooks_keywords.html#term-until "(in Ansible v2.9)") > . > > run\_once > > Boolean that will bypass the host loop, forcing the task to attempt to execute on the first host available and afterward apply any results and facts to all active hosts in the same batch. > > tags > > Tags applied to the task or included tasks, this allows selecting subsets of tasks from the command line. > > throttle > > Limit the number of concurrent task runs on task, block and playbook level. This is independent of the forks and serial settings, but cannot be set higher than those limits. For example, if forks is set to 10 and the throttle is set to 15, at most 10 hosts will be operated on in parallel. > > timeout > > Time limit for the task action to execute in, if exceeded, Ansible will interrupt the process. Timeout does not include templating or looping. > > until > > This keyword implies a ‘[retries](https://docs.ansible.com/projects/ansible/2.9/reference_appendices/playbooks_keywords.html#term-retries "(in Ansible v2.9)") > loop’ that will go on until the condition supplied here is met or we hit the [retries](https://docs.ansible.com/projects/ansible/2.9/reference_appendices/playbooks_keywords.html#term-retries "(in Ansible v2.9)") > limit. > > vars > > Dictionary/map of variables > > when > > Conditional expression, determines if an iteration of a task is run or not. > > with\_ > > The same as `loop` but magically adds the output of any lookup plugin to generate the item list. --- # Galaxy User Guide — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * Galaxy User Guide * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/galaxy/user_guide.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Galaxy User Guide[](https://docs.ansible.com/projects/ansible-core/devel/galaxy/user_guide.html#galaxy-user-guide "Link to this heading") =========================================================================================================================================== _Ansible Galaxy_ refers to the [Galaxy](https://galaxy.ansible.com/) website, a free site for finding, downloading, and sharing community developed collections and roles. Use Galaxy to jump-start your automation project with great content from the Ansible community. Galaxy provides pre-packaged units of work such as [roles](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_reuse_roles.html#playbooks-reuse-roles) , and [collections](https://docs.ansible.com/projects/ansible-core/devel/collections_guide/index.html#collections) . The collection format provides a comprehensive package of automation that may include multiple playbooks, roles, modules, and plugins. See the [Galaxy documentation](https://ansible.readthedocs.io/projects/galaxy-ng/en/latest/) for full details on Galaxy. [Finding collections on Galaxy](https://docs.ansible.com/projects/ansible-core/devel/galaxy/user_guide.html#id1) [](https://docs.ansible.com/projects/ansible-core/devel/galaxy/user_guide.html#finding-collections-on-galaxy "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- To find collections on Galaxy: 1. Click Collections > Collections in the left-hand navigation. 2. Type in your search term. You can filter by keyword, tags, and namespaces. Galaxy presents a list of collections that match your search criteria. See [Using Ansible collections](https://docs.ansible.com/projects/ansible-core/devel/collections_guide/index.html#collections) for complete details on installing and using collections. [Finding roles on Galaxy](https://docs.ansible.com/projects/ansible-core/devel/galaxy/user_guide.html#id2) [](https://docs.ansible.com/projects/ansible-core/devel/galaxy/user_guide.html#finding-roles-on-galaxy "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- To find standalone roles (that is roles that are not part of a collection): 1. Click Roles > Roles in the left-hand navigation. 2. Type in your search term. You can filter by keyword, tags, and namespaces. Galaxy presents a list of roles that match your search criteria. You can optionally search the Galaxy database by tags, platforms, author and multiple keywords using the `ansible-galaxy` CLI command. $ ansible-galaxy role search elasticsearch \--author geerlingguy The search command will return a list of the first 1000 results matching your search: Found 6 roles matching your search: Name Description ---- ----------- geerlingguy.elasticsearch Elasticsearch for Linux. geerlingguy.elasticsearch-curator Elasticsearch curator for Linux. geerlingguy.filebeat Filebeat for Linux. geerlingguy.fluentd Fluentd for Linux. geerlingguy.kibana Kibana for Linux. ### [Get more information about a role](https://docs.ansible.com/projects/ansible-core/devel/galaxy/user_guide.html#id3) [](https://docs.ansible.com/projects/ansible-core/devel/galaxy/user_guide.html#get-more-information-about-a-role "Link to this heading") Use the `info` command to view more detail about a specific role: $ ansible-galaxy role info username.role\_name This returns everything found in Galaxy for the role: Role: username.role\_name description: Installs and configures a thing, a distributed, highly available NoSQL thing. active: True commit: c01947b7bc89ebc0b8a2e298b87ab416aed9dd57 commit\_message: Adding travis commit\_url: https://github.com/username/repo\_name/commit/c01947b7bc89ebc0b8a2e298b87ab company: My Company, Inc. created: 2015-12-08T14:17:52.773Z download\_count: 1 forks\_count: 0 github\_branch: main github\_repo: repo\_name github\_user: username id: 6381 is\_valid: True issue\_tracker\_url: license: Apache min\_ansible\_version: 2.15 modified: YYYY-MM-DDTHH:MM:SS.000Z namespace: username open\_issues\_count: 0 path: /Users/username/projects/roles role\_type: ANS stargazers\_count: 0 travis\_status\_url: https://travis-ci.org/username/repo\_name.svg?branch=main [Installing roles from Galaxy](https://docs.ansible.com/projects/ansible-core/devel/galaxy/user_guide.html#id4) [](https://docs.ansible.com/projects/ansible-core/devel/galaxy/user_guide.html#installing-roles-from-galaxy "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The `ansible-galaxy` command comes bundled with Ansible, and you can use it to install roles from Galaxy or directly from a Git based SCM. You can also use it to create a new role, remove roles, or perform tasks on the Galaxy website. The command line tool by default communicates with the Galaxy website API using the server address _https://galaxy.ansible.com_. If you run your own internal Galaxy server and want to use it instead of the default one, pass the `--server` option followed by the address of this galaxy server. You can set this option permanently by setting the Galaxy server value in your `ansible.cfg` file. See [GALAXY\_SERVER](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/config.html#galaxy-server) for details on setting the value in _ansible.cfg_ . ### [Installing roles](https://docs.ansible.com/projects/ansible-core/devel/galaxy/user_guide.html#id5) [](https://docs.ansible.com/projects/ansible-core/devel/galaxy/user_guide.html#installing-roles "Link to this heading") Use the `ansible-galaxy` command to download roles from the [Galaxy website](https://galaxy.ansible.com/) $ ansible-galaxy role install namespace.role\_name #### Setting where to install roles[](https://docs.ansible.com/projects/ansible-core/devel/galaxy/user_guide.html#setting-where-to-install-roles "Link to this heading") By default, Ansible downloads roles to the first writable directory in the default list of paths `~/.ansible/roles:/usr/share/ansible/roles:/etc/ansible/roles`. This installs roles in the home directory of the user running `ansible-galaxy`. You can override this with one of the following options: * Set the environment variable [`ANSIBLE_ROLES_PATH`](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/config.html#envvar-ANSIBLE_ROLES_PATH) in your session. * Use the `--roles-path` option for the `ansible-galaxy` command. * Define `roles_path` in an `ansible.cfg` file. The following provides an example of using `--roles-path` to install the role into the current working directory: $ ansible-galaxy role install \--roles-path . geerlingguy.apache See also [Configuring Ansible](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_configuration.html#intro-configuration) All about configuration files ### [Installing a specific version of a role](https://docs.ansible.com/projects/ansible-core/devel/galaxy/user_guide.html#id6) [](https://docs.ansible.com/projects/ansible-core/devel/galaxy/user_guide.html#installing-a-specific-version-of-a-role "Link to this heading") When the Galaxy server imports a role, it imports any Git tags matching the [Semantic Version](https://semver.org/) format as versions. In turn, you can download a specific version of a role by specifying one of the imported tags. To see the available versions for a role: 1. Locate the role on the Galaxy search page. 2. Click on the name to view more details, including the available versions. To install a specific version of a role from Galaxy, append a comma and the value of a GitHub release tag. For example: $ ansible-galaxy role install geerlingguy.apache,3.2.0 It is also possible to point directly to the Git repository and specify a branch name or commit hash as the version. For example, the following will install a specific commit: $ ansible-galaxy role install git+https://github.com/geerlingguy/ansible-role-apache.git,0b7cd353c0250e87a26e0499e59e7fd265cc2f25 ### [Installing multiple roles from a file](https://docs.ansible.com/projects/ansible-core/devel/galaxy/user_guide.html#id7) [](https://docs.ansible.com/projects/ansible-core/devel/galaxy/user_guide.html#installing-multiple-roles-from-a-file "Link to this heading") You can install multiple roles by including the roles in a `requirements.yml` file. The format of the file is YAML, and the file extension must be either _.yml_ or _.yaml_. Use the following command to install roles included in `requirements.yml:` $ ansible-galaxy install \-r requirements.yml Again, the extension is important. If the _.yml_ extension is left off, the `ansible-galaxy` CLI assumes the file is in an older, now deprecated, “basic” format. Each role in the file will have one or more of the following attributes: > src > > The source of the role. Use the format _namespace.role\_name_, if downloading from Galaxy; otherwise, provide a URL pointing to a repository within a Git based SCM. See the examples below. This is a required attribute. > > scm > > Specify the SCM. As of this writing only _git_ or _hg_ are allowed. See the examples below. Defaults to _git_. > > version: > > The version of the role to download. Provide a release tag value, commit hash, or branch name. Defaults to the branch set as a default in the repository, otherwise defaults to the _master_. > > name: > > Download the role to a specific name. Defaults to the Galaxy name when downloading from Galaxy, otherwise it defaults to the name of the repository. Use the following example as a guide for specifying roles in _requirements.yml_: \# from galaxy \- name: yatesr.timezone \# from locally cloned Git repository (git+file:// requires full paths) \- src: git+file:///home/bennojoy/nginx \# from GitHub \- src: https://github.com/bennojoy/nginx \# from GitHub, overriding the name and specifying a specific tag \- name: nginx\_role src: https://github.com/bennojoy/nginx version: main \# from GitHub, specifying a specific commit hash \- src: https://github.com/bennojoy/nginx version: "ee8aa41" \# from a webserver, where the role is packaged in a tar.gz \- name: http-role-gz src: https://some.webserver.example.com/files/main.tar.gz \# from a webserver, where the role is packaged in a tar.bz2 \- name: http-role-bz2 src: https://some.webserver.example.com/files/main.tar.bz2 \# from a webserver, where the role is packaged in a tar.xz (Python 3.x only) \- name: http-role-xz src: https://some.webserver.example.com/files/main.tar.xz \# from Bitbucket \- src: git+https://bitbucket.org/willthames/git-ansible-galaxy version: v1.4 \# from Bitbucket, alternative syntax and caveats \- src: https://bitbucket.org/willthames/hg-ansible-galaxy scm: hg \# from GitLab or other git-based scm, using git+ssh \- src: git@gitlab.company.com:mygroup/ansible-core.git scm: git version: "0.1" \# quoted, so YAML doesn't parse this as a floating-point value Warning Embedding credentials into a SCM URL 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..pushInsteadOf](https://git-scm.com/docs/git-config#Documentation/git-config.txt-urlltbasegtpushInsteadOf) in Git config to prevent your credentials from being exposed in logs. ### [Installing roles and collections from the same requirements.yml file](https://docs.ansible.com/projects/ansible-core/devel/galaxy/user_guide.html#id8) [](https://docs.ansible.com/projects/ansible-core/devel/galaxy/user_guide.html#installing-roles-and-collections-from-the-same-requirements-yml-file "Link to this heading") You can install roles and collections from the same requirements files \--- roles: \# Install a role from Ansible Galaxy. \- name: geerlingguy.java version: "1.9.6" \# note that ranges are not supported for roles collections: \# Install a collection from Ansible Galaxy. \- name: community.general version: ">=7.0.0" source: https://galaxy.ansible.com ### [Installing multiple roles from multiple files](https://docs.ansible.com/projects/ansible-core/devel/galaxy/user_guide.html#id9) [](https://docs.ansible.com/projects/ansible-core/devel/galaxy/user_guide.html#installing-multiple-roles-from-multiple-files "Link to this heading") For large projects, the `include` directive in a `requirements.yml` file provides the ability to split a large file into multiple smaller files. For example, a project may have a `requirements.yml` file, and a `webserver.yml` file. Below are the contents of the `webserver.yml` file: \# from github - src: https://github.com/bennojoy/nginx \# from Bitbucket - src: git+https://bitbucket.org/willthames/git-ansible-galaxy version: v1.4 The following shows the contents of the `requirements.yml` file that now includes the `webserver.yml` file: \# from galaxy - name: yatesr.timezone - include: /webserver.yml To install all the roles from both files, pass the root file, in this case `requirements.yml` on the command line, as follows: $ ansible-galaxy role install \-r requirements.yml ### [Dependencies](https://docs.ansible.com/projects/ansible-core/devel/galaxy/user_guide.html#id10) [](https://docs.ansible.com/projects/ansible-core/devel/galaxy/user_guide.html#dependencies "Link to this heading") Roles can also be dependent on other roles, and when you install a role that has dependencies, those dependencies will automatically be installed to the `roles_path`. There are two ways to define the dependencies of a role: * using `meta/requirements.yml` * using `meta/main.yml` #### Using `meta/requirements.yml`[](https://docs.ansible.com/projects/ansible-core/devel/galaxy/user_guide.html#using-meta-requirements-yml "Link to this heading") New in version 2.10. You can create the file `meta/requirements.yml` and define dependencies in the same format used for `requirements.yml` described in the [Installing multiple roles from a file](https://docs.ansible.com/projects/ansible-core/devel/galaxy/user_guide.html#installing-multiple-roles-from-a-file) section. From there, you can import or include the specified roles in your tasks. #### Using `meta/main.yml`[](https://docs.ansible.com/projects/ansible-core/devel/galaxy/user_guide.html#using-meta-main-yml "Link to this heading") Alternatively, you can specify role dependencies in the `meta/main.yml` file by providing a list of roles under the `dependencies` section. If the source of a role is Galaxy, you can simply specify the role in the format `namespace.role_name`. You can also use the more complex format in `requirements.yml`, allowing you to provide `src`, `scm`, `version`, and `name`. Dependencies installed that way, depending on other factors described below, will also be executed **before** this role is executed during play execution. To better understand how dependencies are handled during play execution, see [Roles](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_reuse_roles.html#playbooks-reuse-roles) . The following shows an example `meta/main.yml` file with dependent roles: \--- dependencies: \- geerlingguy.java galaxy\_info: author: geerlingguy description: Elasticsearch for Linux. company: "Midwestern Mac, LLC" license: "license (BSD, MIT)" min\_ansible\_version: 2.4 galaxy\_tags: \- web \- system \- monitoring \- logging \- lucene \- elk \- elasticsearch Tags are inherited _down_ the dependency chain. In order for tags to be applied to a role and all its dependencies, the tag should be applied to the role, not to all the tasks within a role. Roles listed as dependencies are subject to conditionals and tag filtering, and may not execute fully depending on what tags and conditionals are applied. If the source of a role is Galaxy, specify the role in the format _namespace.role\_name_: dependencies: \- geerlingguy.apache \- geerlingguy.ansible Alternately, you can specify the role dependencies in the complex form used in `requirements.yml` as follows: dependencies: \- name: geerlingguy.ansible \- name: composer src: git+https://github.com/geerlingguy/ansible-role-composer.git version: 775396299f2da1f519f0d8885022ca2d6ee80ee8 Note Galaxy expects all role dependencies to exist in Galaxy, and therefore dependencies to be specified in the `namespace.role_name` format. If you import a role with a dependency where the `src` value is a URL, the import process will fail. ### [List installed roles](https://docs.ansible.com/projects/ansible-core/devel/galaxy/user_guide.html#id11) [](https://docs.ansible.com/projects/ansible-core/devel/galaxy/user_guide.html#list-installed-roles "Link to this heading") Use `list` to show the name and version of each role installed in the _roles\_path_. $ ansible-galaxy role list \- namespace-1.foo, v2.7.2 \- namespace2.bar, v2.6.2 ### [Remove an installed role](https://docs.ansible.com/projects/ansible-core/devel/galaxy/user_guide.html#id12) [](https://docs.ansible.com/projects/ansible-core/devel/galaxy/user_guide.html#remove-an-installed-role "Link to this heading") Use `remove` to delete a role from _roles\_path_: $ ansible-galaxy role remove namespace.role\_name See also [Using Ansible collections](https://docs.ansible.com/projects/ansible-core/devel/collections_guide/index.html#collections) Shareable collections of modules, playbooks and roles [Roles](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_reuse_roles.html#playbooks-reuse-roles) Reusable tasks, handlers, and other files in a known directory structure [Working with command line tools](https://docs.ansible.com/projects/ansible-core/devel/command_guide/command_line_tools.html#command-line-tools) Perform other related operations --- # Legacy Public Cloud Guides — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * Legacy Public Cloud Guides * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/scenario_guides/cloud_guides.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Legacy Public Cloud Guides[](https://docs.ansible.com/projects/ansible/latest/scenario_guides/cloud_guides.html#legacy-public-cloud-guides "Link to this heading") ==================================================================================================================================================================== The legacy guides in this section may be out of date. They cover using Ansible with a range of public cloud platforms. They explore particular use cases in greater depth and provide a more “top-down” explanation of some basic features. Guides for using public clouds are moving into collections. We are migrating these guides into collections. Please update your links for the following guides: [Amazon Web Services Guide](https://docs.ansible.com/projects/ansible/latest/collections/amazon/aws/docsite/guide_aws.html#ansible-collections-amazon-aws-docsite-aws-intro) --- # Network Developer Guide — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * Network Developer Guide * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/network/dev_guide/index.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Network Developer Guide[](https://docs.ansible.com/projects/ansible/latest/network/dev_guide/index.html#network-developer-guide "Link to this heading") ========================================================================================================================================================= Welcome to the Developer Guide for Ansible Network Automation! **Who should use this guide?** If you want to extend Ansible for Network Automation by creating a module or plugin, this guide is for you. This guide is specific to networking. You should already be familiar with how to create, test, and document modules and plugins, as well as the prerequisites for getting your module or plugin accepted into the main Ansible repository. See the [Developer Guide](https://docs.ansible.com/projects/ansible/latest/dev_guide/index.html#developer-guide) for details. Before you proceed, please read: * How to [add a custom plugin or module locally](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_locally.html#developing-locally) . * How to figure out if [developing a module is the right approach](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules.html#module-dev-should-you) for my use case. * How to [set up my Python development environment](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_general.html#environment-setup) . * How to [get started writing a module](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_general.html#developing-modules-general) . Find the network developer task that best describes what you want to do: > * I want to [develop a network resource module](https://docs.ansible.com/projects/ansible/latest/network/dev_guide/developing_resource_modules_network.html#developing-resource-modules) > . > > * I want to [develop a network connection plugin](https://docs.ansible.com/projects/ansible/latest/network/dev_guide/developing_plugins_network.html#developing-plugins-network) > . > > * I want to [document my set of modules for a network platform](https://docs.ansible.com/projects/ansible/latest/network/dev_guide/documenting_modules_network.html#documenting-modules-network) > . > If you prefer to read the entire guide, here’s a list of the pages in order. * [Developing network resource modules](https://docs.ansible.com/projects/ansible/latest/network/dev_guide/developing_resource_modules_network.html) * [Developing network plugins](https://docs.ansible.com/projects/ansible/latest/network/dev_guide/developing_plugins_network.html) * [Documenting new network platforms](https://docs.ansible.com/projects/ansible/latest/network/dev_guide/documenting_modules_network.html) --- # Interpreter Discovery — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * Interpreter Discovery * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/reference_appendices/interpreter_discovery.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Interpreter Discovery[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/interpreter_discovery.html#interpreter-discovery "Link to this heading") ======================================================================================================================================================================== Most Ansible modules that execute under a POSIX environment require a Python interpreter on the target host. Unless configured otherwise, Ansible will attempt to discover a suitable Python interpreter on each target host the first time a Python module is executed for that host. To control the discovery behavior: * for individual hosts and groups, use the `ansible_python_interpreter` inventory variable * globally, use the `interpreter_python` key in the `[defaults]` section of `ansible.cfg` Configure a path to a specific Python interpreter, or one of the following values: auto (default) : Searches the configurable list of common Python interpreter paths (see [INTERPRETER\_PYTHON\_FALLBACK](https://docs.ansible.com/projects/ansible/latest/reference_appendices/config.html#interpreter-python-fallback) ) and issues a warning that future installation of another Python interpreter could alter the one chosen. auto\_legacy : Deprecated alias for `auto`. auto\_silent : Same as `auto`, but does not issue warnings. auto\_legacy\_silent : Deprecated alias for `auto_silent`. --- # Red Hat Ansible Automation Platform — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * Red Hat Ansible Automation Platform * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/reference_appendices/tower.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Red Hat Ansible Automation Platform[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/tower.html#red-hat-ansible-automation-platform "Link to this heading") ==================================================================================================================================================================================== Important Red Hat Ansible Automation Platform is available on multiple cloud platforms. See [Ansible on Clouds](https://access.redhat.com/documentation/en-us/ansible_on_clouds/2.x) for details. [Red Hat Ansible Automation Platform](https://www.ansible.com/products/automation-platform) (RHAAP) is an integrated solution for operationalizing Ansible across your team, organization, and enterprise. The platform includes a controller with a web console and REST API, analytics, Execution Environments, and much more. RHAAP gives you role-based access control, including control over the use of securely stored credentials for SSH and other services. You can sync your inventory with a wide variety of cloud sources, and powerful multi-playbook workflows allow you to model complex processes. RHAAP logs all of your jobs, integrates well with LDAP, SAML, and other authentication sources, and has an amazing browsable REST API. Command line tools are available for easy integration with Jenkins as well. RHAAP incorporates the downstream Red Hat supported product version of Ansible AWX, the downstream Red Hat supported product version of Ansible Galaxy, and multiple SaaS offerings. Find out more about RHAAP features and on the [Red Hat Ansible Automation Platform webpage](https://www.ansible.com/products/automation-platform) . A Red Hat Ansible Automation Platform subscription includes support from Red Hat, Inc. --- # Logging Ansible output — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * Logging Ansible output * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/reference_appendices/logging.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Logging Ansible output[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/logging.html#logging-ansible-output "Link to this heading") ============================================================================================================================================================ By default, Ansible sends output about plays, tasks, and module arguments to your screen (STDOUT) on the control node. If you want to capture Ansible output in a log, you have three options: * To save Ansible output in a single log on the control node, set the `log_path` [configuration file setting](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_configuration.html#intro-configuration) . You may also want to set `display_args_to_stdout`, which helps to differentiate similar tasks by including variable values in the Ansible output. * To save Ansible output in separate logs, one on each managed node, set the `no_target_syslog` and `syslog_facility` [configuration file settings](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_configuration.html#intro-configuration) . * To save Ansible output to a secure database, use AWX or [Red Hat Ansible Automation Platform](https://docs.ansible.com/projects/ansible/latest/reference_appendices/tower.html#ansible-platform) . You can then review history based on hosts, projects, and particular inventories over time, using graphs and/or a REST API. Protecting sensitive data with `no_log`[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/logging.html#protecting-sensitive-data-with-no-log "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- If you save Ansible output to a log, you expose any secret data in your Ansible output, such as passwords and usernames. To keep sensitive values out of your logs, mark tasks that expose them with the `no_log: True` attribute. However, the `no_log` attribute does not affect debugging output, so be careful not to debug playbooks in a production environment. See [How do I keep secret data in my playbook?](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#keep-secret-data) for an example. --- # Patterns: targeting hosts and groups — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * [Building Ansible inventories](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/index.html) * Patterns: targeting hosts and groups * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/inventory_guide/intro_patterns.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Patterns: targeting hosts and groups[](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_patterns.html#patterns-targeting-hosts-and-groups "Link to this heading") ============================================================================================================================================================================================= When you execute Ansible through an ad hoc command or by running a playbook, you must choose which managed nodes or groups you want to execute against. Patterns let you run commands and playbooks against specific hosts and/or groups in your inventory. An Ansible pattern can refer to a single host, an IP address, an inventory group, a set of groups, or all hosts in your inventory. Patterns are highly flexible - you can exclude or require subsets of hosts, use wildcards or regular expressions, and more. Ansible executes on all inventory hosts included in the pattern. [Using patterns](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_patterns.html#id2) [](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_patterns.html#using-patterns "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You use a pattern almost any time you execute an ad hoc command or a playbook. The pattern is the only element of an [ad hoc command](https://docs.ansible.com/projects/ansible-core/devel/command_guide/intro_adhoc.html#intro-adhoc) that has no flag. It is usually the second element: ansible \-m \-a "" For example: ansible webservers \-m service \-a "name=httpd state=restarted" In a playbook, the pattern is the content of the `hosts:` line for each play: \- name: hosts: For example: \- name: restart webservers hosts: webservers Since you often want to run a command or playbook against multiple hosts at once, patterns often refer to inventory groups. Both the ad hoc command and the playbook above will execute against all machines in the `webservers` group. [Common patterns](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_patterns.html#id3) [](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_patterns.html#common-patterns "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- This table lists common patterns for targeting inventory hosts and groups. | Description | Pattern(s) | Targets | | --- | --- | --- | | All hosts | all (or \*) | | | One host | host1 | | | Multiple hosts | host1:host2 (or host1,host2) | | | One group | webservers | | | Multiple groups | webservers:dbservers | all hosts in webservers plus all hosts in dbservers | | Excluding groups | webservers:!atlanta | all hosts in webservers except those in atlanta | | Intersection of groups | webservers:&staging | any hosts in webservers that are also in staging | Note You can use either a comma (`,`) or a colon (`:`) to separate a list of hosts. The comma is preferred when dealing with ranges and IPv6 addresses. Once you know the basic patterns, you can combine them. This example: webservers:dbservers:&staging:!phoenix targets all machines in the groups ‘webservers’ and ‘dbservers’ that are also in the group ‘staging’, except for any machines in the group ‘phoenix’. You can use wildcard patterns with FQDNs or IP addresses, as long as the hosts are named in your inventory by FQDN or IP address: 192.0.\* \*.example.com \*.com You can mix wildcard patterns and groups at the same time: one\*.com:dbservers [Limitations of patterns](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_patterns.html#id4) [](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_patterns.html#limitations-of-patterns "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Patterns depend on inventory. If a host or group is not listed in your inventory, you cannot use a pattern to target it. If your pattern includes an IP address or hostname that does not appear in your inventory, you will see an error like this: \[WARNING\]: No inventory was parsed, only implicit localhost is available \[WARNING\]: Could not match supplied host pattern, ignoring: \*.not\_in\_inventory.com Your pattern must match your inventory syntax. If you define a host as an [alias](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#inventory-aliases) : atlanta: hosts: host1: http\_port: 80 maxRequestsPerChild: 808 ansible\_host: 127.0.0.2 you must use the alias in your pattern. In the example above, you must use `host1` in your pattern. If you use the IP address, you will once again get the error: \[WARNING\]: Could not match supplied host pattern, ignoring: 127.0.0.2 [Pattern processing order](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_patterns.html#id5) [](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_patterns.html#pattern-processing-order "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The processing is a bit special and happens in the following order: 1. `:` and `,` 2. `&` 3. `!` This positioning only accounts for processing order inside each operation: `a:b:&c:!d:!e == &c:a:!d:b:!e == !d:a:!e:&c:b` All of these result in the following: Host in/is (a or b) AND host in/is all(c) AND host NOT in/is all(d, e). Now `a:b:!e:!d:&c` is a slight change as the `!e` gets processed before the `!d`, though this doesn’t make much of a difference: Host in/is (a or b) AND host in/is all(c) AND host NOT in/is all(e, d). [Advanced pattern options](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_patterns.html#id6) [](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_patterns.html#advanced-pattern-options "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The common patterns described above will meet most of your needs, but Ansible offers several other ways to define the hosts and groups you want to target. ### [Using variables in patterns](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_patterns.html#id7) [](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_patterns.html#using-variables-in-patterns "Link to this heading") You can use variables to enable passing group specifiers with the `-e` argument to ansible-playbook: webservers:!{{ excluded }}:&{{ required }} ### [Using group position in patterns](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_patterns.html#id8) [](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_patterns.html#using-group-position-in-patterns "Link to this heading") You can define a host or subset of hosts by its position in a group. For example, given the following group: \[webservers\] cobweb webbing weber you can use subscripts to select individual hosts or ranges within the webservers group. #### [Slicing at specific items](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_patterns.html#id9) [](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_patterns.html#slicing-at-specific-items "Link to this heading") * **Operation:** `s[i]` * **Result:** `i-th` item of `s` where the indexing origin is `0` If _i_ is negative, the index is relative to the end of sequence _s_: `len(s) + i` is substituted. However `-0` is `0`. webservers\[0\] \# == cobweb webservers\[\-1\] \# == weber #### [Slicing with start and end points](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_patterns.html#id10) [](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_patterns.html#slicing-with-start-and-end-points "Link to this heading") * **Operation:** `s[i:j]` * **Result:** slice of `s` from `i` to `j` The slice of _s_ from _i_ to _j_ is defined as the sequence of items with index _k_ such that `i <= k <= j`. If _i_ is omitted, use `0`. If _j_ is omitted, use `len(s)`. The slice omitting both _i_ and _j_, results in an invalid host pattern. If _i_ is greater than _j_, the slice is empty. If _i_ is equal to _j_, the _s\[i\]_ is substituted. webservers\[0:2\] \# == webservers\[0\],webservers\[1\],webservers\[2\] \# == cobweb,webbing,weber webservers\[1:2\] \# == webservers\[1\],webservers\[2\] \# == webbing,weber webservers\[1:\] \# == webbing,weber webservers\[:3\] \# == cobweb,webbing,weber ### [Using regexes in patterns](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_patterns.html#id11) [](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_patterns.html#using-regexes-in-patterns "Link to this heading") You can specify a pattern as a regular expression by starting the pattern with `~`: ~(web|db).\*\\.example\\.com [Patterns and ad-hoc commands](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_patterns.html#id12) [](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_patterns.html#patterns-and-ad-hoc-commands "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can change the behavior of the patterns defined in ad-hoc commands using command-line options. You can also limit the hosts you target on a particular run with the `--limit` flag. * Limit to one host $ ansible all \-m \-a "" \--limit "host1" * Limit to multiple hosts $ ansible all \-m \-a "" \--limit "host1,host2" * Negated limit. Note that single quotes MUST be used to prevent bash interpolation. $ ansible all \-m \-a "" \--limit 'all:!host1' * Limit to host group $ ansible all \-m \-a "" \--limit 'group1' [Patterns and ansible-playbook flags](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_patterns.html#id13) [](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_patterns.html#patterns-and-ansible-playbook-flags "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can change the behavior of the patterns defined in playbooks using command-line options. For example, you can run a playbook that defines `hosts: all` on a single host by specifying `-i 127.0.0.2,` (note the trailing comma). This works even if the host you target is not defined in your inventory, but this method will NOT read your inventory for variables tied to this host and any variables required by the playbook will need to be specified manually at the command line. You can also limit the hosts you target on a particular run with the `--limit` flag, which will reference your inventory: ansible-playbook site.yml \--limit datacenter2 Finally, you can use `--limit` to read the list of hosts from a file by prefixing the file name with `@`: ansible-playbook site.yml \--limit @retry\_hosts.txt If [RETRY\_FILES\_ENABLED](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/config.html#retry-files-enabled) is set to `True`, a `.retry` file will be created after the `ansible-playbook` run containing a list of failed hosts from all plays. This file is overwritten each time `ansible-playbook` finishes running. ansible-playbook site.yml \--limit @site.retry To apply your knowledge of patterns with Ansible commands and playbooks, read [Introduction to ad hoc commands](https://docs.ansible.com/projects/ansible-core/devel/command_guide/intro_adhoc.html#intro-adhoc) and [Ansible playbooks](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_intro.html#playbooks-intro) . See also [Introduction to ad hoc commands](https://docs.ansible.com/projects/ansible-core/devel/command_guide/intro_adhoc.html#intro-adhoc) Examples of basic commands [Working with playbooks](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks.html#working-with-playbooks) Learning the Ansible configuration management language [Communication](https://docs.ansible.com/projects/ansible-core/devel/community/communication.html#communication) Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide --- # Introduction to ad hoc commands — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * [Using Ansible command line tools](https://docs.ansible.com/projects/ansible-core/devel/command_guide/index.html) * Introduction to ad hoc commands * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/command_guide/intro_adhoc.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Introduction to ad hoc commands[](https://docs.ansible.com/projects/ansible-core/devel/command_guide/intro_adhoc.html#introduction-to-ad-hoc-commands "Link to this heading") =============================================================================================================================================================================== An Ansible ad hoc command uses the /usr/bin/ansible command-line tool to automate a single task on one or more managed nodes. ad hoc commands are quick and easy, but they are not reusable. So why learn about ad hoc commands? ad hoc commands demonstrate the simplicity and power of Ansible. The concepts you learn here will port over directly to the playbook language. Before reading and executing these examples, please read [How to build your inventory](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#intro-inventory) . [Why use ad hoc commands?](https://docs.ansible.com/projects/ansible-core/devel/command_guide/intro_adhoc.html#id4) [](https://docs.ansible.com/projects/ansible-core/devel/command_guide/intro_adhoc.html#why-use-ad-hoc-commands "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ ad hoc commands are great for tasks you repeat rarely. For example, if you want to power off all the machines in your lab when you go on vacation, you could execute a quick one-liner in Ansible without writing a playbook. An ad hoc command looks like this: $ ansible \[pattern\] \-m \[module\] \-a "\[module options\]" The `-a` option accepts options either through the `key=value` syntax or a JSON string starting with `{` and ending with `}` for more complex option structure. You can learn more about [patterns](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_patterns.html#intro-patterns) and [modules](https://docs.ansible.com/projects/ansible-core/devel/plugins/module.html#module-plugins) on other pages. [Use cases for ad hoc tasks](https://docs.ansible.com/projects/ansible-core/devel/command_guide/intro_adhoc.html#id5) [](https://docs.ansible.com/projects/ansible-core/devel/command_guide/intro_adhoc.html#use-cases-for-ad-hoc-tasks "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ad hoc tasks can be used to reboot servers, copy files, manage packages and users, and much more. You can use any Ansible module in an ad hoc task. ad hoc tasks, like playbooks, use a declarative model, calculating and executing the actions required to reach a specified final state. They achieve a form of idempotence by checking the current state before they begin and doing nothing unless the current state is different from the specified final state. ### [Rebooting servers](https://docs.ansible.com/projects/ansible-core/devel/command_guide/intro_adhoc.html#id6) [](https://docs.ansible.com/projects/ansible-core/devel/command_guide/intro_adhoc.html#rebooting-servers "Link to this heading") The default module for the `ansible` command-line utility is the [ansible.builtin.command module](https://docs.ansible.com/projects/ansible-core/devel/collections/ansible/builtin/command_module.html#command-module) . You can use an ad hoc task to call the command module and reboot all web servers in Atlanta, 10 at a time. Before Ansible can do this, you must have all servers in Atlanta listed in a group called \[atlanta\] in your inventory, and you must have working SSH credentials for each machine in that group. To reboot all the servers in the \[atlanta\] group: $ ansible atlanta \-a "/sbin/reboot" By default, Ansible uses only five simultaneous processes. If you have more hosts than the value set for the fork count, it can increase the time it takes for Ansible to communicate with the hosts. To reboot the \[atlanta\] servers with 10 parallel forks: $ ansible atlanta \-a "/sbin/reboot" \-f 10 /usr/bin/ansible will default to running from your user account. To connect as a different user: $ ansible atlanta \-a "/sbin/reboot" \-f 10 \-u username Rebooting probably requires privilege escalation. You can connect to the server as `username` and run the command as the `root` user by using the [become](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_privilege_escalation.html#become) keyword: $ ansible atlanta \-a "/sbin/reboot" \-f 10 \-u username \--become \[\--ask-become-pass\] If you add `--ask-become-pass` or `-K`, Ansible prompts you for the password to use for privilege escalation (sudo/su/pfexec/doas/etc). Note The [command module](https://docs.ansible.com/projects/ansible-core/devel/collections/ansible/builtin/command_module.html#command-module) does not support extended shell syntaxes like piping and redirects (although shell variables will always work). If your command requires shell-specific syntax, use the shell module instead. So far all our examples have used the default ‘command’ module. To use a different module, pass `-m` for module name. For example, to use the [ansible.builtin.shell module](https://docs.ansible.com/projects/ansible-core/devel/collections/ansible/builtin/shell_module.html#shell-module) : $ ansible raleigh \-m ansible.builtin.shell \-a 'echo $TERM' When running any command with the Ansible _ad hoc_ CLI (as opposed to [Playbooks](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks.html#working-with-playbooks) ), pay particular attention to shell quoting rules, so the local shell retains the variable and passes it to Ansible. For example, using double rather than single quotes in the above example would evaluate the variable on the box you were on. ### [Managing files](https://docs.ansible.com/projects/ansible-core/devel/command_guide/intro_adhoc.html#id7) [](https://docs.ansible.com/projects/ansible-core/devel/command_guide/intro_adhoc.html#managing-files "Link to this heading") An ad hoc task can harness the power of Ansible and SCP to transfer many files to multiple machines in parallel. To transfer a file directly to all servers in the \[atlanta\] group: $ ansible atlanta \-m ansible.builtin.copy \-a "src=/etc/hosts dest=/tmp/hosts" If you plan to repeat a task like this, use the [ansible.builtin.template](https://docs.ansible.com/projects/ansible-core/devel/collections/ansible/builtin/template_module.html#template-module) module in a playbook. The [ansible.builtin.file](https://docs.ansible.com/projects/ansible-core/devel/collections/ansible/builtin/file_module.html#file-module) module allows changing ownership and permissions on files. These same options can be passed directly to the `copy` module as well: $ ansible webservers \-m ansible.builtin.file \-a "dest=/srv/foo/a.txt mode=600" $ ansible webservers \-m ansible.builtin.file \-a "dest=/srv/foo/b.txt mode=600 owner=mdehaan group=mdehaan" The `file` module can also create directories, similar to `mkdir -p`: $ ansible webservers \-m ansible.builtin.file \-a "dest=/path/to/c mode=755 owner=mdehaan group=mdehaan state=directory" As well as delete directories (recursively) and delete files: $ ansible webservers \-m ansible.builtin.file \-a "dest=/path/to/c state=absent" ### [Managing packages](https://docs.ansible.com/projects/ansible-core/devel/command_guide/intro_adhoc.html#id8) [](https://docs.ansible.com/projects/ansible-core/devel/command_guide/intro_adhoc.html#managing-packages "Link to this heading") You might also use an ad hoc task to install, update, or remove packages on managed nodes using a package management module such as `yum`. Package management modules support common functions to install, remove, and generally manage packages. Some specific functions for a package manager might not be present in the Ansible module since they are not part of general package management. To ensure a package is installed without updating it: $ ansible webservers \-m ansible.builtin.yum \-a "name=acme state=present" To ensure a specific version of a package is installed: $ ansible webservers \-m ansible.builtin.yum \-a "name=acme-1.5 state=present" To ensure a package is at the latest version: $ ansible webservers \-m ansible.builtin.yum \-a "name=acme state=latest" To ensure a package is not installed: $ ansible webservers \-m ansible.builtin.yum \-a "name=acme state=absent" Ansible has modules for managing packages under many platforms. If there is no module for your package manager, you can install packages using the command module or create a module for your package manager. ### [Managing users and groups](https://docs.ansible.com/projects/ansible-core/devel/command_guide/intro_adhoc.html#id9) [](https://docs.ansible.com/projects/ansible-core/devel/command_guide/intro_adhoc.html#managing-users-and-groups "Link to this heading") You can create, manage, and remove user accounts on your managed nodes with ad hoc tasks: $ ansible all \-m ansible.builtin.user \-a "name=foo password=" $ ansible all \-m ansible.builtin.user \-a "name=foo state=absent" See the [ansible.builtin.user](https://docs.ansible.com/projects/ansible-core/devel/collections/ansible/builtin/user_module.html#user-module) module documentation for details on all of the available options, including how to manipulate groups and group membership. ### [Managing services](https://docs.ansible.com/projects/ansible-core/devel/command_guide/intro_adhoc.html#id10) [](https://docs.ansible.com/projects/ansible-core/devel/command_guide/intro_adhoc.html#managing-services "Link to this heading") Ensure a service is started on all webservers: $ ansible webservers \-m ansible.builtin.service \-a "name=httpd state=started" Alternatively, restart a service on all webservers: $ ansible webservers \-m ansible.builtin.service \-a "name=httpd state=restarted" Ensure a service is stopped: $ ansible webservers \-m ansible.builtin.service \-a "name=httpd state=stopped" ### [Gathering facts](https://docs.ansible.com/projects/ansible-core/devel/command_guide/intro_adhoc.html#id11) [](https://docs.ansible.com/projects/ansible-core/devel/command_guide/intro_adhoc.html#gathering-facts "Link to this heading") Facts represent discovered variables about a system. You can use facts to implement conditional execution of tasks but also just to get ad hoc information about your systems. To see all facts: $ ansible all \-m ansible.builtin.setup You can also filter this output to display only certain facts, see the [ansible.builtin.setup](https://docs.ansible.com/projects/ansible-core/devel/collections/ansible/builtin/setup_module.html#setup-module) module documentation for details. ### [Check mode](https://docs.ansible.com/projects/ansible-core/devel/command_guide/intro_adhoc.html#id12) [](https://docs.ansible.com/projects/ansible-core/devel/command_guide/intro_adhoc.html#check-mode "Link to this heading") In check mode, Ansible does not make any changes to remote systems. Ansible prints the commands only. It does not run the commands. $ ansible all \-m copy \-a "content=foo dest=/root/bar.txt" \-C Enabling check mode (`-C` or `--check`) in the above command means Ansible does not actually create or update the `/root/bar.txt` file on any remote systems. ### [Patterns and ad-hoc commands](https://docs.ansible.com/projects/ansible-core/devel/command_guide/intro_adhoc.html#id13) [](https://docs.ansible.com/projects/ansible-core/devel/command_guide/intro_adhoc.html#patterns-and-ad-hoc-commands "Link to this heading") See the [patterns](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_patterns.html#intro-patterns) documentation for details on all of the available options, including how to limit using patterns in ad-hoc commands. Now that you understand the basic elements of Ansible execution, you are ready to learn to automate repetitive tasks using [Ansible Playbooks](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_intro.html#playbooks-intro) . See also [Configuring Ansible](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_configuration.html#intro-configuration) All about the Ansible config file [Collection Index](https://docs.ansible.com/projects/ansible-core/devel/collections/index.html#list-of-collections) Browse existing collections, modules, and plugins [Working with playbooks](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks.html#working-with-playbooks) Using Ansible for configuration management & deployment [Communication](https://docs.ansible.com/projects/ansible-core/devel/community/communication.html#communication) Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide --- # Ansible documentation style guide — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * Ansible documentation style guide * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/dev_guide/style_guide/index.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Ansible documentation style guide[](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#ansible-documentation-style-guide "Link to this heading") ===================================================================================================================================================================================== Welcome to the Ansible style guide! To create clear, concise, consistent, useful materials on docs.ansible.com, follow these guidelines: [Linguistic guidelines](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#id3) [](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#linguistic-guidelines "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- We want the Ansible documentation to be: * clear * direct * conversational * easy to translate We want reading the docs to feel like having an experienced, friendly colleague explain how Ansible works. ### [Stylistic cheat-sheet](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#id4) [](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#stylistic-cheat-sheet "Link to this heading") This cheat-sheet illustrates a few rules that help achieve the “Ansible tone”: | Rule | Good example | Bad example | | --- | --- | --- | | Use active voice | You can run a task by | A task can be run by | | Use the present tense | This command creates a | This command will create a | | Address the reader | As you expand your inventory | When the number of managed nodes grows | | Use standard English | Return to this page | Hop back to this page | | Use American English | The color of the output | The colour of the output | ### [Title and heading case](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#id5) [](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#title-and-heading-case "Link to this heading") Titles and headings should be written in sentence case. For example, this section’s title is `Title and heading case`, not `Title and Heading Case` or `TITLE AND HEADING CASE`. ### [Avoid using Latin phrases](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#id6) [](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#avoid-using-latin-phrases "Link to this heading") 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. Use the following English terms in place of Latin terms or abbreviations: | Latin | English | | --- | --- | | i.e | in other words | | e.g. | for example | | etc | and so on | | via | by/ through | | vs./versus | rather than/against | [reStructuredText guidelines](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#id7) [](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#restructuredtext-guidelines "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The Ansible documentation is written in reStructuredText and processed by Sphinx. We follow these technical or mechanical guidelines on all rST pages: ### [Heading notation](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#id8) [](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#heading-notation "Link to this heading") [Section headings 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 headings. To make our documents easy to read and to edit, we follow a standard set of heading notations. We use: * `###` with overline, for parts: ############### Developer guide ############### * `***` with overline, for chapters: \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\* Ansible style guide \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\* * `===` for sections: Mechanical guidelines \===================== * `---` for subsections: Internal navigation \------------------- * `^^^` for sub-subsections: Adding anchors ^^^^^^^^^^^^^^ * `"""` for paragraphs: Paragraph that needs a title """""""""""""""""""""""""""" ### [Syntax highlighting - Pygments](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#id9) [](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#syntax-highlighting-pygments "Link to this heading") 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. The Ansible documentation allows the following values: * none (no highlighting) * ansible-output (a custom lexer for Ansible output) * bash * console * csharp * diff * ini * jinja * json * md * powershell * python * rst * sh * shell * shell-session * text * yaml * yaml+jinja For example, you can highlight Python code using following syntax: .. code-block:: python def my\_beautiful\_python\_code(): pass ### [Internal navigation](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#id10) [](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#internal-navigation "Link to this heading") [Anchors (also called labels) and links](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref) 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 headings, can also include a local TOC. Note Avoid raw URLs. RST and sphinx allow `https://my.example.com`, but this is unhelpful for those using screen readers. `:ref:` links automatically pick up the heading from the anchor, but for external links, always use the `` `link title `_ `` format. #### [Adding anchors](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#id11) [](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#adding-anchors "Link to this heading") * Include at least one anchor on every page * Place the main anchor above the main heading * If the file has a unique title, use that for the main page anchor: .. \_unique\_page:: * You may also add anchors elsewhere on the page #### [Adding internal links](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#id12) [](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#adding-internal-links "Link to this heading") * All internal links must use `:ref:` syntax. These links both point to the anchor defined above: :ref:\`unique\_page\` :ref:\`this page \` The second example adds custom text for the link. #### [Adding links to modules and plugins](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#id13) [](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#adding-links-to-modules-and-plugins "Link to this heading") Use the `:ansplugin:` RST role to link to modules and plugins using their Fully Qualified Collection Name (FQCN): The ansible.builtin.copy module can be linked with :ansplugin:\`ansible.builtin.copy#module\` If you want to specify an explicit type, use: :ansplugin:\`the copy module \` This displays as “The ansible.builtin.copy module can be linked with [ansible.builtin.copy](https://docs.ansible.com/projects/ansible-core/devel/collections/ansible/builtin/copy_module.html#ansible-collections-ansible-builtin-copy-module) ” and “If you want to specify an explicit type, use: [the copy module](https://docs.ansible.com/projects/ansible-core/devel/collections/ansible/builtin/copy_module.html#ansible-collections-ansible-builtin-copy-module) ”. Instead of `#module`, you can also specify `#` to reference to a plugin of type ``: :ansplugin:\`arista.eos.eos\_config \` :ansplugin:\`kubernetes.core.kubectl connection plugin \` :ansplugin:\`ansible.builtin.file lookup plugin \` Note `ansible.builtin` is the FQCN for modules included in ansible-core. #### [Adding links to module and plugin options and return values](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#id14) [](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#adding-links-to-module-and-plugin-options-and-return-values "Link to this heading") Use the `:ansopt:` and `:ansretval:` roles to reference options and return values of modules and plugins while showing the option’s resp. return value’s name and optionally a value. Use the `:ansoptref:` and `:ansretvalref:` roles to reference options and return values of modules and plugins while displaying a provided title. The following example shows their usage: :ansopt:\`ansible.builtin.file#module:path\` references the \`\`path\`\` parameter of the \`\`ansible.builtin.file\`\` module; :ansopt:\`ansible.builtin.file#module:path=/root/.ssh/known\_hosts\` shows the assignment \`\`path=/root/.ssh/known\_hosts\`\` as a clickable link. You can :ansoptref:\`provide a path \` to the :ansplugin:\`ansible.builtin.file#module\`; its value is :ansretvalref:\`returned as a return value \`. :ansretval:\`ansible.builtin.stat#module:stat.exists\` references the \`\`stat.exists\`\` return value of the \`\`ansible.builtin.stat\`\` module. You can also use \`\`=\`\` as for option values: :ansretval:\`ansible.builtin.stat#module:stat.exists=true\` shows \`\`stat.exists=true\`\`. :ansopt:\`foo\` and :ansopt:\`foo=bar\` use the same markup for an option and an option assignment without a link; the same is true for return values: :ansretval:\`foo\` and :ansretval:\`foo=bar\`. This displays as: > `**[path](https://docs.ansible.com/projects/ansible-core/devel/collections/ansible/builtin/file_module.html#ansible-collections-ansible-builtin-file-module-parameter-path) **` references the `path` parameter of the `ansible.builtin.file` module; `[path=/root/.ssh/known_hosts](https://docs.ansible.com/projects/ansible-core/devel/collections/ansible/builtin/file_module.html#ansible-collections-ansible-builtin-file-module-parameter-path) ` shows the assignment `path=/root/.ssh/known_hosts` as a clickable link. > > You can [provide a path](https://docs.ansible.com/projects/ansible-core/devel/collections/ansible/builtin/file_module.html#ansible-collections-ansible-builtin-file-module-parameter-path) > to the [ansible.builtin.file](https://docs.ansible.com/projects/ansible-core/devel/collections/ansible/builtin/file_module.html#ansible-collections-ansible-builtin-file-module) > ; its value is [returned as a return value](https://docs.ansible.com/projects/ansible-core/devel/collections/ansible/builtin/file_module.html#ansible-collections-ansible-builtin-file-module-return-path) > . > > `[stat.exists](https://docs.ansible.com/projects/ansible-core/devel/collections/ansible/builtin/stat_module.html#ansible-collections-ansible-builtin-stat-module-return-stat-exists) ` references the `stat.exists` return value of the `ansible.builtin.stat` module. You can also use `=` as for option values: `[stat.exists=true](https://docs.ansible.com/projects/ansible-core/devel/collections/ansible/builtin/stat_module.html#ansible-collections-ansible-builtin-stat-module-return-stat-exists) ` shows `stat.exists=true`. > > `**foo**` and `foo=bar` use the same markup for an option and an option assignment without a link; the same is true for return values: `foo` and `foo=bar`. For both option and return values, `.` is used to reference suboptions and contained return values. Array stubs (`[...]`) can be used to indicate that something is a list, for example the `:ansretval:` argument `ansible.builtin.service_facts#module:ansible_facts.services['systemd'].state` references the `ansible_facts.services.state` return value of the `ansible.builtin.service_facts` module (`[ansible_facts.services['systemd'].state](https://docs.ansible.com/projects/ansible-core/devel/collections/ansible/builtin/service_facts_module.html#ansible-collections-ansible-builtin-service-facts-module-return-ansible-facts-services-state) `). #### [Adding local TOCs](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#id15) [](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#adding-local-tocs "Link to this heading") 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: * place it below, not above, the main heading and (optionally) introductory text * use the `:local:` directive so the page’s main heading is not included * do not include a title The syntax is: .. contents:: :local: [Markdown guidelines](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#id16) [](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#markdown-guidelines "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Some Ansible ecosystem documentation is written in markdown and processed by mkdocs. We follow these technical or mechanical guidelines on all .md pages: ### [Heading notation](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#id17) [](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#headings-style-md "Link to this heading") [Section headings in markdown](https://daringfireball.net/projects/markdown/syntax#header) can use a variety of notations. To make our documents easy to read and to edit, we follow a standard set of heading notations. We use: * `#` for page titles: \# Installation * `##` for section headings: \## Installing on Linux Subsections add an additional `#` for each subsection. We recommend not going beyond `####` as that suggests a deeply nested document that could present better as multiple pages. ### [Linking in Markdown](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#id18) [](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#linking-in-markdown "Link to this heading") Using Mkdocs, you can format internal links \`\_ using the file name of the local file instead of an external URL. \[configuration\](/configuration) You can also link directly to a heading within a file Use the lower-case form of the heading. \[dependency\](/configuration/#dependency) External links use a similar format with the external URL. \[Ansible Documentation\](https://docs.ansible.com) ### [Code blocks](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#id19) [](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#code-blocks "Link to this heading") Markdown supports code blocks in the following format. \`\`\`text docs/ index.md user-guide/getting-started.md user-guide/configuration-options.md license.md \`\`\` [Accessibility guidelines](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#id20) [](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#accessibility-guidelines "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ Ansible documentation has a goal to be more accessible. Use the following guidelines to help us reach this goal. ### [Images and alternative text](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#id21) [](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#images-and-alternative-text "Link to this heading") Ensure all icons, images, diagrams, and non text elements have a meaningful alternative-text description. Do not include screen captures of CLI output. Use a code block instead. To add alt text in rst: > .. image:: path/networkdiag.png > :width: 400 > :alt: SpiffyCorp network diagram To add alt text in md: > !\[SpiffyCorp network diagram\](path/networkdiag.png) ### [Links and hypertext](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#id22) [](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#links-and-hypertext "Link to this heading") URLs and cross-reference links have descriptive text that conveys information about the content of the linked target. See [Internal navigation](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#style-links) for how to format links in RST and see [Linking in Markdown](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#style-links-md) for Markdown. ### [Tables](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#id23) [](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#tables "Link to this heading") Tables have a simple, logical reading order from left to right, and top to bottom. Tables include a heading row and avoid empty or blank table cells. Label tables with a descriptive title. For RST: > .. table:: File descriptions > > +----------+----------------------------+ > |File |Purpose | > +==========+============================+ > |foo.txt |foo configuration settings | > +----------+----------------------------+ > |bar.txt |bar configuration settings | > +----------+----------------------------+ For Markdown: > \#### File descriptions > > |File |Purpose | > |---------- | -------------------------- | > |foo.txt | foo configuration settings | > |bar.txt | bar configuration settings | ### [Colors and other visual information](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#id24) [](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#colors-and-other-visual-information "Link to this heading") > * Avoid instructions that rely solely on sensory characteristics. For example, do not use `Click the square, blue button to continue.` > > * Convey information by methods and not by color alone. > > * Ensure there is sufficient contrast between foreground and background text or graphical elements in images and diagrams. > > * Instructions for navigating through an interface make sense without directional indicators such as left, right, above, and below. > ### [Accessibility resources](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#id25) [](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#accessibility-resources "Link to this heading") Use the following resources to help test your documentation changes: * [axe DevTools browser extension](https://chrome.google.com/webstore/detail/axe-devtools-web-accessib/lhdoppojpmngadmnindnejefpokejbdd?hl=en-US&_ga=2.98933278.1490638154.1645821120-953800914.1645821120) - Highlights accessibility issues on a website page. * [WAVE browser extension](https://wave.webaim.org/extension/) from WebAIM - another accessibility tester. * [Orca screen reader](https://help.gnome.org/users/orca/stable/) - Common tool used by people with vision impairments. * [color filter](https://www.toptal.com/designers/colorfilter/) - For color-blind testing. [More resources](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#id26) [](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/index.html#more-resources "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- These pages offer more help with grammatical, stylistic, and technical rules for documentation. * [Basic rules](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/basic_rules.html) * [Voice Style](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/voice_style.html) * [Trademark Usage](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/trademarks.html) * [Grammar and Punctuation](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/grammar_punctuation.html) * [Spelling - Word Usage - Common Words and Phrases to Use and Avoid](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/spelling_word_choice.html) * [Preferred terminology](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/preferred_terms.html) * [Writing documentation so search can find it](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/search_hints.html) * [Resources](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/style_guide/resources.html) See also [Contributing to the Ansible Documentation](https://docs.ansible.com/projects/ansible-core/devel/community/documentation_contributions.html#community-documentation-contributions) How to contribute to the Ansible documentation [Testing the documentation locally](https://docs.ansible.com/projects/ansible-core/devel/community/documentation_contributions.html#testing-documentation-locally) How to build the Ansible documentation [Communication](https://docs.ansible.com/projects/ansible-core/devel/community/communication.html#communication) Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide --- # Configuring Ansible — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * [Installation Guide](https://docs.ansible.com/projects/ansible/latest/installation_guide/index.html) * Configuring Ansible * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/installation_guide/intro_configuration.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * [Configuring Ansible](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_configuration.html#id3) [](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_configuration.html#configuring-ansible "Link to this heading") ===================================================================================================================================================================================================================================================================== This topic describes how to control Ansible settings. [Configuration file](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_configuration.html#id4) [](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_configuration.html#configuration-file "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Certain settings in Ansible are adjustable with a configuration file (`ansible.cfg`). The stock configuration should be sufficient for most users, but there may be reasons you would want to change them. Paths where the configuration file is searched are listed in [reference documentation](https://docs.ansible.com/projects/ansible/latest/reference_appendices/config.html#ansible-configuration-settings-locations) . ### [Getting the latest configuration](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_configuration.html#id5) [](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_configuration.html#getting-the-latest-configuration "Link to this heading") If installing Ansible from a package manager, the latest `ansible.cfg` file should be present in `/etc/ansible`, possibly as a `.rpmnew` file (or other) as appropriate in the case of updates. If you installed Ansible from `pip` or from the source, you may want to create this file to override default settings in Ansible. You can generate an Ansible configuration file, `ansible.cfg`, that lists all default settings as follows: $ ansible-config init \--disabled \> ansible.cfg Include available plugins to create a more complete Ansible configuration as follows: $ ansible-config init \--disabled \-t all \> ansible.cfg For more details and a full listing of available configurations go to [configuration\_settings](https://docs.ansible.com/projects/ansible/latest/reference_appendices/config.html#ansible-configuration-settings) . You can use the [ansible-config](https://docs.ansible.com/projects/ansible/latest/cli/ansible-config.html#ansible-config) command-line utility to list your available options and inspect the current values. For in-depth details, see [Ansible Configuration Settings](https://docs.ansible.com/projects/ansible/latest/reference_appendices/config.html#ansible-configuration-settings) . [Environmental configuration](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_configuration.html#id6) [](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_configuration.html#environmental-configuration "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Ansible also allows configuring settings using environment variables. If these environment variables are set, they will override any associated settings loaded from the configuration file. You can get a full listing of available environment variables from: * [Ansible Configuration Settings](https://docs.ansible.com/projects/ansible/latest/reference_appendices/config.html#ansible-configuration-settings) : for configuring core functionality * [Index of all Collection Environment Variables](https://docs.ansible.com/projects/ansible/latest/collections/environment_variables.html#list-of-collection-env-vars) : for configuring plugins in collections [Command line options](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_configuration.html#id7) [](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_configuration.html#command-line-options "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Not all configuration options are present in the command line, just the ones deemed most useful or common. Settings in the command line will override those passed through the configuration file and the environment. The full list of options available is in [ansible-playbook](https://docs.ansible.com/projects/ansible/latest/cli/ansible-playbook.html#ansible-playbook) and [ansible](https://docs.ansible.com/projects/ansible/latest/cli/ansible.html#ansible) . --- # Galaxy Developer Guide — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * Galaxy Developer Guide * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/galaxy/dev_guide.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Galaxy Developer Guide[](https://docs.ansible.com/projects/ansible/latest/galaxy/dev_guide.html#galaxy-developer-guide "Link to this heading") ================================================================================================================================================ You can host collections and roles on Galaxy to share with the Ansible community. Galaxy content is formatted in pre-packaged units of work such as [roles](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#playbooks-reuse-roles) , and [collections](https://docs.ansible.com/projects/ansible/latest/collections_guide/index.html#collections) . You can create roles for provisioning infrastructure, deploying applications, and all of the tasks you do everyday. Taking this a step further, you can create collections which provide a comprehensive package of automation that may include multiple playbooks, roles, modules, and plugins. [Creating collections for Galaxy](https://docs.ansible.com/projects/ansible/latest/galaxy/dev_guide.html#id1) [](https://docs.ansible.com/projects/ansible/latest/galaxy/dev_guide.html#creating-collections-for-galaxy "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- 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/) . See [Developing collections](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_collections.html#developing-collections) for details on how to create collections. [Creating roles for Galaxy](https://docs.ansible.com/projects/ansible/latest/galaxy/dev_guide.html#id2) [](https://docs.ansible.com/projects/ansible/latest/galaxy/dev_guide.html#creating-roles-for-galaxy "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Use the `init` command to initialize the base structure of a new role, saving time on creating the various directories and main.yml files a role requires $ ansible-galaxy role init role\_name The above will create the following directory structure in the current working directory: role\_name/ README.md defaults/ main.yml files/ handlers/ main.yml meta/ main.yml tasks/ main.yml templates/ tests/ inventory test.yml vars/ main.yml If you want to create a repository for the role, the repository root should be role\_name. ### [Force](https://docs.ansible.com/projects/ansible/latest/galaxy/dev_guide.html#id3) [](https://docs.ansible.com/projects/ansible/latest/galaxy/dev_guide.html#force "Link to this heading") If a directory matching the name of the role already exists in the current working directory, the init command will result in an error. To ignore the error use the `--force` option. Force will create the above subdirectories and files, replacing anything that matches. ### [Container enabled](https://docs.ansible.com/projects/ansible/latest/galaxy/dev_guide.html#id4) [](https://docs.ansible.com/projects/ansible/latest/galaxy/dev_guide.html#container-enabled "Link to this heading") If you are creating a Container Enabled role, pass `--type container` to `ansible-galaxy role init`. This will create the same directory structure as above, but populate it with default files appropriate for a Container Enabled role. For example, the README.md has a slightly different structure, the `.travis.yml` file tests the role using [Ansible Container](https://github.com/ansible/ansible-container) , and the meta directory includes a `container.yml` file. ### [Using a custom role skeleton](https://docs.ansible.com/projects/ansible/latest/galaxy/dev_guide.html#id5) [](https://docs.ansible.com/projects/ansible/latest/galaxy/dev_guide.html#using-a-custom-role-skeleton "Link to this heading") A custom role skeleton directory can be supplied as follows: $ ansible-galaxy role init \--role-skeleton\=/path/to/skeleton role\_name When a skeleton is provided, init will: * copy all files and directories from the skeleton to the new role * any .j2 files found outside of a templates folder will be rendered as templates. The only useful variable at the moment is role\_name * The .git folder and any .git\_keep files will not be copied Alternatively, the role\_skeleton and ignoring of files can be configured with ansible.cfg \[galaxy\] role\_skeleton = /path/to/skeleton role\_skeleton\_ignore = ^.git$,^.\*/.git\_keep$ ### [Authenticate with Galaxy](https://docs.ansible.com/projects/ansible/latest/galaxy/dev_guide.html#id6) [](https://docs.ansible.com/projects/ansible/latest/galaxy/dev_guide.html#authenticate-with-galaxy "Link to this heading") Using the `import`, `delete` and `setup` commands to manage your roles on the Galaxy website requires authentication in the form of an API key, you must create an account on the Galaxy website. To create an authentication token: 1. Click Collections > API Token. 2. Click Load Token and then copy it. 3. Save your token in the path set in the [GALAXY\_TOKEN\_PATH](https://docs.ansible.com/projects/ansible/latest/reference_appendices/config.html#galaxy-token-path) . ### [Import a role](https://docs.ansible.com/projects/ansible/latest/galaxy/dev_guide.html#id7) [](https://docs.ansible.com/projects/ansible/latest/galaxy/dev_guide.html#import-a-role "Link to this heading") The `import` command requires that you authenticate with the API token. You can include it in your `ansible.cfg` file or use the `--token` command option. You are only allowed to remove roles where you have access to the repository in GitHub. To import a new role: $ ansible-galaxy role import github\_user github\_repo By default, the command will wait for Galaxy to complete the import process, displaying the results as the import progresses: Successfully submitted import request 41 Starting import 41: role\_name=myrole repo=githubuser/ansible-role-repo ref= Retrieving GitHub repo githubuser/ansible-role-repo Accessing branch: devel Parsing and validating meta/main.yml Parsing galaxy\_tags Parsing platforms Adding dependencies Parsing and validating README.md Adding repo tags as role versions Import completed Status SUCCESS : warnings=0 errors=0 See [ansible-galaxy](https://docs.ansible.com/projects/ansible/latest/cli/ansible-galaxy.html#ansible-galaxy) for other command options. ### [Delete a role](https://docs.ansible.com/projects/ansible/latest/galaxy/dev_guide.html#id8) [](https://docs.ansible.com/projects/ansible/latest/galaxy/dev_guide.html#delete-a-role "Link to this heading") The `delete` command requires that you authenticate with the API token. You can include it in your `ansible.cfg` file or use the `--token` command option. You are only allowed to remove roles where you have access to the repository in GitHub. Use the following to delete a role: $ ansible-galaxy role delete github\_user github\_repo This only removes the role from Galaxy. It does not remove or alter the actual GitHub repository. ### [Travis integrations](https://docs.ansible.com/projects/ansible/latest/galaxy/dev_guide.html#id9) [](https://docs.ansible.com/projects/ansible/latest/galaxy/dev_guide.html#travis-integrations "Link to this heading") You can create an integration or connection between a role in Galaxy and [Travis](https://travis-ci.org/) . Once the connection is established, a build in Travis will automatically trigger an import in Galaxy, updating the search index with the latest information about the role. You create the integration using the `setup` command with your API token. You will also need an account in Travis, and your Travis token. Once you are ready, use the following command to create the integration: $ ansible-galaxy role setup travis github\_user github\_repo xxx-travis-token-xxx The setup command requires your Travis token, however the token is not stored in Galaxy. It is used along with the GitHub username and repo to create a hash as described in [the Travis documentation](https://docs.travis-ci.com/user/notifications/) . The hash is stored in Galaxy and used to verify notifications received from Travis. The setup command enables Galaxy to respond to notifications. To configure Travis to run a build on your repository and send a notification, follow the [Travis getting started guide](https://docs.travis-ci.com/user/getting-started/) . To instruct Travis to notify Galaxy when a build completes, add the following to your .travis.yml file: notifications: webhooks: https://galaxy.ansible.com/api/v1/notifications/ #### List Travis integrations[](https://docs.ansible.com/projects/ansible/latest/galaxy/dev_guide.html#list-travis-integrations "Link to this heading") Use the `--list` option to display your Travis integrations: $ ansible-galaxy role setup \--list travis github\_user github\_repo xxx-travis-token-xxx ID Source Repo ---------- \---------- \---------- 2 travis github\_user/github\_repo 1 travis github\_user/github\_repo #### Remove Travis integrations[](https://docs.ansible.com/projects/ansible/latest/galaxy/dev_guide.html#remove-travis-integrations "Link to this heading") Use the `--remove` option to disable and remove a Travis integration: > $ ansible-galaxy role setup \--remove ID Provide the ID of the integration to be disabled. You can find the ID by using the `--list` option. See also [Using Ansible collections](https://docs.ansible.com/projects/ansible/latest/collections_guide/index.html#collections) Shareable collections of modules, playbooks and roles [Roles](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#playbooks-reuse-roles) All about ansible roles [Communication](https://docs.ansible.com/projects/ansible/latest/community/communication.html#communication) Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide --- # Special Variables — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * Special Variables * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/reference_appendices/special_variables.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Special Variables[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#special-variables "Link to this heading") ============================================================================================================================================================ Magic variables[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#magic-variables "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------- These variables cannot be set directly by the user; Ansible will always override them to reflect internal state. ansible\_check\_mode[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-ansible_check_mode "Link to this term") Boolean that indicates if we are in check mode or not ansible\_collection\_name[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-ansible_collection_name "Link to this term") The name of the collection the task that is executing is a part of. In the format of `namespace.collection` ansible\_config\_file[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-ansible_config_file "Link to this term") The full path of used Ansible configuration file ansible\_dependent\_role\_names[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-ansible_dependent_role_names "Link to this term") The names of the roles currently imported into the current play as dependencies of other plays ansible\_diff\_mode[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-ansible_diff_mode "Link to this term") Boolean that indicates if we are in diff mode or not ansible\_forks[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-ansible_forks "Link to this term") Integer reflecting the number of maximum forks available to this run ansible\_index\_var[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-ansible_index_var "Link to this term") The name of the value provided to `loop_control.index_var`. Added in `2.9` ansible\_inventory\_sources[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-ansible_inventory_sources "Link to this term") List of sources used as inventory ansible\_limit[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-ansible_limit "Link to this term") Contents of the `--limit` CLI option for the current execution of Ansible ansible\_loop[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-ansible_loop "Link to this term") A dictionary/map containing extended loop information when enabled through `loop_control.extended` ansible\_loop\_var[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-ansible_loop_var "Link to this term") The name of the value provided to `loop_control.loop_var`. Added in `2.8` ansible\_parent\_role\_names[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-ansible_parent_role_names "Link to this term") When the current role is being executed by means of an [include\_role](https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/include_role_module.html#include-role-module) or [import\_role](https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/import_role_module.html#import-role-module) action, this variable contains a list of all parent roles, with the most recent role (in other words, the role that included/imported this role) being the first item in the list. When multiple inclusions occur, this list lists the _last_ role (in other words, the role that included this role) as the _first_ item in the list. It is also possible that a specific role exists more than once in this list. For example: When role **A** includes role **B**, inside role B, `ansible_parent_role_names` will equal to `['A']`. If role **B** then includes role **C**, the list becomes `['B', 'A']`. ansible\_parent\_role\_paths[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-ansible_parent_role_paths "Link to this term") When the current role is being executed by means of an [include\_role](https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/include_role_module.html#include-role-module) or [import\_role](https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/import_role_module.html#import-role-module) action, this variable contains a list of all parent roles paths, with the most recent role (in other words, the role that included/imported this role) being the first item in the list. Please refer to `ansible_parent_role_names` for the order of items in this list. ansible\_play\_batch[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-ansible_play_batch "Link to this term") List of active hosts in the current play run limited by the serial, aka ‘batch’. Failed/Unreachable hosts are not considered ‘active’. ansible\_play\_hosts[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-ansible_play_hosts "Link to this term") List of hosts in the current play run, not limited by the serial. Failed/Unreachable hosts are excluded from this list. ansible\_play\_hosts\_all[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-ansible_play_hosts_all "Link to this term") List of all the hosts that were targeted by the play ansible\_play\_name[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-ansible_play_name "Link to this term") The name of the currently executed play. Added in `2.8`. (name attribute of the play, not file name of the playbook.) ansible\_play\_role\_names[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-ansible_play_role_names "Link to this term") The names of the roles currently imported into the current play. This list does **not** contain the role names that are implicitly included through dependencies. ansible\_playbook\_python[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-ansible_playbook_python "Link to this term") The path to the python interpreter being used by Ansible on the control node ansible\_role\_name[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-ansible_role_name "Link to this term") The fully qualified collection role name, in the format of `namespace.collection.role_name` ansible\_role\_names[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-ansible_role_names "Link to this term") The names of the roles currently imported into the current play, or roles referenced as dependencies of the roles imported into the current play. ansible\_run\_tags[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-ansible_run_tags "Link to this term") Contents of the `--tags` CLI option, which specifies which tags will be included for the current run. Note that if `--tags` is not passed, this variable will default to `["all"]`. ansible\_search\_path[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-ansible_search_path "Link to this term") Current search path for action plugins and lookups, in other words, where we search for relative paths when you do `template: src=myfile` ansible\_skip\_tags[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-ansible_skip_tags "Link to this term") Contents of the `--skip-tags` CLI option, which specifies which tags will be skipped for the current run. ansible\_verbosity[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-ansible_verbosity "Link to this term") Current verbosity setting for Ansible ansible\_version[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-ansible_version "Link to this term") Dictionary/map that contains information about the current running version of ansible, it has the following keys: full, major, minor, revision and string. group\_names[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-group_names "Link to this term") List of groups the current host is part of, it always reflects the `inventory_hostname` and ignores delegation. groups[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-groups "Link to this term") A dictionary/map with all the groups in inventory and each group has the list of hosts that belong to it hostvars[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-hostvars "Link to this term") A dictionary/map with all the hosts in inventory and variables assigned to them inventory\_dir[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-inventory_dir "Link to this term") The directory of the inventory source in which the inventory\_hostname was first defined. This always reflects the `inventory_hostname` and ignores delegation. inventory\_hostname[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-inventory_hostname "Link to this term") The inventory name for the ‘current’ host being iterated over in the play. This is not affected by delegation, it always reflects the original host for the task inventory\_hostname\_short[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-inventory_hostname_short "Link to this term") The short version of inventory\_hostname, is the first section after splitting it via `.`. As an example, for the `inventory_hostname` of `www.example.com`, `www` would be the `inventory_hostname_short` This is affected by delegation, so it will reflect the ‘short name’ of the delegated host inventory\_file[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-inventory_file "Link to this term") The file name of the inventory source in which the inventory\_hostname was first defined. Ignores delegation and always reflects the information for the `inventory_hostname`. omit[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-omit "Link to this term") Special variable that allows you to ‘omit’ an option in a task, for example `- user: name=bob home={{ bobs_home|default(omit) }}` play\_hosts[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-play_hosts "Link to this term") Deprecated, the same as ansible\_play\_batch playbook\_dir[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-playbook_dir "Link to this term") The path to the directory of the current playbook being executed. NOTE: This might be different than directory of the playbook passed to the `ansible-playbook` command line when a playbook contains a `import_playbook` statement. role\_name[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-role_name "Link to this term") The name of the role currently being executed. role\_names[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-role_names "Link to this term") Deprecated, the same as ansible\_play\_role\_names role\_path[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-role_path "Link to this term") The path to the dir of the currently running role Facts[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#facts "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------ These are variables that contain information pertinent to the current host (inventory\_hostname). They are only available if gathered first. See [Discovering variables: facts and magic variables](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_vars_facts.html#vars-and-facts) for more information. ansible\_facts[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-ansible_facts "Link to this term") Contains any facts gathered or cached for the inventory\_hostname Facts are normally gathered by the [setup](https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/setup_module.html#setup-module) module automatically in a play, but any module can return facts. ansible\_local[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-ansible_local "Link to this term") Contains any ‘local facts’ gathered or cached for the inventory\_hostname. The keys available depend on the custom facts created. See the [setup](https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/setup_module.html#setup-module) module and [facts.d or local facts](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_vars_facts.html#local-facts) for more details. Connection variables[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#connection-variables "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------ Connection variables are normally used to set the specifics on how to execute actions on a target. Most of them correspond to connection plugins, but not all are specific to them; other plugins like shell, terminal and become are normally involved. Only the common ones are described as each connection/become/shell/etc plugin can define its own overrides and specific variables. See [Controlling how Ansible behaves: precedence rules](https://docs.ansible.com/projects/ansible/latest/reference_appendices/general_precedence.html#general-precedence-rules) for how connection variables interact with [configuration settings](https://docs.ansible.com/projects/ansible/latest/reference_appendices/config.html#ansible-configuration-settings) , [command-line options](https://docs.ansible.com/projects/ansible/latest/command_guide/command_line_tools.html#command-line-tools) , and [playbook keywords](https://docs.ansible.com/projects/ansible/latest/reference_appendices/playbooks_keywords.html#playbook-keywords) . ansible\_become\_user[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-ansible_become_user "Link to this term") The user Ansible ‘becomes’ after using privilege escalation. This must be available to the ‘login user’. ansible\_connection[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-ansible_connection "Link to this term") The connection plugin actually used for the task on the target host. ansible\_host[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-ansible_host "Link to this term") The ip/name of the target host to use instead of inventory\_hostname. ansible\_python\_interpreter[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-ansible_python_interpreter "Link to this term") The path to the Python executable Ansible should use on the target host. ansible\_user[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#term-ansible_user "Link to this term") The user Ansible ‘logs in’ as. --- # Return Values — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * Return Values * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/reference_appendices/common_return_values.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * [Return Values](https://docs.ansible.com/projects/ansible/latest/reference_appendices/common_return_values.html#id1) [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/common_return_values.html#return-values "Link to this heading") =============================================================================================================================================================================================================================================================== Ansible modules normally return a data structure that can be registered into a variable, or seen directly when output by the ansible program. Each module can optionally document its own unique return values (visible through ansible-doc and on the [main docsite](https://docs.ansible.com/projects/ansible/latest/index.html#ansible-documentation) ). This document covers return values common to all modules. Note Some of these keys might be set by Ansible itself once it processes the module’s return information. [Common](https://docs.ansible.com/projects/ansible/latest/reference_appendices/common_return_values.html#id2) [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/common_return_values.html#common "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [backup\_file](https://docs.ansible.com/projects/ansible/latest/reference_appendices/common_return_values.html#id3) [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/common_return_values.html#backup-file "Link to this heading") For those modules that implement backup=no|yes when manipulating files, a path to the backup file created if original file was changed. > "backup\_file": "./foo.txt.32729.2020-07-30@06:24:19~" ### [changed](https://docs.ansible.com/projects/ansible/latest/reference_appendices/common_return_values.html#id4) [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/common_return_values.html#changed "Link to this heading") A boolean indicating if the task had to make changes to the target or delegated host. > "changed": true ### [diff](https://docs.ansible.com/projects/ansible/latest/reference_appendices/common_return_values.html#id5) [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/common_return_values.html#diff "Link to this heading") Information on differences between the previous and current state. Often a dictionary with entries `before` and `after`, which will then be formatted by the callback plugin to a diff view. > "diff": \[\ > {\ > "after": "",\ > "after\_header": "foo.txt (content)",\ > "before": "",\ > "before\_header": "foo.txt (content)"\ > },\ > {\ > "after\_header": "foo.txt (file attributes)",\ > "before\_header": "foo.txt (file attributes)"\ > }\ \ ### [failed](https://docs.ansible.com/projects/ansible/latest/reference_appendices/common_return_values.html#id6)\ [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/common_return_values.html#failed "Link to this heading")\ \ A boolean that indicates if the task was failed or not.\ \ > "failed": false\ \ ### [invocation](https://docs.ansible.com/projects/ansible/latest/reference_appendices/common_return_values.html#id7)\ [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/common_return_values.html#invocation "Link to this heading")\ \ Information on how the module was invoked.\ \ > "invocation": {\ > "module\_args": {\ > "\_original\_basename": "foo.txt",\ > "attributes": null,\ > "backup": true,\ > "checksum": "da39a3ee5e6b4b0d3255bfef95601890afd80709",\ > "content": null,\ > "delimiter": null,\ > "dest": "./foo.txt",\ > "directory\_mode": null,\ > "follow": false,\ > "force": true,\ > "group": null,\ > "local\_follow": null,\ > "mode": "666",\ > "owner": null,\ > "regexp": null,\ > "remote\_src": null,\ > "selevel": null,\ > "serole": null,\ > "setype": null,\ > "seuser": null,\ > "src": "/Users/foo/.ansible/tmp/ansible-tmp-1596115458.110205-105717464505158/source",\ > "unsafe\_writes": null,\ > "validate": null\ > }\ \ ### [msg](https://docs.ansible.com/projects/ansible/latest/reference_appendices/common_return_values.html#id8)\ [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/common_return_values.html#msg "Link to this heading")\ \ A string with a generic message relayed to the user.\ \ > "msg": "line added"\ \ ### [rc](https://docs.ansible.com/projects/ansible/latest/reference_appendices/common_return_values.html#id9)\ [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/common_return_values.html#rc "Link to this heading")\ \ Some modules execute command line utilities or are geared for executing commands directly (raw, shell, command, and so on), this field contains ‘return code’ of these utilities.\ \ > "rc": 257\ \ ### [results](https://docs.ansible.com/projects/ansible/latest/reference_appendices/common_return_values.html#id10)\ [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/common_return_values.html#results "Link to this heading")\ \ If this key exists, it indicates that a loop was present for the task and that it contains a list of the normal module ‘result’ per item.\ \ > "results": \[\ > {\ > "ansible\_loop\_var": "item",\ > "backup": "foo.txt.83170.2020-07-30@07:03:05~",\ > "changed": true,\ > "diff": \[\ > {\ > "after": "",\ > "after\_header": "foo.txt (content)",\ > "before": "",\ > "before\_header": "foo.txt (content)"\ > },\ > {\ > "after\_header": "foo.txt (file attributes)",\ > "before\_header": "foo.txt (file attributes)"\ > }\ > \],\ > "failed": false,\ > "invocation": {\ > "module\_args": {\ > "attributes": null,\ > "backrefs": false,\ > "backup": true\ > }\ > },\ > "item": "foo",\ > "msg": "line added"\ > },\ > {\ > "ansible\_loop\_var": "item",\ > "backup": "foo.txt.83187.2020-07-30@07:03:05~",\ > "changed": true,\ > "diff": \[\ > {\ > "after": "",\ > "after\_header": "foo.txt (content)",\ > "before": "",\ > "before\_header": "foo.txt (content)"\ > },\ > {\ > "after\_header": "foo.txt (file attributes)",\ > "before\_header": "foo.txt (file attributes)"\ > }\ > \],\ > "failed": false,\ > "invocation": {\ > "module\_args": {\ > "attributes": null,\ > "backrefs": false,\ > "backup": true\ > }\ > },\ > "item": "bar",\ > "msg": "line added"\ > }\ > \]\ \ ### [skipped](https://docs.ansible.com/projects/ansible/latest/reference_appendices/common_return_values.html#id11)\ [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/common_return_values.html#skipped "Link to this heading")\ \ A boolean that indicates if the task was skipped or not\ \ > "skipped": true\ \ ### [stderr](https://docs.ansible.com/projects/ansible/latest/reference_appendices/common_return_values.html#id12)\ [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/common_return_values.html#stderr "Link to this heading")\ \ Some modules execute command line utilities or are geared for executing commands directly (raw, shell, command, and so on), this field contains the error output of these utilities.\ \ > "stderr": "ls: foo: No such file or directory"\ \ ### [stderr\_lines](https://docs.ansible.com/projects/ansible/latest/reference_appendices/common_return_values.html#id13)\ [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/common_return_values.html#stderr-lines "Link to this heading")\ \ When stderr is returned we also always provide this field which is a list of strings, one item per line from the original.\ \ > "stderr\_lines": \[\ > "ls: doesntexist: No such file or directory"\ > \]\ \ ### [stdout](https://docs.ansible.com/projects/ansible/latest/reference_appendices/common_return_values.html#id14)\ [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/common_return_values.html#stdout "Link to this heading")\ \ Some modules execute command line utilities or are geared for executing commands directly (raw, shell, command, and so on). This field contains the normal output of these utilities.\ \ > "stdout": "foo!"\ \ ### [stdout\_lines](https://docs.ansible.com/projects/ansible/latest/reference_appendices/common_return_values.html#id15)\ [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/common_return_values.html#stdout-lines "Link to this heading")\ \ When stdout is returned, Ansible always provides a list of strings, each containing one item per line from the original output.\ \ > "stdout\_lines": \[\ > "foo!"\ > \]\ \ [Internal use](https://docs.ansible.com/projects/ansible/latest/reference_appendices/common_return_values.html#id16)\ [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/common_return_values.html#internal-use "Link to this heading")\ \ --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------\ \ These keys can be added by modules but will be removed from registered variables; they are ‘consumed’ by Ansible itself.\ \ ### [ansible\_facts](https://docs.ansible.com/projects/ansible/latest/reference_appendices/common_return_values.html#id17)\ [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/common_return_values.html#ansible-facts "Link to this heading")\ \ This key should contain a dictionary which will be appended to the facts assigned to the host. These will be directly accessible and don’t require using a registered variable.\ \ ### [exception](https://docs.ansible.com/projects/ansible/latest/reference_appendices/common_return_values.html#id18)\ [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/common_return_values.html#exception "Link to this heading")\ \ This key can contain traceback information caused by an exception in a module. It will only be displayed on high verbosity (-vvv).\ \ ### [warnings](https://docs.ansible.com/projects/ansible/latest/reference_appendices/common_return_values.html#id19)\ [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/common_return_values.html#warnings "Link to this heading")\ \ This key contains a list of strings that will be presented to the user.\ \ ### [deprecations](https://docs.ansible.com/projects/ansible/latest/reference_appendices/common_return_values.html#id20)\ [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/common_return_values.html#deprecations "Link to this heading")\ \ This key contains a list of dictionaries that will be presented to the user. Keys of the dictionaries are msg and version, values are string, value for the version key can be an empty string.\ \ See also\ \ [Collection Index](https://docs.ansible.com/projects/ansible/latest/collections/index.html#list-of-collections)\ \ Browse existing collections, modules, and plugins\ \ [GitHub modules directory](https://github.com/ansible/ansible/tree/devel/lib/ansible/modules)\ \ Browse source of core and extras modules\ \ [Communication](https://docs.ansible.com/projects/ansible/latest/community/communication.html#communication)\ \ Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide --- # Installing Ansible — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * [Installation Guide](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/index.html) * Installing Ansible * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/installation_guide/intro_installation.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Installing Ansible[](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#installing-ansible "Link to this heading") ================================================================================================================================================================= Ansible is an agentless automation tool that you install on a single host (referred to as the control node). From the control node, Ansible can manage an entire fleet of machines and other devices (referred to as managed nodes) remotely with SSH, Powershell remoting, and numerous other transports, all from a simple command-line interface with no databases or daemons required. [Control node requirements](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#id7) [](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#control-node-requirements "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- For your _control_ node (the machine that runs Ansible), you can use nearly any UNIX-like machine with Python installed. This includes Red Hat, Debian, Ubuntu, macOS, BSDs, and Windows under a [Windows Subsystem for Linux (WSL) distribution](https://docs.microsoft.com/en-us/windows/wsl/about) . Windows without WSL is not natively supported as a control node; see [Matt Davis’ blog post](http://blog.rolpdog.com/2020/03/why-no-ansible-controller-for-windows.html) for more information. [Managed node requirements](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#id8) [](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#managed-node-requirements "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The _managed_ node (the machine that Ansible is managing) does not require Ansible to be installed, but requires Python to run Ansible-generated Python code. The managed node also needs a user account that can connect through SSH to the node with an interactive POSIX shell. Note There can be exceptions in module requirements. For example, network modules do not require Python on the managed device. See documentation for the modules you use. [Node requirement summary](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#id9) [](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#node-requirement-summary "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can find details about control and managed node requirements, including Python versions, for each Ansible version in the [ansible-core control node Python support](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#support-life) and [ansible-core support matrix](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#ansible-core-support-matrix) sections. [Selecting an Ansible package and version to install](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#id10) [](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#selecting-an-ansible-package-and-version-to-install "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Ansible’s community packages are distributed in two ways: * `ansible-core`: a minimalist language and runtime package containing a set of [built-in modules and plugins](https://docs.ansible.com/projects/ansible-core/devel/collections/ansible/builtin/index.html#plugins-in-ansible-builtin) . * `ansible`: a much larger “batteries included” package, which adds a community-curated selection of [Ansible Collections](https://docs.ansible.com/projects/ansible-core/devel/collections_guide/index.html#collections) for automating a wide variety of devices. Choose the package that fits your needs. The following instructions use `ansible` as a package name, but you can substitute `ansible-core` if you prefer to start with the minimal package and separately install only the Ansible Collections you require. The `ansible` or `ansible-core` packages may be available in your operating systems package manager, and you are free to install these packages with your preferred method. For more information, see the [Installing Ansible on specific operating systems](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/installation_distros.html#installing-distros) guide. These installation instructions only cover the officially supported means of installing the python packages with `pip`. See the [Ansible package release status table](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#ansible-changelogs) for the `ansible-core` version included in the package. [Installing and upgrading Ansible with pipx](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#id11) [](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#installing-and-upgrading-ansible-with-pipx "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- On some systems, it may not be possible to install Ansible with `pip`, due to decisions made by the operating system developers. In such cases, `pipx` is a widely available alternative. These instructions will not go over the steps to install `pipx`; if those instructions are needed, please continue to the [pipx installation instructions](https://pipx.pypa.io/stable/#install-pipx) for more information. ### [Installing Ansible](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#id12) [](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#pipx-install "Link to this heading") Use `pipx` in your environment to install the full Ansible package: $ pipx install \--include-deps ansible You can install the minimal `ansible-core` package: $ pipx install ansible-core Alternately, you can install a specific version of `ansible-core`: $ pipx install ansible-core\==2.12.3 ### [Upgrading Ansible](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#id13) [](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#upgrading-ansible "Link to this heading") To upgrade an existing Ansible installation to the latest released version: $ pipx upgrade \--include-injected ansible ### [Installing Extra Python Dependencies](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#id14) [](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#installing-extra-python-dependencies "Link to this heading") To install additional python dependencies that may be needed, with the example of installing the `argcomplete` python package as described below: $ pipx inject ansible argcomplete Include the `--include-apps` option to make apps in the additional python dependency available on your PATH. This allows you to execute commands for those apps from the shell. $ pipx inject \--include-apps ansible argcomplete If you need to install dependencies from a requirements file, for example when installing the Azure collection, you can use `runpip`. $ pipx runpip ansible install \-r ~/.ansible/collections/ansible\_collections/azure/azcollection/requirements.txt [Installing and upgrading Ansible with pip](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#id15) [](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#installing-and-upgrading-ansible-with-pip "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ ### [Locating Python](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#id16) [](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#locating-python "Link to this heading") Locate and remember the path to the Python interpreter you wish to use to run Ansible. The following instructions refer to this Python as `python3`. For example, if you have determined that you want the Python at `/usr/bin/python3.9` to be the one that you will install Ansible under, specify that instead of `python3`. ### [Ensuring `pip` is available](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#id17) [](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#ensuring-pip-is-available "Link to this heading") To verify whether `pip` is already installed for your preferred Python: $ python3 \-m pip \-V If all is well, you should see something like the following: $ python3 \-m pip \-V pip 21.0.1 from /usr/lib/python3.9/site-packages/pip (python 3.9) If so, `pip` is available, and you can move on to the [next step](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#pip-install) . If you see an error like `No module named pip`, you will need to install `pip` under your chosen Python interpreter before proceeding. This may mean installing an additional OS package (for example, `python3-pip`), or installing the latest `pip` directly from the Python Packaging Authority by running the following: $ curl https://bootstrap.pypa.io/get-pip.py \-o get-pip.py $ python3 get-pip.py \--user You may need to perform some additional configuration before you are able to run Ansible. See the Python documentation on [installing to the user site](https://packaging.python.org/tutorials/installing-packages/#installing-to-the-user-site) for more information. ### [Installing Ansible](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#id18) [](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#pip-install "Link to this heading") Use `pip` in your selected Python environment to install the full Ansible package for the current user: $ python3 \-m pip install \--user ansible You can install the minimal `ansible-core` package for the current user: $ python3 \-m pip install \--user ansible-core Alternately, you can install a specific version of `ansible-core`: $ python3 \-m pip install \--user ansible-core\==2.12.3 ### [Upgrading Ansible](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#id19) [](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#pip-upgrade "Link to this heading") To upgrade an existing Ansible installation in this Python environment to the latest released version, simply add `--upgrade` to the command above: $ python3 \-m pip install \--upgrade \--user ansible [Installing Ansible to containers](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#id20) [](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#installing-ansible-to-containers "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ Instead of installing Ansible content manually, you can simply build an execution environment container image or use one of the available community images as your control node. See [Getting started with Execution Environments](https://docs.ansible.com/projects/ansible/12/getting_started_ee/index.html#getting-started-ee-index "(in Ansible v12)") for details. [Installing for development](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#id21) [](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#installing-for-development "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ If you are testing new features, fixing bugs, or otherwise working with the development team on changes to the core code, you can install and run the source from GitHub. Note You should only install and run the `devel` branch if you are modifying `ansible-core` or trying out features under development. This is a rapidly changing source of code and can become unstable at any point. For more information on getting involved in the Ansible project, see the [Ansible Community Guide](https://docs.ansible.com/projects/ansible-core/devel/community/index.html#ansible-community-guide) . For more information on creating Ansible modules and Collections, see the [Developer Guide](https://docs.ansible.com/projects/ansible/2.9/dev_guide/index.html#developer-guide "(in Ansible v2.9)") . ### [Installing `devel` from GitHub with `pip`](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#id22) [](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#installing-devel-from-github-with-pip "Link to this heading") You can install the `devel` branch of `ansible-core` directly from GitHub with `pip`: $ python3 \-m pip install \--user https://github.com/ansible/ansible/archive/devel.tar.gz You can replace `devel` in the URL mentioned above, with any other branch or tag on GitHub to install older versions of Ansible, tagged alpha or beta versions, and release candidates. ### [Running the `devel` branch from a clone](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#id23) [](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#running-the-devel-branch-from-a-clone "Link to this heading") `ansible-core` is easy to run from source. You do not need `root` permissions to use it and there is no software to actually install. No daemons or database setup are required. 1. Clone the `ansible-core` repository $ git clone https://github.com/ansible/ansible.git $ cd ./ansible 2. Setup the Ansible environment * Using Bash $ source ./hacking/env-setup * Using Fish $ source ./hacking/env-setup.fish * To suppress spurious warnings/errors, use `-q` $ source ./hacking/env-setup \-q 3. Install Python dependencies $ python3 \-m pip install \--user \-r ./requirements.txt 4. Update the `devel` branch of `ansible-core` on your local machine Use pull-with-rebase so any local changes are replayed. $ git pull \--rebase [Confirming your installation](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#id24) [](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#confirming-your-installation "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can test that Ansible is installed correctly by checking the version: $ ansible \--version The version displayed by this command is for the associated `ansible-core` package that has been installed. To check the version of the `ansible` package that has been installed: $ ansible-community \--version [Adding Ansible command shell completion](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#id25) [](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#adding-ansible-command-shell-completion "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can add shell completion of the Ansible command line utilities by installing an optional dependency called `argcomplete`. It supports bash, and has limited support for zsh and tcsh. For more information about installation and configuration, see the [argcomplete documentation](https://kislyuk.github.io/argcomplete/) . ### [Installing `argcomplete`](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#id26) [](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#installing-argcomplete "Link to this heading") If you chose the `pipx` installation instructions: $ pipx inject \--include-apps ansible argcomplete If you chose the `pip` installation instructions: $ python3 \-m pip install \--user argcomplete ### [Configuring `argcomplete`](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#id27) [](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#configuring-argcomplete "Link to this heading") There are 2 ways to configure `argcomplete` to allow shell completion of the Ansible command line utilities: globally or per command. #### [Global configuration](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#id28) [](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#global-configuration "Link to this heading") Global completion requires bash 4.2. $ activate-global-python-argcomplete \--user This will write a bash completion file to a user location. Use `--dest` to change the location or `sudo` to set up the completion globally. #### [Per command configuration](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#id29) [](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#per-command-configuration "Link to this heading") If you do not have bash 4.2, you must register each script independently. $ eval $(register-python-argcomplete ansible) $ eval $(register-python-argcomplete ansible-config) $ eval $(register-python-argcomplete ansible-console) $ eval $(register-python-argcomplete ansible-doc) $ eval $(register-python-argcomplete ansible-galaxy) $ eval $(register-python-argcomplete ansible-inventory) $ eval $(register-python-argcomplete ansible-playbook) $ eval $(register-python-argcomplete ansible-pull) $ eval $(register-python-argcomplete ansible-vault) You should place the above commands into your shell’s profile file such as `~/.profile` or `~/.bash_profile`. #### [Using `argcomplete` with zsh or tcsh](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#id30) [](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#using-argcomplete-with-zsh-or-tcsh "Link to this heading") See the [argcomplete documentation](https://kislyuk.github.io/argcomplete/) . See also [Introduction to ad hoc commands](https://docs.ansible.com/projects/ansible-core/devel/command_guide/intro_adhoc.html#intro-adhoc) Examples of basic commands [Working with playbooks](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks.html#working-with-playbooks) Learning ansible’s configuration management language [How do I handle the package dependencies required by Ansible package dependencies during Ansible installation ?](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#installation-faqs) Ansible Installation related to FAQs [Forum](https://docs.ansible.com/projects/ansible-core/devel/community/communication.html#ansible-forum) Join the Ansible community forum to get help and share insights [Real-time chat](https://docs.ansible.com/projects/ansible-core/devel/community/communication.html#communication-irc) How to join Ansible chat channels --- # Releases and maintenance — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * Releases and maintenance * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/reference_appendices/release_and_maintenance.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Releases and maintenance[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#releases-and-maintenance "Link to this heading") ==================================================================================================================================================================================== This section describes release cycles, rules, and maintenance schedules for both Ansible community projects: the Ansible community package and `ansible-core`. The two projects have different versioning systems, maintenance structures, contents, and workflows. | Ansible community package | ansible-core | | --- | --- | | Uses new versioning (2.10, then 3.0.0) | Continues “classic Ansible” versioning (2.11, then 2.12) | | Follows semantic versioning rules | Does not use semantic versioning | | Maintains only one version at a time | Maintains latest version plus two older versions | | Includes language, runtime, and selected Collections | Includes language, runtime, and builtin plugins | | Developed and maintained in Collection repositories | Developed and maintained in ansible/ansible repository | Many community users install the Ansible community package. The Ansible community package offers the functionality that existed in Ansible 2.9, with more than 85 Collections containing thousands of modules and plugins. The `ansible-core` option is primarily for developers and users who want to install only the collections they need. [Release cycle overview](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#id26) [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#release-cycle-overview "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ The two community releases are related - the release cycle follows this pattern: 1. Release of a new ansible-core major version, for example, ansible-core 2.11 * New release of ansible-core and two prior versions are now maintained (in this case, ansible-base 2.10, Ansible 2.9) * Work on new features for ansible-core continues in the `devel` branch 2. Collection freeze (no new Collections or new versions of existing Collections) on the Ansible community package 3. Release candidate for Ansible community package, testing, additional release candidates as necessary 4. Release of a new Ansible community package major version based on the new ansible-core, for example, Ansible 4.0.0 based on ansible-core 2.11 * Newest release of the Ansible community package is the only version now maintained * Work on new features continues in Collections * Individual Collections can make multiple minor and major releases 5. Minor releases of three maintained ansible-core versions every four weeks (2.11.1) 6. Minor releases of the single maintained Ansible community package version every four weeks (4.1.0) 7. Feature freeze on ansible-core 8. Release candidate for ansible-core, testing, additional release candidates as necessary 9. Release of the next ansible-core major version, cycle begins again ### [Ansible community package release cycle](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#id27) [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#ansible-community-package-release-cycle "Link to this heading") The Ansible community team typically releases two major versions of the community package per year, on a flexible release cycle that trails the release of `ansible-core`. This cycle can be extended to allow for larger changes to be properly implemented and tested before a new release is made available. See [Ansible Roadmap](https://docs.ansible.com/projects/ansible/12/roadmap/ansible_roadmap_index.html#ansible-roadmaps "(in Ansible v12)") for upcoming release details. Between major versions, we release a new minor version of the Ansible community package every four weeks. Minor releases include new backwards-compatible features, modules and plugins, as well as bug fixes. Starting with version 2.10, the Ansible community team guarantees maintenance for only one major community package release at a time. For example, when Ansible 4.0.0 gets released, the team will stop making new 3.x releases. Community members may maintain older versions if desired. Note Each Ansible EOL version may issue one final maintenance release at or shortly after the first release of the next version. When this happens, the final maintenance release is EOL at the date it releases. Note Older, unmaintained versions of the Ansible community package might contain unfixed security vulnerabilities (_CVEs_). If you are using a release of the Ansible community package that is no longer maintained, we strongly encourage you to upgrade as soon as possible to benefit from the latest features and security fixes. Each major release of the Ansible community package accepts the latest released version of each included Collection and the latest released version of ansible-core. For specific schedules and deadlines, see the [Ansible Roadmap](https://docs.ansible.com/projects/ansible/12/roadmap/ansible_roadmap_index.html#ansible-roadmaps "(in Ansible v12)") for each version. Major releases of the Ansible community package can contain breaking changes in the modules and other plugins within the included Collections and in core features. The Ansible community package follows semantic versioning rules. Minor releases of the Ansible community package accept only backwards-compatible changes in included Collections, that is, not Collections major releases. Collections must also use semantic versioning, so the Collection version numbers reflect this rule. For example, if Ansible 3.0.0 releases with community.general 2.0.0, then all minor releases of Ansible 3.x (such as Ansible 3.1.0 or Ansible 3.5.0) must include a 2.x release of community.general (such as 2.8.0 or 2.9.5) and not 3.x.x or later major releases. Work in Collections is tracked within the individual Collection repositories. You can refer to the [Ansible package porting guides](https://docs.ansible.com/projects/ansible/2.9/porting_guides/porting_guides.html#porting-guides "(in Ansible v2.9)") for tips on updating your playbooks to run on newer versions of Ansible. For Ansible 2.10 and later releases, you can install the Ansible package with `pip`. See [Installing Ansible](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#intro-installation-guide) for details. You can download older Ansible releases from [https://releases.ansible.com/ansible/](https://releases.ansible.com/ansible/) . ### [Ansible community changelogs](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#id28) [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#ansible-community-changelogs "Link to this heading") This table links to the changelogs for each major Ansible release. These changelogs contain the dates and significant changes in each minor release. | Ansible Community Package Release | Status | Core version dependency | | --- | --- | --- | | 14.0.0 | In development (unreleased) | 2.21 | | [13.x Changelogs](https://github.com/ansible-community/ansible-build-data/blob/main/13/CHANGELOG-v13.md) | Current- Latest | 2.20 | | [12.x Changelogs](https://github.com/ansible-community/ansible-build-data/blob/main/12/CHANGELOG-v12.md) | EOL in Dec 2025 | 2.19 | | [11.x Changelogs](https://github.com/ansible-community/ansible-build-data/blob/main/11/CHANGELOG-v11.md) | EOL in Dec 2025 | 2.18 | | [10.x Changelogs](https://github.com/ansible-community/ansible-build-data/blob/main/10/CHANGELOG-v10.md) | Unmaintained (end of life) | 2.17 | | [9.x Changelogs](https://github.com/ansible-community/ansible-build-data/blob/main/9/CHANGELOG-v9.rst) | Unmaintained (end of life) | 2.16 | | [8.x Changelogs](https://github.com/ansible-community/ansible-build-data/blob/main/8/CHANGELOG-v8.rst) | Unmaintained (end of life) | 2.15 | | [7.x Changelogs](https://github.com/ansible-community/ansible-build-data/blob/main/7/CHANGELOG-v7.rst) | Unmaintained (end of life) | 2.14 | | [6.x Changelogs](https://github.com/ansible-community/ansible-build-data/blob/main/6/CHANGELOG-v6.rst) | Unmaintained (end of life) | 2.13 | | [5.x Changelogs](https://github.com/ansible-community/ansible-build-data/blob/main/5/CHANGELOG-v5.rst) | Unmaintained (end of life) | 2.12 | | [4.x Changelogs](https://github.com/ansible-community/ansible-build-data/blob/main/4/CHANGELOG-v4.rst) | Unmaintained (end of life) | 2.11 | | [3.x Changelogs](https://github.com/ansible-community/ansible-build-data/blob/main/3/CHANGELOG-v3.rst) | Unmaintained (end of life) | 2.10 | | [2.10 Changelogs](https://github.com/ansible-community/ansible-build-data/blob/main/2.10/CHANGELOG-v2.10.rst) | Unmaintained (end of life) | 2.10 | ### [ansible-core release cycle](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#id29) [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#ansible-core-release-cycle "Link to this heading") `ansible-core` is developed and released on a flexible release cycle. We can extend this cycle to properly implement and test larger changes before a new release is made available. See [ansible-core Roadmaps](https://docs.ansible.com/projects/ansible-core/devel/roadmap/ansible_core_roadmap_index.html#ansible-core-roadmaps) for upcoming release details. `ansible-core` has a graduated maintenance structure that extends to three major releases. For more information, read about the [Development and maintenance workflows](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#development-and-stable-version-maintenance-workflow) or see the chart in [ansible-core control node Python support](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#release-schedule) for the degrees to which current releases are maintained. Note Older, unmaintained versions of `ansible-core` can contain unfixed security vulnerabilities (_CVEs_). If you are using a release of `ansible-core` that is no longer maintained, we strongly encourage you to upgrade as soon as possible to benefit from the latest features and security fixes. `ansible-core` maintenance continues for 3 releases. Thus the latest release receives security and general bug fixes when it is first released, security and critical bug fixes when the next `ansible-core` version is released, and **only** security fixes once the follow on to that version is released. You can refer to the [Ansible Core Porting Guides](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/core_porting_guides.html#core-porting-guides) for tips on updating your playbooks to run on newer versions of `ansible-core`. You can install `ansible-core` with `pip`. See [Installing Ansible](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#intro-installation-guide) for details. ### [`ansible-core` control node Python support](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#id30) [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#ansible-core-control-node-python-support "Link to this heading") Starting with `ansible-core` version 2.12, each release includes control node support for the three most recently released Python versions. ### [`ansible-core` target node Python support](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#id31) [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#ansible-core-target-node-python-support "Link to this heading") Starting with `ansible-core` version 2.16, each release includes target node support for: * The 6 most recently released Python versions. * The 7 most recently released Python versions every 6th `ansible-core` release (2.16, 2.22, etc.) Support for Python 2.7 is included in `ansible-core` version 2.16 and earlier. ### [`ansible-core` target node PowerShell and Windows support](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#id32) [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#ansible-core-target-node-powershell-and-windows-support "Link to this heading") `ansible-core` on Windows supports the baseline version of PowerShell that each Windows version ships with. For example, Windows Server 2016 shipped with PowerShell 5.1 so Ansible will support PowerShell 5.1 for the life of Windows Server 2016 support. Support for each Windows version is determined by the Windows lifecycle policy and when each version reaches the extended end date. For example Windows Server 2012 and 2012 R2 extended end date was for October 10th 2023 while Windows Server 2016 is January 12th 2027. Windows support does not align with the 3 year Extended Security Updates (`ESU`) support from Microsoft which is a paid support option for products that are past the normal end of support date from Microsoft. ### [`ansible-core` support matrix](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#id33) [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#ansible-core-support-matrix "Link to this heading") This table links to the changelogs for each major `ansible-core` release. These changelogs contain the dates and significant changes in each minor release. Dates listed indicate the start date of the maintenance cycle. | Version | Support | End Of Life | Control Node Python | Target Python / PowerShell | | --- | --- | --- | --- | --- | | [2.21](https://github.com/ansible/ansible/blob/stable-2.21/changelogs/CHANGELOG-v2.21.rst) | GA: May 2026

Critical: Nov 2026

Security: May 2027 | Nov 2027 | Python 3.12 - 3.14 | Python 3.9 - 3.14

PowerShell 5.1 - 7 | | [2.20](https://github.com/ansible/ansible/blob/stable-2.20/changelogs/CHANGELOG-v2.20.rst) | GA: 03 Nov 2025

Critical: 18 May 2026

Security: 02 Nov 2026 | May 2027 | Python 3.12 - 3.14 | Python 3.9 - 3.14

PowerShell 5.1 | | [2.19](https://github.com/ansible/ansible/blob/stable-2.19/changelogs/CHANGELOG-v2.19.rst) | GA: 21 July 2025

Critical: 03 Nov 2025

Security: 18 May 2026 | Nov 2026 | Python 3.11 - 3.13 | Python 3.8 - 3.13

PowerShell 5.1 | | [2.18](https://github.com/ansible/ansible/blob/stable-2.18/changelogs/CHANGELOG-v2.18.rst) | GA: 04 Nov 2024

Critical: 19 May 2025

Security: 03 Nov 2025 | May 2026 | Python 3.11 - 3.13 | Python 3.8 - 3.13

PowerShell 5.1 | | [2.17](https://github.com/ansible/ansible/blob/stable-2.17/changelogs/CHANGELOG-v2.17.rst) | GA: 20 May 2024

Critical: 04 Nov 2024

Security: 19 May 2025 | **EOL**

Nov 2025 | Python 3.10 - 3.12 | Python 3.7 - 3.12

PowerShell 5.1 | | [2.16](https://github.com/ansible/ansible/blob/stable-2.16/changelogs/CHANGELOG-v2.16.rst) | GA: 06 Nov 2023

Critical: 20 May 2024

Security: Nov 2024 | **EOL**

July 2025 | Python 3.10 - 3.12 | Python 2.7

Python 3.6 - 3.12

Powershell 5.1 | | [2.15](https://github.com/ansible/ansible/blob/stable-2.15/changelogs/CHANGELOG-v2.15.rst) | GA: 22 May 2023

Critical: 06 Nov 2023

Security: 20 May 2024 | **EOL**

Nov 2024 | Python 3.9 - 3.11 | Python 2.7

Python 3.5 - 3.11

PowerShell 3 - 5.1 | | [2.14](https://github.com/ansible/ansible/blob/stable-2.14/changelogs/CHANGELOG-v2.14.rst) | GA: 07 Nov 2022

Critical: 22 May 2023

Security: 06 Nov 2023 | **EOL**

20 May 2024 | Python 3.9 - 3.11 | Python 2.7

Python 3.5 - 3.11

PowerShell 3 - 5.1 | | [2.13](https://github.com/ansible/ansible/blob/stable-2.13/changelogs/CHANGELOG-v2.13.rst) | GA: 23 May 2022

Critical: 07 Nov 2022

Security: 22 May 2023 | **EOL**

06 Nov 2023 | Python 3.8 - 3.10 | Python 2.7

Python 3.5 - 3.10

PowerShell 3 - 5.1 | | [2.12](https://github.com/ansible/ansible/blob/stable-2.12/changelogs/CHANGELOG-v2.12.rst) | GA: 08 Nov 2021

Critical: 23 May 2022

Security: 07 Nov 2022 | **EOL**

22 May 2023 | Python 3.8 - 3.10 | Python 2.6 - 2.7

Python 3.5 - 3.10

PowerShell 3 - 5.1 | | [2.11](https://github.com/ansible/ansible/blob/stable-2.11/changelogs/CHANGELOG-v2.11.rst) | GA: 26 Apr 2021

Critical: 08 Nov 2021

Security: 23 May 2022 | **EOL**

07 Nov 2022 | Python 2.7

Python 3.5 - 3.9 | Python 2.6 - 2.7

Python 3.5 - 3.9

PowerShell 3 - 5.1 | | [2.10](https://github.com/ansible/ansible/blob/stable-2.10/changelogs/CHANGELOG-v2.10.rst) | GA: 13 Aug 2020

Critical: 26 Apr 2021

Security: 08 Nov 2021 | **EOL**

23 May 2022 | Python 2.7

Python 3.5 - 3.9 | Python 2.6 - 2.7

Python 3.5 - 3.9

PowerShell 3 - 5.1 | | [2.9](https://github.com/ansible/ansible/blob/stable-2.9/changelogs/CHANGELOG-v2.9.rst) | GA: 31 Oct 2019

Critical: 13 Aug 2020

Security: 26 Apr 2021 | **EOL**

23 May 2022 | Python 2.7

Python 3.5 - 3.8 | Python 2.6 - 2.7

Python 3.5 - 3.8

PowerShell 3 - 5.1 | ### [`ansible-core` versioning](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#id34) [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#ansible-core-versioning "Link to this heading") The ansible-core project uses a historical versioning scheme, most similar to the versioning scheme used by Python. This scheme follows the formatting of `X.Y.Z` which is described in detail below. #### [What is the `X` in `X.Y.Z`?](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#id35) [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#what-is-the-x-in-x-y-z "Link to this heading") The `X` represents the internal architecture of `ansible-core`. The `X` here does not imply any form of compatibility, nor anything about the scope of the changes. * `v1` can be best described as the internal architecture revolving around `ansible.runner.Runner` as the “execution” engine * `v2` can be best described as the internal architecture revolving around the `TaskQueueManager`, `PlayIterator`, and the strategy as the “execution” engine #### [What is the `Y` in `X.Y.Z`?](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#id36) [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#what-is-the-y-in-x-y-z "Link to this heading") Approximately every 6 months, in May and November ansible-core releases a new _Major_ release. This is denoted by the `Y` in the `X.Y.Z` version scheme. Although the `Y` denotes the Major version, it is not referenced independently, and instead a Major version is indicated in the format of `X.Y`, such as `2.16`. As such, versions like `2.9.0`, `2.10.0`, `2.11.0`, `2.16.0` and `2.19.0` are all major releases. `X.Y.0` releases do not carry any guarantee of 100% backwards compatibility with the version before it. Some may be more or less impactful based on the scope of the work for the release. Check porting guides for changes that may necessitate user intervention. #### [What is the `Z` in `X.Y.Z`?](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#id37) [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#what-is-the-z-in-x-y-z "Link to this heading") This is the patch version. ansible-core operates on a 4 week patch schedule. The `Z` release of a major version will include bugfixes and security fixes as outlined in the [ansible-core support matrix](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#ansible-core-support-matrix) . [Preparing for a new release](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#id38) [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#preparing-for-a-new-release "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [Feature freezes](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#id39) [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#feature-freezes "Link to this heading") During final preparations for a new release, core developers and maintainers focus on improving the release candidate, not on adding or reviewing new features. We may impose a feature freeze. A feature freeze means that we delay new features and fixes unrelated to the pending release so we can create the new release as soon as possible. ### [Release candidates](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#id40) [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#release-candidates "Link to this heading") We create at least one release candidate before each new major release of Ansible or `ansible-core`. Release candidates allow the Ansible community to try out new features, test existing playbooks on the release candidate, and report bugs or issues they find. Ansible and `ansible-core` tag the first release candidate (RC1) which is usually scheduled to last five business days. If no major bugs or issues are identified during this period, the release candidate becomes the final release. If there are major problems with the first candidate, the team and the community fix them and tag a second release candidate (RC2). This second candidate lasts for a shorter duration than the first. If no problems have been reported for an RC2 after two business days, the second release candidate becomes the final release. If there are major problems in RC2, the cycle begins again with another release candidate and repeats until the maintainers agree that all major problems have been fixed. [Development and maintenance workflows](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#id41) [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#development-and-maintenance-workflows "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ In between releases, the Ansible community develops new features, maintains existing functionality, and fixes bugs in `ansible-core` and in the collections included in the Ansible community package. ### [Ansible community package workflow](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#id42) [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#ansible-community-package-workflow "Link to this heading") The Ansible community develops and maintains the features and functionality included in the Ansible community package in Collections repositories, with a workflow that looks like this: > * Developers add new features and bug fixes to the individual Collections, following each Collection’s rules on contributing. > > * Each new feature and each bug fix includes a changelog fragment describing the work. > > * Release engineers create a minor release for the current version every four weeks to ensure that the latest bug fixes are available to users. > > * At the end of the development period, the release engineers announce which Collections, and which major version of each included Collection, will be included in the next release of the Ansible community package. New Collections and new major versions may not be added after this, and the work of creating a new release begins. > We generally do not provide fixes for unmaintained releases of the Ansible community package, however, there can sometimes be exceptions for critical issues. Some Collections are maintained by the Ansible team, some by Partner organizations, and some by community teams. For more information on adding features or fixing bugs in Ansible-maintained Collections, see [Contributing to Ansible-maintained Collections](https://docs.ansible.com/projects/ansible/12/community/contributing_maintained_collections.html#contributing-maintained-collections "(in Ansible v12)") . ### [ansible-core workflow](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#id43) [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#ansible-core-workflow "Link to this heading") The Ansible community develops and maintains `ansible-core` on [GitHub](https://github.com/ansible/ansible) , with a workflow that looks like this: > * Developers add new features and bug fixes to the `devel` branch. > > * Each new feature and each bug fix includes a changelog fragment describing the work. > > * The development team backports bug fixes to one, two, or three stable branches, depending on the severity of the bug. They do not backport new features. > > * Release engineers create a minor release for each maintained version every four weeks to ensure that the latest bug fixes are available to users. > > * At the end of the development period, the release engineers impose a feature freeze and the work of creating a new release begins. > We generally do not provide fixes for unmaintained releases of `ansible-core`, however, there can sometimes be exceptions for critical issues. For more information about adding features or fixing bugs in `ansible-core` see [The Ansible Development Cycle](https://docs.ansible.com/projects/ansible-core/devel/community/development_process.html#community-development-process) . ### [Generating changelogs](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#id44) [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#generating-changelogs "Link to this heading") We generate changelogs based on fragments. When creating new features for existing modules and plugins or fixing bugs, create a changelog fragment describing the change. A changelog entry is not needed for new modules or plugins. Details for those items will be generated from the module documentation. To add changelog fragments to Collections in the Ansible community package, we recommend the [antsibull-changelog utility](https://github.com/ansible-community/antsibull-changelog/blob/main/docs/changelogs.rst) . To add changelog fragments for new features and bug fixes in `ansible-core`, see the [changelog examples and instructions](https://docs.ansible.com/projects/ansible-core/devel/community/development_process.html#changelogs-how-to) in the Community Guide. [Deprecation cycles](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#id45) [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#deprecation-cycles "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Sometimes we remove a feature, normally in favor of a reimplementation that we hope does a better job. To do this we have a deprecation cycle. First we mark a feature as ‘deprecated’. This is normally accompanied with warnings to the user as to why we deprecated it, what alternatives they should switch to and when (which version) we are scheduled to remove the feature permanently. ### [Ansible community package deprecation cycle](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#id46) [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#ansible-community-package-deprecation-cycle "Link to this heading") Since Ansible is a package of individual collections, the deprecation cycle depends on the collection maintainers. We recommend the collection maintainers deprecate a feature in one Ansible major version and do not remove that feature for one year, or at least until the next major Ansible version. For example, deprecate the feature in 3.1.0 and do not remove the feature until 5.0.0 or 4.0.0 at the earliest. Collections should use semantic versioning, such that the major collection version cannot be changed within an Ansible major version. Therefore, the removal should not happen before the next major Ansible community package release. This is up to each collection maintainer and cannot be guaranteed. ### [ansible-core deprecation cycle](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#id47) [](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/release_and_maintenance.html#ansible-core-deprecation-cycle "Link to this heading") The deprecation cycle in `ansible-core` is normally across 4 feature releases (2.x. where the x marks a feature release). The feature is normally removed in the 4th release after we announce the deprecation. For example, something deprecated in 2.10 will be removed in 2.13. The tracking is tied to the number of releases, not the release numbering itself. Although this is the standard, there are times where a deprecation cycle for a feature or behavior may have a longer or shorter deprecation cycle based on use or urgency of removal. Unintended or undocumented functionality may be removed without a deprecation cycle. In this context, unintended functionality refers specifically to emergent features that occur outside the release roadmap. See also [Committers Guidelines](https://docs.ansible.com/projects/ansible-core/devel/community/committer_guidelines.html#community-committer-guidelines) Guidelines for Ansible Core contributors and maintainers [Testing Strategies](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/test_strategies.html#testing-strategies) Testing strategies [Ansible Community Guide](https://docs.ansible.com/projects/ansible-core/devel/community/index.html#ansible-community-guide) Community information and contributing [Communication](https://docs.ansible.com/projects/ansible-core/devel/community/communication.html#communication) Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide --- # Advanced Contributor Guide — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * Advanced Contributor Guide * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/community/advanced_index.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Advanced Contributor Guide[](https://docs.ansible.com/projects/ansible-core/devel/community/advanced_index.html#advanced-contributor-guide "Link to this heading") ==================================================================================================================================================================== This guide focuses on contributors who are committers, GitHub admins, release managers, or Ansible ecosystem project developers. * [Committers Guidelines](https://docs.ansible.com/projects/ansible-core/devel/community/committer_guidelines.html) * [GitHub Admins](https://docs.ansible.com/projects/ansible-core/devel/community/github_admins.html) * [Ansible Ecosystem Project Development Resources](https://docs.ansible.com/projects/ansible-core/devel/community/ecosystem_project_resources.html) --- # Introduction to Ansible — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * [Getting started with Ansible](https://docs.ansible.com/projects/ansible-core/devel/getting_started/index.html) * Introduction to Ansible * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/getting_started/introduction.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Introduction to Ansible[](https://docs.ansible.com/projects/ansible-core/devel/getting_started/introduction.html#introduction-to-ansible "Link to this heading") ================================================================================================================================================================== Ansible provides open-source automation that reduces complexity and runs everywhere. Using Ansible lets you automate virtually any task. Here are some common use cases for Ansible: * Eliminate repetition and simplify workflows * Manage and maintain system configuration * Continuously deploy complex software * Perform zero-downtime rolling updates Ansible uses simple, human-readable scripts called playbooks to automate your tasks. You declare the desired state of a local or remote system in your playbook. Ansible ensures that the system remains in that state. As automation technology, Ansible is designed around the following principles: Agent-less architecture Low maintenance overhead by avoiding the installation of additional software across IT infrastructure. Simplicity Automation playbooks use straightforward YAML syntax for code that reads like documentation. Ansible is also decentralized, using SSH with existing OS credentials to access remote machines. Scalability and flexibility Easily and quickly scale the systems you automate through a modular design that supports a large range of operating systems, cloud platforms, and network devices. Idempotence and predictability When the system is in the state your playbook describes, Ansible does not change anything, even if the playbook runs multiple times. Ready to start using Ansible? [Get up and running in a few easy steps](https://docs.ansible.com/projects/ansible-core/devel/getting_started/get_started_ansible.html#get-started-ansible) . --- # Start automating with Ansible — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * [Getting started with Ansible](https://docs.ansible.com/projects/ansible-core/devel/getting_started/index.html) * Start automating with Ansible * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/getting_started/get_started_ansible.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Start automating with Ansible[](https://docs.ansible.com/projects/ansible-core/devel/getting_started/get_started_ansible.html#start-automating-with-ansible "Link to this heading") ===================================================================================================================================================================================== Get started with Ansible by creating an automation project, building an inventory, and creating a “Hello World” playbook. 1. Install Ansible. pip install ansible 2. Create a project folder on your filesystem. mkdir ansible\_quickstart && cd ansible\_quickstart Using a single directory structure makes it easier to add to source control as well as to reuse and share automation content. Continue getting started with Ansible by [building an inventory](https://docs.ansible.com/projects/ansible-core/devel/getting_started/get_started_inventory.html#get-started-inventory) . See also [Installing Ansible](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_installation.html#installation-guide) Installation guide with instructions for installing Ansible on various operating systems [Ansible Demos](https://github.com/ansible/product-demos) Demonstrations of different Ansible usecases [Ansible Labs](https://www.ansible.com/products/ansible-training) Labs to provide further knowledge on different topics [Ansible Communication Guide](https://docs.ansible.com/projects/ansible-core/devel/community/communication.html#communication) Questions? Help? Ideas? Ask the community --- # ansible-core Contributors Guide — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * ansible-core Contributors Guide * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/community/contributions.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * ansible-core Contributors Guide[](https://docs.ansible.com/projects/ansible/latest/community/contributions.html#ansible-core-contributors-guide "Link to this heading") ========================================================================================================================================================================= * [Reporting bugs and requesting features](https://docs.ansible.com/projects/ansible/latest/community/reporting_bugs_and_features.html) * [Reporting a bug](https://docs.ansible.com/projects/ansible/latest/community/reporting_bugs_and_features.html#reporting-a-bug) * [Requesting a feature](https://docs.ansible.com/projects/ansible/latest/community/reporting_bugs_and_features.html#requesting-a-feature) * [Contributing to the Ansible Documentation](https://docs.ansible.com/projects/ansible/latest/community/documentation_contributions.html) * [Editing docs directly on GitHub](https://docs.ansible.com/projects/ansible/latest/community/documentation_contributions.html#editing-docs-directly-on-github) * [Reviewing or solving open issues](https://docs.ansible.com/projects/ansible/latest/community/documentation_contributions.html#reviewing-or-solving-open-issues) * [Reviewing open PRs](https://docs.ansible.com/projects/ansible/latest/community/documentation_contributions.html#reviewing-open-prs) * [Opening a new issue and/or PR](https://docs.ansible.com/projects/ansible/latest/community/documentation_contributions.html#opening-a-new-issue-and-or-pr) * [Verifying your documentation PR](https://docs.ansible.com/projects/ansible/latest/community/documentation_contributions.html#verifying-your-documentation-pr) * [Joining the documentation working group](https://docs.ansible.com/projects/ansible/latest/community/documentation_contributions.html#joining-the-documentation-working-group) * [The Ansible Development Cycle](https://docs.ansible.com/projects/ansible/latest/community/development_process.html) * [Macro development: `ansible-core` roadmaps, releases, and projects](https://docs.ansible.com/projects/ansible/latest/community/development_process.html#macro-development-ansible-core-roadmaps-releases-and-projects) * [Micro development: the lifecycle of a PR](https://docs.ansible.com/projects/ansible/latest/community/development_process.html#micro-development-the-lifecycle-of-a-pr) * [Making your PR merge-worthy](https://docs.ansible.com/projects/ansible/latest/community/development_process.html#making-your-pr-merge-worthy) * [Backporting merged PRs in `ansible-core`](https://docs.ansible.com/projects/ansible/latest/community/development_process.html#backporting-merged-prs-in-ansible-core) * [Other Tools and Programs](https://docs.ansible.com/projects/ansible/latest/community/other_tools_and_programs.html) * [Popular editors](https://docs.ansible.com/projects/ansible/latest/community/other_tools_and_programs.html#popular-editors) * [Tools for validating playbooks](https://docs.ansible.com/projects/ansible/latest/community/other_tools_and_programs.html#tools-for-validating-playbooks) * [Collection development tools](https://docs.ansible.com/projects/ansible/latest/community/other_tools_and_programs.html#collection-development-tools) * [Other tools](https://docs.ansible.com/projects/ansible/latest/community/other_tools_and_programs.html#other-tools) If you have a specific Ansible interest or expertise (for example, VMware, Linode, and so on), consider joining a [working group](https://docs.ansible.com/projects/ansible/latest/community/communication.html#working-group-list) . Working with the Ansible repo[](https://docs.ansible.com/projects/ansible/latest/community/contributions.html#working-with-the-ansible-repo "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------- * I want to make my first code changes to a collection or to `ansible-core`. How do I [set up my Python development environment](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_general.html#environment-setup) ? * I would like to get more efficient as a developer. How can I find [editors, linters, and other tools](https://docs.ansible.com/projects/ansible/latest/community/other_tools_and_programs.html#other-tools-and-programs) that will support my Ansible development efforts? * I want my code to meet Ansible’s guidelines. Where can I find guidance on [coding in Ansible](https://docs.ansible.com/projects/ansible/latest/dev_guide/index.html#developer-guide) ? * I would like to connect Ansible to a new API or other resource. How do I [create a collection](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_in_groups.html#developing-modules-in-groups) ? * My pull request is marked `needs_rebase`. How do I [rebase my PR](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_rebasing.html#rebase-guide) ? * I am using an older version of Ansible and want a bug fixed in my version that has already been fixed on the `devel` branch. How do I [backport a bugfix PR](https://docs.ansible.com/projects/ansible/latest/community/development_process.html#backport-process) ? * I have an open pull request with a failing test. How do I learn about Ansible’s [testing (CI) process](https://docs.ansible.com/projects/ansible/latest/dev_guide/testing.html#developing-testing) ? * I am ready to step up as a collection maintainer. What are the [guidelines for maintainers](https://docs.ansible.com/projects/ansible/latest/community/maintainers.html#maintainers) ? * A module in a collection I maintain is obsolete. How do I [deprecate a module](https://docs.ansible.com/projects/ansible/latest/dev_guide/module_lifecycle.html#deprecating-modules) ? --- # Ansible tips and tricks — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * Ansible tips and tricks * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/tips_tricks/index.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Ansible tips and tricks[](https://docs.ansible.com/projects/ansible/latest/tips_tricks/index.html#ansible-tips-and-tricks "Link to this heading") =================================================================================================================================================== Note **Making Open Source More Inclusive** 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) . Welcome to the Ansible tips and tricks guide. These tips and tricks have helped us optimize our Ansible usage and we offer them here as suggestions. We hope they will help you organize content, write playbooks, maintain inventory, and execute Ansible. Ultimately, though, you should use Ansible in the way that makes the most sense for your organization and your goals. * [General tips](https://docs.ansible.com/projects/ansible/latest/tips_tricks/ansible_tips_tricks.html) * [Keep it simple](https://docs.ansible.com/projects/ansible/latest/tips_tricks/ansible_tips_tricks.html#keep-it-simple) * [Use version control](https://docs.ansible.com/projects/ansible/latest/tips_tricks/ansible_tips_tricks.html#use-version-control) * [Customize the CLI output](https://docs.ansible.com/projects/ansible/latest/tips_tricks/ansible_tips_tricks.html#customize-the-cli-output) * [Avoid configuration-dependent content](https://docs.ansible.com/projects/ansible/latest/tips_tricks/ansible_tips_tricks.html#avoid-configuration-dependent-content) * [Playbook tips](https://docs.ansible.com/projects/ansible/latest/tips_tricks/ansible_tips_tricks.html#playbook-tips) * [Use whitespace](https://docs.ansible.com/projects/ansible/latest/tips_tricks/ansible_tips_tricks.html#use-whitespace) * [Always name plays, tasks, and blocks](https://docs.ansible.com/projects/ansible/latest/tips_tricks/ansible_tips_tricks.html#always-name-plays-tasks-and-blocks) * [Always mention the state](https://docs.ansible.com/projects/ansible/latest/tips_tricks/ansible_tips_tricks.html#always-mention-the-state) * [Use comments](https://docs.ansible.com/projects/ansible/latest/tips_tricks/ansible_tips_tricks.html#use-comments) * [Use fully qualified collection names](https://docs.ansible.com/projects/ansible/latest/tips_tricks/ansible_tips_tricks.html#use-fully-qualified-collection-names) * [Inventory tips](https://docs.ansible.com/projects/ansible/latest/tips_tricks/ansible_tips_tricks.html#inventory-tips) * [Use dynamic inventory with clouds](https://docs.ansible.com/projects/ansible/latest/tips_tricks/ansible_tips_tricks.html#use-dynamic-inventory-with-clouds) * [Group inventory by function](https://docs.ansible.com/projects/ansible/latest/tips_tricks/ansible_tips_tricks.html#group-inventory-by-function) * [Separate production and staging inventory](https://docs.ansible.com/projects/ansible/latest/tips_tricks/ansible_tips_tricks.html#separate-production-and-staging-inventory) * [Keep vaulted variables safely visible](https://docs.ansible.com/projects/ansible/latest/tips_tricks/ansible_tips_tricks.html#keep-vaulted-variables-safely-visible) * [Execution tricks](https://docs.ansible.com/projects/ansible/latest/tips_tricks/ansible_tips_tricks.html#execution-tricks) * [Use Execution Environments](https://docs.ansible.com/projects/ansible/latest/tips_tricks/ansible_tips_tricks.html#use-execution-environments) * [Try it in staging first](https://docs.ansible.com/projects/ansible/latest/tips_tricks/ansible_tips_tricks.html#try-it-in-staging-first) * [Update in batches](https://docs.ansible.com/projects/ansible/latest/tips_tricks/ansible_tips_tricks.html#update-in-batches) * [Handling OS and distro differences](https://docs.ansible.com/projects/ansible/latest/tips_tricks/ansible_tips_tricks.html#handling-os-and-distro-differences) * [Sample Ansible setup](https://docs.ansible.com/projects/ansible/latest/tips_tricks/sample_setup.html) * [Sample directory layout](https://docs.ansible.com/projects/ansible/latest/tips_tricks/sample_setup.html#sample-directory-layout) * [Alternative directory layout](https://docs.ansible.com/projects/ansible/latest/tips_tricks/sample_setup.html#alternative-directory-layout) * [Sample group and host variables](https://docs.ansible.com/projects/ansible/latest/tips_tricks/sample_setup.html#sample-group-and-host-variables) * [Sample playbooks organized by function](https://docs.ansible.com/projects/ansible/latest/tips_tricks/sample_setup.html#sample-playbooks-organized-by-function) * [Sample task and handler files in a function-based role](https://docs.ansible.com/projects/ansible/latest/tips_tricks/sample_setup.html#sample-task-and-handler-files-in-a-function-based-role) * [What the sample setup enables](https://docs.ansible.com/projects/ansible/latest/tips_tricks/sample_setup.html#what-the-sample-setup-enables) * [Organizing for deployment or configuration](https://docs.ansible.com/projects/ansible/latest/tips_tricks/sample_setup.html#organizing-for-deployment-or-configuration) * [Using local Ansible modules](https://docs.ansible.com/projects/ansible/latest/tips_tricks/sample_setup.html#using-local-ansible-modules) --- # Ansible-core 2.18 Porting Guide — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * [Ansible Core Porting Guides](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/core_porting_guides.html) * Ansible-core 2.18 Porting Guide * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/porting_guides/porting_guide_core_2.18.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * [Ansible-core 2.18 Porting Guide](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.18.html#id1) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.18.html#ansible-core-2-18-porting-guide "Link to this heading") ===================================================================================================================================================================================================================================================================================================== This section discusses the behavioral changes between `ansible-core` 2.17 and `ansible-core` 2.18. It is intended to assist in updating your playbooks, plugins and other parts of your Ansible infrastructure so they will work with this version of Ansible. We suggest you read this page along with [ansible-core Changelog for 2.18](https://github.com/ansible/ansible/blob/stable-2.18/changelogs/CHANGELOG-v2.18.rst) to understand what updates you may need to make. This document is part of a collection on porting. The complete list of porting guides can be found at [porting guides](https://docs.ansible.com/projects/ansible/2.9/porting_guides/porting_guides.html#porting-guides "(in Ansible v2.9)") . [Playbook](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.18.html#id2) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.18.html#playbook "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- No notable changes [Command Line](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.18.html#id3) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.18.html#command-line "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * Python 3.10 is a no longer supported control node version. Python 3.11+ is now required for running Ansible. * Python 3.7 is a no longer supported remote version. Python 3.8+ is now required for target execution. [Deprecated](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.18.html#id4) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.18.html#deprecated "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- No notable changes [Modules](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.18.html#id5) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.18.html#modules "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- No notable changes ### [Modules removed](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.18.html#id6) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.18.html#modules-removed "Link to this heading") The following modules no longer exist: * No notable changes ### [Deprecation notices](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.18.html#id7) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.18.html#deprecation-notices "Link to this heading") No notable changes ### [Noteworthy module changes](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.18.html#id8) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.18.html#noteworthy-module-changes "Link to this heading") No notable changes [Plugins](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.18.html#id9) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.18.html#plugins "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * The `ssh` connection plugin now officially supports targeting Windows hosts. A breaking change that has been made as part of this official support is the low level command execution done by plugins like `ansible.builtin.raw` and action plugins calling `_low_level_execute_command` is no longer wrapped with a `powershell.exe` wrapped invocation. These commands will now be executed directly on the target host using the default shell configuration set on the Windows host. This change is done to simplify the configuration required on the Ansible side, make module execution more efficient, and to remove the need to decode stderr CLIXML output. A consequence of this change is that `ansible.builtin.raw` commands are no longer guaranteed to be run through a PowerShell shell and with the output encoding of UTF-8. To run a command through PowerShell and with UTF-8 output support, use the `ansible.windows.win_shell` or `ansible.windows.win_powershell` module instead. \- name: Run with win\_shell ansible.windows.win\_shell: Write-Host "Hello, Café" \- name: Run with win\_powershell ansible.windows.win\_powershell: script: Write-Host "Hello, Café" [Porting custom scripts](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.18.html#id10) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.18.html#porting-custom-scripts "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ No notable changes [Networking](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.18.html#id11) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.18.html#networking "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ No notable changes --- # Ansible-core 2.17 Porting Guide — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * [Ansible Core Porting Guides](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/core_porting_guides.html) * Ansible-core 2.17 Porting Guide * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/porting_guides/porting_guide_core_2.17.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * [Ansible-core 2.17 Porting Guide](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.17.html#id1) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.17.html#ansible-core-2-17-porting-guide "Link to this heading") ===================================================================================================================================================================================================================================================================================================== This section discusses the behavioral changes between `ansible-core` 2.16 and `ansible-core` 2.17. It is intended to assist in updating your playbooks, plugins and other parts of your Ansible infrastructure so they will work with this version of Ansible. We suggest you read this page along with [ansible-core Changelog for 2.17](https://github.com/ansible/ansible/blob/stable-2.17/changelogs/CHANGELOG-v2.17.rst) to understand what updates you may need to make. This document is part of a collection on porting. The complete list of porting guides can be found at [porting guides](https://docs.ansible.com/projects/ansible/2.9/porting_guides/porting_guides.html#porting-guides "(in Ansible v2.9)") . [Playbook](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.17.html#id2) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.17.html#playbook "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * Conditionals - due to mitigation of security issue CVE-2023-5764 in ansible-core 2.16.1, conditional expressions with embedded template blocks can fail with the message “`Conditional is marked as unsafe, and cannot be evaluated.`” when an embedded template consults data from untrusted sources like module results or vars marked `!unsafe`. Conditionals with embedded templates can be a source of malicious template injection when referencing untrusted data, and can nearly always be rewritten without embedded templates. Playbook task conditional keywords such as `when` and `until` have long displayed warnings discouraging use of embedded templates in conditionals; this warning has been expanded to non-task conditionals as well, such as the `assert` action. \- name: task with a module result (always untrusted by Ansible) shell: echo "hi mom" register: untrusted\_result \# don't do it this way... \# - name: insecure conditional with embedded template consulting untrusted data \# assert: \# that: '"hi mom" is in {{ untrusted\_result.stdout }}' \- name: securely access untrusted values directly as Jinja variables instead assert: that: '"hi mom" is in untrusted\_result.stdout' * `any_errors_fatal` - when a task in a block with a `rescue` section fails on a host, the `rescue` section is executed on all hosts. This occurs because `any_errors_fatal` automatically fails all hosts. [Command Line](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.17.html#id3) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.17.html#command-line "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * Python 2.7 and Python 3.6 are no longer supported remote versions. Python 3.7+ is now required for target execution. [Deprecated](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.17.html#id4) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.17.html#deprecated "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- No notable changes [Modules](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.17.html#id5) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.17.html#modules "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- No notable changes ### [Modules removed](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.17.html#id6) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.17.html#modules-removed "Link to this heading") The following modules no longer exist: * No notable changes ### [Deprecation notices](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.17.html#id7) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.17.html#deprecation-notices "Link to this heading") No notable changes ### [Noteworthy module changes](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.17.html#id8) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.17.html#noteworthy-module-changes "Link to this heading") No notable changes [Plugins](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.17.html#id9) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.17.html#plugins "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- No notable changes [Porting custom scripts](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.17.html#id10) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.17.html#porting-custom-scripts "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ No notable changes [Networking](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.17.html#id11) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.17.html#networking "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ No notable changes --- # Ansible-core 2.16 Porting Guide — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * [Ansible Core Porting Guides](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/core_porting_guides.html) * Ansible-core 2.16 Porting Guide * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/porting_guides/porting_guide_core_2.16.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * [Ansible-core 2.16 Porting Guide](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.16.html#id1) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.16.html#ansible-core-2-16-porting-guide "Link to this heading") ===================================================================================================================================================================================================================================================================================================== This section discusses the behavioral changes between `ansible-core` 2.15 and `ansible-core` 2.16. It is intended to assist in updating your playbooks, plugins and other parts of your Ansible infrastructure so they will work with this version of Ansible. We suggest you read this page along with [ansible-core Changelog for 2.16](https://github.com/ansible/ansible/blob/stable-2.16/changelogs/CHANGELOG-v2.16.rst) to understand what updates you may need to make. This document is part of a collection on porting. The complete list of porting guides can be found at [porting guides](https://docs.ansible.com/projects/ansible/2.9/porting_guides/porting_guides.html#porting-guides "(in Ansible v2.9)") . [Playbook](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.16.html#id2) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.16.html#playbook "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * Conditionals - due to mitigation of security issue CVE-2023-5764 in ansible-core 2.16.1, conditional expressions with embedded template blocks can fail with the message “`Conditional is marked as unsafe, and cannot be evaluated.`” when an embedded template consults data from untrusted sources like module results or vars marked `!unsafe`. Conditionals with embedded templates can be a source of malicious template injection when referencing untrusted data, and can nearly always be rewritten without embedded templates. Playbook task conditional keywords such as `when` and `until` have long displayed warnings discouraging use of embedded templates in conditionals; this warning has been expanded to non-task conditionals as well, such as the `assert` action. \- name: task with a module result (always untrusted by Ansible) shell: echo "hi mom" register: untrusted\_result \# don't do it this way... \# - name: insecure conditional with embedded template consulting untrusted data \# assert: \# that: '"hi mom" is in {{ untrusted\_result.stdout }}' \- name: securely access untrusted values directly as Jinja variables instead assert: that: '"hi mom" is in untrusted\_result.stdout' [Command Line](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.16.html#id3) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.16.html#command-line "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- [Deprecated](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.16.html#id4) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.16.html#deprecated "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- [Modules](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.16.html#id5) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.16.html#modules "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [Modules removed](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.16.html#id6) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.16.html#modules-removed "Link to this heading") ### [Deprecation notices](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.16.html#id7) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.16.html#deprecation-notices "Link to this heading") ### [Noteworthy module changes](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.16.html#id8) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.16.html#noteworthy-module-changes "Link to this heading") [Plugins](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.16.html#id9) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.16.html#plugins "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- [Porting custom scripts](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.16.html#id10) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.16.html#porting-custom-scripts "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ [Networking](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.16.html#id11) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.16.html#networking "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ --- # Ansible-core 2.13 Porting Guide — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * [Ansible Core Porting Guides](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/core_porting_guides.html) * Ansible-core 2.13 Porting Guide * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/porting_guides/porting_guide_core_2.13.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * [Ansible-core 2.13 Porting Guide](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.13.html#id1) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.13.html#ansible-core-2-13-porting-guide "Link to this heading") ===================================================================================================================================================================================================================================================================================================== This section discusses the behavioral changes between `ansible-core` 2.12 and `ansible-core` 2.13. It is intended to assist in updating your playbooks, plugins and other parts of your Ansible infrastructure so they will work with this version of Ansible. We suggest you read this page along with [ansible-core Changelog for 2.13](https://github.com/ansible/ansible/blob/stable-2.13/changelogs/CHANGELOG-v2.13.rst) to understand what updates you may need to make. This document is part of a collection on porting. The complete list of porting guides can be found at [porting guides](https://docs.ansible.com/projects/ansible/2.9/porting_guides/porting_guides.html#porting-guides "(in Ansible v2.9)") . [Playbook](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.13.html#id2) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.13.html#playbook "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * Templating - You can no longer perform arithmetic and concatenation operations outside of the jinja template. The following statement will need to be rewritten to produce `[1, 2]`: > \- name: Prior to 2.13 > debug: > msg: '\[1\] + {{ \[2\] }}' > > \- name: 2.13 and forward > debug: > msg: '{{ \[1\] + \[2\] }}' * The return value of the `__repr__` method of an undefined variable represented by the `AnsibleUndefined` object changed. `{{ '%r'|format(undefined_variable) }}` returns `AnsibleUndefined(hint=None, obj=missing, name='undefined_variable')` in 2.13 as opposed to just `AnsibleUndefined` in versions 2.12 and prior. * The `finalize` method is no longer exposed in the globals for use in templating. To convert `None` to an empty string the following expression can be used: `{{ value if value is not none }}`. [Command Line](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.13.html#id3) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.13.html#command-line "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- No notable changes [Deprecated](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.13.html#id4) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.13.html#deprecated "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- No notable changes [Modules](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.13.html#id5) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.13.html#modules "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * To use ansible-core 2.13 for module execution, you must use Python 2 version 2.7 or Python 3 version 3.5 or newer. Any code utilizing `ansible.module_utils.basic` will not function with lower Python versions. ### [Modules removed](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.13.html#id6) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.13.html#modules-removed "Link to this heading") The following modules no longer exist: * No notable changes ### [Deprecation notices](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.13.html#id7) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.13.html#deprecation-notices "Link to this heading") No notable changes ### [Noteworthy module changes](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.13.html#id8) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.13.html#noteworthy-module-changes "Link to this heading") No notable changes ### [Breaking Changes](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.13.html#id9) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.13.html#breaking-changes "Link to this heading") * `ansible.module_utils.urls.fetch_url` will now return the captured `HTTPError` exception as `r`. `HTTPError` is a response like object that can offer more information to module authors. Modules should rely on `info['status'] >= 400` to determine if there was a failure, instead of using `r is None` or catching `AttributeError` when attempting `r.read()`. [Plugins](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.13.html#id10) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.13.html#plugins "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ No notable changes [Porting custom scripts](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.13.html#id11) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.13.html#porting-custom-scripts "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ No notable changes [Networking](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.13.html#id12) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.13.html#networking "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ No notable changes --- # Building Ansible inventories — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * Building Ansible inventories * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/inventory_guide/index.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Building Ansible inventories[](https://docs.ansible.com/projects/ansible/latest/inventory_guide/index.html#building-ansible-inventories "Link to this heading") ================================================================================================================================================================= Note **Making Open Source More Inclusive** 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) . Welcome to the guide to building Ansible inventories. An inventory is a list of managed nodes, or hosts, that Ansible deploys and configures. This guide introduces you to inventories and covers the following topics: * Creating inventories to track a list of servers and devices that you want to automate. * Using dynamic inventories to track cloud services with servers and devices that are constantly starting and stopping. * Using patterns to automate specific sub-sets of an inventory. * Expanding and refining the connection methods Ansible uses for your inventory. * [How to build your inventory](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html) * [Inventory basics: formats, hosts, and groups](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#inventory-basics-formats-hosts-and-groups) * [Passing multiple inventory sources](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#passing-multiple-inventory-sources) * [Organizing inventory in a directory](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#organizing-inventory-in-a-directory) * [Adding variables to inventory](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#adding-variables-to-inventory) * [Assigning a variable to one machine: host variables](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#assigning-a-variable-to-one-machine-host-variables) * [Defining variables in INI format](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#defining-variables-in-ini-format) * [Assigning a variable to many machines: group variables](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#assigning-a-variable-to-many-machines-group-variables) * [Organizing host and group variables](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#organizing-host-and-group-variables) * [How variables are merged](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#how-variables-are-merged) * [Connecting to hosts: behavioral inventory parameters](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#connecting-to-hosts-behavioral-inventory-parameters) * [Inventory setup examples](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#inventory-setup-examples) * [Working with dynamic inventory](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_dynamic_inventory.html) * [Inventory script example: Cobbler](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_dynamic_inventory.html#inventory-script-example-cobbler) * [Other inventory scripts](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_dynamic_inventory.html#other-inventory-scripts) * [Using inventory directories and multiple inventory sources](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_dynamic_inventory.html#using-inventory-directories-and-multiple-inventory-sources) * [Static groups of dynamic groups](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_dynamic_inventory.html#static-groups-of-dynamic-groups) * [Patterns: targeting hosts and groups](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_patterns.html) * [Using patterns](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_patterns.html#using-patterns) * [Common patterns](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_patterns.html#common-patterns) * [Limitations of patterns](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_patterns.html#limitations-of-patterns) * [Pattern processing order](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_patterns.html#pattern-processing-order) * [Advanced pattern options](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_patterns.html#advanced-pattern-options) * [Patterns and ad-hoc commands](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_patterns.html#patterns-and-ad-hoc-commands) * [Patterns and ansible-playbook flags](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_patterns.html#patterns-and-ansible-playbook-flags) * [Connection methods and details](https://docs.ansible.com/projects/ansible/latest/inventory_guide/connection_details.html) * [ControlPersist and paramiko](https://docs.ansible.com/projects/ansible/latest/inventory_guide/connection_details.html#controlpersist-and-paramiko) * [Setting a remote user](https://docs.ansible.com/projects/ansible/latest/inventory_guide/connection_details.html#setting-a-remote-user) * [Setting up SSH keys](https://docs.ansible.com/projects/ansible/latest/inventory_guide/connection_details.html#setting-up-ssh-keys) * [Running against localhost](https://docs.ansible.com/projects/ansible/latest/inventory_guide/connection_details.html#running-against-localhost) * [Managing host key checking](https://docs.ansible.com/projects/ansible/latest/inventory_guide/connection_details.html#managing-host-key-checking) * [Other connection methods](https://docs.ansible.com/projects/ansible/latest/inventory_guide/connection_details.html#other-connection-methods) --- # Creating a playbook — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * [Getting started with Ansible](https://docs.ansible.com/projects/ansible/latest/getting_started/index.html) * Creating a playbook * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/getting_started/get_started_playbook.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Creating a playbook[](https://docs.ansible.com/projects/ansible/latest/getting_started/get_started_playbook.html#creating-a-playbook "Link to this heading") ============================================================================================================================================================== Playbooks are automation blueprints, in `YAML` format, that Ansible uses to deploy and configure managed nodes. Playbook A list of plays that define the order in which Ansible performs operations, from top to bottom, to achieve an overall goal. Play An ordered list of tasks that maps to managed nodes in an inventory. Task A reference to a single module that defines the operations that Ansible performs. Module A unit of code or binary that Ansible runs on managed nodes. Ansible modules are grouped in collections with a [Fully Qualified Collection Name (FQCN)](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Fully-Qualified-Collection-Name-FQCN) for each module. Complete the following steps to create a playbook that pings your hosts and prints a “Hello world” message: 1. Create a file named `playbook.yaml` in your `ansible_quickstart` directory, that you created earlier, with the following content: \- name: My first play hosts: myhosts tasks: \- name: Ping my hosts ansible.builtin.ping: \- name: Print message ansible.builtin.debug: msg: Hello world 2. Run your playbook. ansible-playbook \-i inventory.ini playbook.yaml Ansible returns the following output: PLAY \[My first play\] \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\* TASK \[Gathering Facts\] \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\* ok: \[192.0.2.50\] ok: \[192.0.2.51\] ok: \[192.0.2.52\] TASK \[Ping my hosts\] \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\* ok: \[192.0.2.50\] ok: \[192.0.2.51\] ok: \[192.0.2.52\] TASK \[Print message\] \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\* ok: \[192.0.2.50\] => { "msg": "Hello world" } ok: \[192.0.2.51\] => { "msg": "Hello world" } ok: \[192.0.2.52\] => { "msg": "Hello world" } PLAY RECAP \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\* 192.0.2.50: ok=3 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 192.0.2.51: ok=3 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 192.0.2.52: ok=3 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 In this output you can see: * The names that you give the play and each task. You should always use descriptive names that make it easy to verify and troubleshoot playbooks. * The “Gathering Facts” task runs implicitly. By default, Ansible gathers information about your inventory that it can use in the playbook. * The status of each task. Each task has a status of `ok` which means it ran successfully. * The play recap that summarizes results of all tasks in the playbook per host. In this example, there are three tasks so `ok=3` indicates that each task ran successfully. Congratulations, you have started using Ansible! See also [Ansible playbooks](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_intro.html#playbooks-intro) Start building playbooks for real world scenarios. [Working with playbooks](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks.html#working-with-playbooks) Go into more detail with Ansible playbooks. [Ansible tips and tricks](https://docs.ansible.com/projects/ansible/latest/tips_tricks/index.html#playbooks-best-practices) Get tips and tricks for using playbooks. [Discovering variables: facts and magic variables](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_vars_facts.html#vars-and-facts) Learn more about the `gather_facts` keyword in playbooks. --- # Ansible concepts — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * [Getting started with Ansible](https://docs.ansible.com/projects/ansible/latest/getting_started/index.html) * Ansible concepts * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/getting_started/basic_concepts.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Ansible concepts[](https://docs.ansible.com/projects/ansible/latest/getting_started/basic_concepts.html#ansible-concepts "Link to this heading") ================================================================================================================================================== These concepts are common to all uses of Ansible. You should understand them before using Ansible or reading the documentation. [Control node](https://docs.ansible.com/projects/ansible/latest/getting_started/basic_concepts.html#id1) [](https://docs.ansible.com/projects/ansible/latest/getting_started/basic_concepts.html#control-node "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The machine from which you run the Ansible CLI tools (`ansible-playbook` , `ansible`, `ansible-vault` and others). You can use any computer that meets the software requirements as a control node - laptops, shared desktops, and servers can all run Ansible. You can also run Ansible in containers known as [Execution Environments](https://docs.ansible.com/projects/ansible/latest/getting_started_ee/index.html#getting-started-ee-index) . Multiple control nodes are possible, but Ansible itself does not coordinate across them, see `AAP` for such features. [Managed nodes](https://docs.ansible.com/projects/ansible/latest/getting_started/basic_concepts.html#id2) [](https://docs.ansible.com/projects/ansible/latest/getting_started/basic_concepts.html#managed-nodes "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Also referred to as ‘hosts’, these are the target devices (servers, network appliances or any computer) you aim to manage with Ansible. Ansible is not normally installed on managed nodes, unless you are using `ansible-pull`, but this is rare and not the recommended setup. [Inventory](https://docs.ansible.com/projects/ansible/latest/getting_started/basic_concepts.html#id3) [](https://docs.ansible.com/projects/ansible/latest/getting_started/basic_concepts.html#inventory "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- A list of managed nodes provided by one or more ‘inventory sources’. Your inventory can specify information specific to each node, like IP address. It is also used for assigning groups, that both allow for node selection in the Play and bulk variable assignment. To learn more about inventory, see [the Working with Inventory](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#intro-inventory) section. Sometimes an inventory source file is also referred to as a ‘hostfile’. [Playbooks](https://docs.ansible.com/projects/ansible/latest/getting_started/basic_concepts.html#id4) [](https://docs.ansible.com/projects/ansible/latest/getting_started/basic_concepts.html#playbooks "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- They contain Plays (which are the basic unit of Ansible execution). This is both an ‘execution concept’ and how we describe the files on which `ansible-playbook` operates. Playbooks are written in YAML and are easy to read, write, share and understand. To learn more about playbooks, see [Ansible playbooks](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_intro.html#about-playbooks) . ### [Plays](https://docs.ansible.com/projects/ansible/latest/getting_started/basic_concepts.html#id5) [](https://docs.ansible.com/projects/ansible/latest/getting_started/basic_concepts.html#plays "Link to this heading") The main context for Ansible execution, this playbook object maps managed nodes (hosts) to tasks. The Play contains variables, roles and an ordered lists of tasks and can be run repeatedly. It basically consists of an implicit loop over the mapped hosts and tasks and defines how to iterate over them. #### [Roles](https://docs.ansible.com/projects/ansible/latest/getting_started/basic_concepts.html#id6) [](https://docs.ansible.com/projects/ansible/latest/getting_started/basic_concepts.html#roles "Link to this heading") A limited distribution of reusable Ansible content (tasks, handlers, variables, plugins, templates and files) for use inside of a Play. To use any Role resource, the Role itself must be imported into the Play. #### [Tasks](https://docs.ansible.com/projects/ansible/latest/getting_started/basic_concepts.html#id7) [](https://docs.ansible.com/projects/ansible/latest/getting_started/basic_concepts.html#tasks "Link to this heading") The definition of an ‘action’ to be applied to the managed host. You can execute a single task once with an ad hoc command using `ansible` or `ansible-console` (both create a virtual Play). #### [Handlers](https://docs.ansible.com/projects/ansible/latest/getting_started/basic_concepts.html#id8) [](https://docs.ansible.com/projects/ansible/latest/getting_started/basic_concepts.html#handlers "Link to this heading") A special form of a Task, that only executes when notified by a previous task which resulted in a ‘changed’ status. [Modules](https://docs.ansible.com/projects/ansible/latest/getting_started/basic_concepts.html#id9) [](https://docs.ansible.com/projects/ansible/latest/getting_started/basic_concepts.html#modules "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The code or binaries that Ansible copies to and executes on each managed node (when needed) to accomplish the action defined in each Task. Each module has a particular use, from administering users on a specific type of database to managing VLAN interfaces on a specific type of network device. You can invoke a single module with a task, or invoke several different modules in a playbook. Ansible modules are grouped in collections. For an idea of how many collections Ansible includes, see the [Collection Index](https://docs.ansible.com/projects/ansible/latest/collections/index.html#list-of-collections) . [Plugins](https://docs.ansible.com/projects/ansible/latest/getting_started/basic_concepts.html#id10) [](https://docs.ansible.com/projects/ansible/latest/getting_started/basic_concepts.html#plugins "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ Pieces of code that expand Ansible’s core capabilities. Plugins can control how you connect to a managed node (connection plugins), manipulate data (filter plugins) and even control what is displayed in the console (callback plugins). See [Working with plugins](https://docs.ansible.com/projects/ansible/latest/plugins/plugins.html#working-with-plugins) for details. [Collections](https://docs.ansible.com/projects/ansible/latest/getting_started/basic_concepts.html#id11) [](https://docs.ansible.com/projects/ansible/latest/getting_started/basic_concepts.html#collections "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- A format in which Ansible content is distributed that can contain playbooks, roles, modules, and plugins. You can install and use collections through [Ansible Galaxy](https://galaxy.ansible.com/) . To learn more about collections, see [Using Ansible collections](https://docs.ansible.com/projects/ansible/latest/collections_guide/index.html#collections) . Collection resources can be used independently and discretely from each other. --- # Introduction to Execution Environments — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * [Getting started with Execution Environments](https://docs.ansible.com/projects/ansible/latest/getting_started_ee/index.html) * Introduction to Execution Environments * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/getting_started_ee/introduction.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Introduction to Execution Environments[](https://docs.ansible.com/projects/ansible/latest/getting_started_ee/introduction.html#introduction-to-execution-environments "Link to this heading") =============================================================================================================================================================================================== Ansible Execution Environments aim to resolve complexity issues and provide all the benefits you can get from containerization. Reducing complexity[](https://docs.ansible.com/projects/ansible/latest/getting_started_ee/introduction.html#reducing-complexity "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------- There are three main areas where EEs can reduce complexity: * software dependencies * portability * content separation ### Dependencies[](https://docs.ansible.com/projects/ansible/latest/getting_started_ee/introduction.html#dependencies "Link to this heading") Software applications typically have dependencies, and Ansible is no exception. These dependencies can include software libraries, configuration files or other services, to name a few. Traditionally, administrators install application dependencies on top of an operating system using packaging management tools such as RPM or Python-pip. The major drawback of such an approach is that an application might require versions of dependencies different from those provided by default. For Ansible, a typical installation consists of ansible-core and a set of Ansible collections. Many of them have dependencies for the plugins, modules, roles and playbooks they provide. The Ansible collections can depend on the following pieces of software and their versions: * `ansible-core` * Python * Python packages * System packages * Other Ansible collections The dependencies have to be installed and sometimes can conflict with each other. One way to **partially** resolve the dependency issue is to use Python virtual environments on Ansible control nodes. However, applied to Ansible, virtual environments have drawbacks and natural limitations. ### Portability[](https://docs.ansible.com/projects/ansible/latest/getting_started_ee/introduction.html#portability "Link to this heading") An Ansible user writes content for Ansible locally and wants to leverage the container technology to make their automation runtimes portable, shareable and easily deployable to testing and production environments. ### Content separation[](https://docs.ansible.com/projects/ansible/latest/getting_started_ee/introduction.html#content-separation "Link to this heading") In situations when there is an Ansible control node or a tool such as Ansible AWX/Controller used by several users, they might want separate their content to avoid configuration and dependency conflicts. Ansible tooling for EEs[](https://docs.ansible.com/projects/ansible/latest/getting_started_ee/introduction.html#ansible-tooling-for-ees "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------- Projects in the Ansible ecosystem also provide several tools that you can use with EEs, such as: * [Ansible Builder](https://ansible-builder.readthedocs.io/en/stable/) * [Ansible Navigator](https://ansible-navigator.readthedocs.io/) * [Ansible AWX](https://ansible.readthedocs.io/projects/awx/en/latest/userguide/execution_environments.html#use-an-execution-environment-in-jobs) * [Ansible Runner](https://ansible-runner.readthedocs.io/en/stable/) * [VS Code Ansible](https://marketplace.visualstudio.com/items?itemName=redhat.ansible) * [Dev Containers extensions](https://code.visualstudio.com/docs/devcontainers/containers) Ready to get started with EEs? Proceed to [Setting up your environment](https://docs.ansible.com/projects/ansible/latest/getting_started_ee/setup_environment.html#setting-up-ee-environment) . --- # Running Ansible with the community EE image — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * [Getting started with Execution Environments](https://docs.ansible.com/projects/ansible/latest/getting_started_ee/index.html) * Running Ansible with the community EE image * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/getting_started_ee/run_community_ee_image.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Running Ansible with the community EE image[](https://docs.ansible.com/projects/ansible/latest/getting_started_ee/run_community_ee_image.html#running-ansible-with-the-community-ee-image "Link to this heading") =================================================================================================================================================================================================================== You can run ansible without the need to build a custom EE using community images. Use the `community-ee-minimal` image that includes only `ansible-core` or the `community-ee-base` image that also includes several base collections. Run the following command to see the collections included in the `community-ee-base` image: ansible-navigator collections \--execution-environment-image ghcr.io/ansible-community/community-ee-base:latest Run the following Ansible ad-hoc command against localhost inside the `community-ee-minimal` container: ansible-navigator exec "ansible localhost -m setup" \--execution-environment-image ghcr.io/ansible-community/community-ee-minimal:latest \--mode stdout Now, create a simple test playbook and run it against `localhost` inside the container: \- name: Gather and print local facts hosts: localhost become: true gather\_facts: true tasks: \- name: Print facts ansible.builtin.debug: var: ansible\_facts ansible-navigator run test\_localhost.yml \--execution-environment-image ghcr.io/ansible-community/community-ee-minimal:latest \--mode stdout See also * [Building your first Execution Environment](https://docs.ansible.com/projects/ansible/latest/getting_started_ee/build_execution_environment.html#building-execution-environment) * [Running your EE](https://docs.ansible.com/projects/ansible/latest/getting_started_ee/run_execution_environment.html#running-custom-execution-environment) * [Ansible Navigator documentation](https://ansible-navigator.readthedocs.io/) --- # Setting up your environment — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * [Getting started with Execution Environments](https://docs.ansible.com/projects/ansible/latest/getting_started_ee/index.html) * Setting up your environment * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/getting_started_ee/setup_environment.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Setting up your environment[](https://docs.ansible.com/projects/ansible/latest/getting_started_ee/setup_environment.html#setting-up-your-environment "Link to this heading") ============================================================================================================================================================================== Complete the following steps to set up a local environment for your first Execution Environment: 1. Ensure the following packages are installed on your system: > * `podman` or `docker` > > * `python3` > > * `python3-pip` > > > If you use the DNF package manager, install these prerequisites as follows: > > sudo dnf install \-y podman python3 python3-pip 2. Install `ansible-navigator`: > pip3 install ansible-navigator > > Installing `ansible-navigator` lets you run EEs on the command line. It includes the `ansible-builder` package to build EEs. > > If you want to build EEs without testing, install only `ansible-builder`: > > pip3 install ansible-builder 3. Verify your environment with the following commands: > ansible-navigator \--version > ansible-builder \--version Ready to build an EE in a few easy steps? Proceed to [Building your first Execution Environment](https://docs.ansible.com/projects/ansible/latest/getting_started_ee/build_execution_environment.html#building-execution-environment) . Want to try an EE without having to build one? Proceed to [Running Ansible with the community EE image](https://docs.ansible.com/projects/ansible/latest/getting_started_ee/run_community_ee_image.html#running-community-execution-environment) . --- # Protecting sensitive data with Ansible vault — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * Protecting sensitive data with Ansible vault * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/vault_guide/index.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Protecting sensitive data with Ansible vault[](https://docs.ansible.com/projects/ansible-core/devel/vault_guide/index.html#protecting-sensitive-data-with-ansible-vault "Link to this heading") ================================================================================================================================================================================================= Note **Making Open Source More Inclusive** 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) . Welcome to the Ansible vault documentation. Ansible vault provides a way to encrypt and manage sensitive data such as passwords. This guide introduces you to Ansible vault and covers the following topics: * Managing vault passwords. * Encrypting content and files with Ansible vault. * Using encrypted variables and files. * [Ansible Vault](https://docs.ansible.com/projects/ansible-core/devel/vault_guide/vault.html) * [Managing vault passwords](https://docs.ansible.com/projects/ansible-core/devel/vault_guide/vault_managing_passwords.html) * [Choosing between a single password and multiple passwords](https://docs.ansible.com/projects/ansible-core/devel/vault_guide/vault_managing_passwords.html#choosing-between-a-single-password-and-multiple-passwords) * [Managing multiple passwords with vault IDs](https://docs.ansible.com/projects/ansible-core/devel/vault_guide/vault_managing_passwords.html#managing-multiple-passwords-with-vault-ids) * [Storing and accessing vault passwords](https://docs.ansible.com/projects/ansible-core/devel/vault_guide/vault_managing_passwords.html#storing-and-accessing-vault-passwords) * [Encrypting content with Ansible Vault](https://docs.ansible.com/projects/ansible-core/devel/vault_guide/vault_encrypting_content.html) * [Encrypting individual variables with Ansible Vault](https://docs.ansible.com/projects/ansible-core/devel/vault_guide/vault_encrypting_content.html#encrypting-individual-variables-with-ansible-vault) * [Encrypting files with Ansible Vault](https://docs.ansible.com/projects/ansible-core/devel/vault_guide/vault_encrypting_content.html#encrypting-files-with-ansible-vault) * [Using encrypted variables and files](https://docs.ansible.com/projects/ansible-core/devel/vault_guide/vault_using_encrypted_content.html) * [Passing a single password](https://docs.ansible.com/projects/ansible-core/devel/vault_guide/vault_using_encrypted_content.html#passing-a-single-password) * [Passing vault IDs](https://docs.ansible.com/projects/ansible-core/devel/vault_guide/vault_using_encrypted_content.html#passing-vault-ids) * [Passing multiple vault passwords](https://docs.ansible.com/projects/ansible-core/devel/vault_guide/vault_using_encrypted_content.html#passing-multiple-vault-passwords) * [Using `--vault-id` without a vault ID](https://docs.ansible.com/projects/ansible-core/devel/vault_guide/vault_using_encrypted_content.html#using-vault-id-without-a-vault-id) * [Configuring defaults for using encrypted content](https://docs.ansible.com/projects/ansible-core/devel/vault_guide/vault_using_encrypted_content.html#configuring-defaults-for-using-encrypted-content) * [Setting a default vault ID](https://docs.ansible.com/projects/ansible-core/devel/vault_guide/vault_using_encrypted_content.html#setting-a-default-vault-id) * [Setting a default password source](https://docs.ansible.com/projects/ansible-core/devel/vault_guide/vault_using_encrypted_content.html#setting-a-default-password-source) * [When are encrypted files made visible?](https://docs.ansible.com/projects/ansible-core/devel/vault_guide/vault_using_encrypted_content.html#when-are-encrypted-files-made-visible) * [Format of files encrypted with Ansible Vault](https://docs.ansible.com/projects/ansible-core/devel/vault_guide/vault_using_encrypted_content.html#format-of-files-encrypted-with-ansible-vault) * [Ansible Vault payload format 1.1 - 1.2](https://docs.ansible.com/projects/ansible-core/devel/vault_guide/vault_using_encrypted_content.html#ansible-vault-payload-format-1-1-1-2) --- # Ansible Community Guide — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * Ansible Community Guide * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/community/index.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Ansible Community Guide[](https://docs.ansible.com/projects/ansible-core/devel/community/index.html#ansible-community-guide "Link to this heading") ===================================================================================================================================================== Note **Making Open Source More Inclusive** 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) . Welcome to the Ansible Community Guide! In the Ansible community, our mission is to produce, maintain, and popularize simple, flexible, and powerful open-source software tools tailored to automating a large variety of tasks. We strive to innovate in making infrastructure configuration and management as effortless and efficient as possible with automation, enabling people to focus on their core objectives. We welcome members from all skill levels to participate in our open, inclusive, and vibrant community. Whether you are an expert or just beginning your journey with Ansible, you are encouraged to contribute, share insights, and collaborate with fellow enthusiasts! The purpose of this guide is to teach you everything you need to know about being a contributing member of the Ansible community. All types of contributions are welcome and necessary for Ansible’s continued success. * [Getting started](https://docs.ansible.com/projects/ansible-core/devel/community/getting_started.html) * [Community Code of Conduct](https://docs.ansible.com/projects/ansible-core/devel/community/code_of_conduct.html) * [Developer Certificate Of Origin](https://docs.ansible.com/projects/ansible-core/devel/community/developer_certificate_of_origin.html) * [Communicating with the Ansible community](https://docs.ansible.com/projects/ansible-core/devel/community/communication.html) * [How can I help?](https://docs.ansible.com/projects/ansible-core/devel/community/how_can_I_help.html) * [Other ways to get involved](https://docs.ansible.com/projects/ansible-core/devel/community/getting_started.html#other-ways-to-get-involved) * [Contributor path](https://docs.ansible.com/projects/ansible-core/devel/community/contributor_path.html) * [Determine your area of interest](https://docs.ansible.com/projects/ansible-core/devel/community/contributor_path.html#determine-your-area-of-interest) * [Find the corresponding project](https://docs.ansible.com/projects/ansible-core/devel/community/contributor_path.html#find-the-corresponding-project) * [Learn](https://docs.ansible.com/projects/ansible-core/devel/community/contributor_path.html#learn) * [Making your first contribution](https://docs.ansible.com/projects/ansible-core/devel/community/contributor_path.html#making-your-first-contribution) * [Continue to contribute](https://docs.ansible.com/projects/ansible-core/devel/community/contributor_path.html#continue-to-contribute) * [Teach others](https://docs.ansible.com/projects/ansible-core/devel/community/contributor_path.html#teach-others) * [Become a collection maintainer](https://docs.ansible.com/projects/ansible-core/devel/community/contributor_path.html#become-a-collection-maintainer) * [Become a steering committee member](https://docs.ansible.com/projects/ansible-core/devel/community/contributor_path.html#become-a-steering-committee-member) --- # Ansible Core Porting Guides — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * Ansible Core Porting Guides * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/porting_guides/core_porting_guides.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Ansible Core Porting Guides[](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/core_porting_guides.html#ansible-core-porting-guides "Link to this heading") ================================================================================================================================================================================ This section lists porting guides that can help you in updating playbooks, plugins and other parts of your Ansible infrastructure from one version of `ansible-core` to the next. Please note that this is not a complete list. If you believe any extra information would be useful in these pages, you can edit by clicking Edit on GitHub on the top right, or raising an issue. * [Ansible-core 2.21 Porting Guide](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.21.html) * [Ansible-core 2.20 Porting Guide](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.20.html) * [Ansible-core 2.19 Porting Guide](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html) * [Ansible-core 2.18 Porting Guide](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.18.html) * [Ansible-core 2.17 Porting Guide](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.17.html) * [Ansible-core 2.16 Porting Guide](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.16.html) * [Ansible-core 2.15 Porting Guide](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.15.html) * [Ansible-core 2.14 Porting Guide](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.14.html) * [Ansible-core 2.13 Porting Guide](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.13.html) * [Ansible-core 2.12 Porting Guide](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.12.html) * [Ansible-core 2.11 Porting Guide](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.11.html) * [Ansible-base 2.10 Porting Guide](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_base_2.10.html) --- # Using Ansible command line tools — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * Using Ansible command line tools * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/command_guide/index.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Using Ansible command line tools[](https://docs.ansible.com/projects/ansible-core/devel/command_guide/index.html#using-ansible-command-line-tools "Link to this heading") =========================================================================================================================================================================== Note **Making Open Source More Inclusive** 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) . Welcome to the guide for using Ansible command line tools. Ansible provides ad hoc commands and several utilities for performing various operations and automation tasks. * [Introduction to ad hoc commands](https://docs.ansible.com/projects/ansible-core/devel/command_guide/intro_adhoc.html) * [Why use ad hoc commands?](https://docs.ansible.com/projects/ansible-core/devel/command_guide/intro_adhoc.html#why-use-ad-hoc-commands) * [Use cases for ad hoc tasks](https://docs.ansible.com/projects/ansible-core/devel/command_guide/intro_adhoc.html#use-cases-for-ad-hoc-tasks) * [Working with command line tools](https://docs.ansible.com/projects/ansible-core/devel/command_guide/command_line_tools.html) * [ansible](https://docs.ansible.com/projects/ansible-core/devel/cli/ansible.html) * [ansible-config](https://docs.ansible.com/projects/ansible-core/devel/cli/ansible-config.html) * [ansible-console](https://docs.ansible.com/projects/ansible-core/devel/cli/ansible-console.html) * [ansible-doc](https://docs.ansible.com/projects/ansible-core/devel/cli/ansible-doc.html) * [ansible-galaxy](https://docs.ansible.com/projects/ansible-core/devel/cli/ansible-galaxy.html) * [ansible-inventory](https://docs.ansible.com/projects/ansible-core/devel/cli/ansible-inventory.html) * [ansible-playbook](https://docs.ansible.com/projects/ansible-core/devel/cli/ansible-playbook.html) * [ansible-pull](https://docs.ansible.com/projects/ansible-core/devel/cli/ansible-pull.html) * [ansible-vault](https://docs.ansible.com/projects/ansible-core/devel/cli/ansible-vault.html) * [Ansible CLI cheatsheet](https://docs.ansible.com/projects/ansible-core/devel/command_guide/cheatsheet.html) * [ansible-playbook](https://docs.ansible.com/projects/ansible-core/devel/command_guide/cheatsheet.html#ansible-playbook) * [ansible-galaxy](https://docs.ansible.com/projects/ansible-core/devel/command_guide/cheatsheet.html#ansible-galaxy) * [ansible](https://docs.ansible.com/projects/ansible-core/devel/command_guide/cheatsheet.html#ansible) * [ansible-doc](https://docs.ansible.com/projects/ansible-core/devel/command_guide/cheatsheet.html#ansible-doc) See also [Ansible Navigator](https://ansible.readthedocs.io/projects/navigator/) A command-line tool and a TUI that provides a convenient user interface for most of the native Ansible command-line utilities and allows to run Ansible automation content inside containers ([Execution Environments](https://docs.ansible.com/projects/ansible/12/getting_started_ee/index.html#getting-started-ee-index "(in Ansible v12)") ) --- # Advanced Contributor Guide — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * Advanced Contributor Guide * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/community/advanced_index.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Advanced Contributor Guide[](https://docs.ansible.com/projects/ansible/latest/community/advanced_index.html#advanced-contributor-guide "Link to this heading") ================================================================================================================================================================ This guide focuses on contributors who are committers, GitHub admins, release managers, or Ansible ecosystem project developers. * [Committers Guidelines](https://docs.ansible.com/projects/ansible/latest/community/committer_guidelines.html) * [GitHub Admins](https://docs.ansible.com/projects/ansible/latest/community/github_admins.html) * [Ansible Ecosystem Project Development Resources](https://docs.ansible.com/projects/ansible/latest/community/ecosystem_project_resources.html) --- # Installing Ansible on specific operating systems — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * [Installation Guide](https://docs.ansible.com/projects/ansible/latest/installation_guide/index.html) * Installing Ansible on specific operating systems * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/installation_guide/installation_distros.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Installing Ansible on specific operating systems[](https://docs.ansible.com/projects/ansible/latest/installation_guide/installation_distros.html#installing-ansible-on-specific-operating-systems "Link to this heading") =========================================================================================================================================================================================================================== Note These instructions come from their respective communities. If you encounter bugs or issues, file them with that community to update these instructions. Ansible maintains only the `pip install` instructions. You can always [install the ansible package from PyPI using pip](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#intro-installation-guide) on most systems. The community also packages and maintains Ansible for various Linux distributions. This guide shows you how to install Ansible from different distribution package repositories. Requirements for adding new distributions[](https://docs.ansible.com/projects/ansible/latest/installation_guide/installation_distros.html#requirements-for-adding-new-distributions "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Package maintainers who want to add instructions for another distribution to this guide must meet the following requirements: * Ensure the distribution provides a reasonably up-to-date version of `ansible`. * Keep `ansible-core` and `ansible` versions synchronized to the extent that the build system allows. * Provide a way to contact the distribution maintainers as part of the instructions. * Distribution maintainers are also encouraged to join and monitor the [Ansible Packaging](https://matrix.to/#/#packaging:ansible.com) Matrix room. Installing Ansible on Fedora Linux[](https://docs.ansible.com/projects/ansible/latest/installation_guide/installation_distros.html#installing-ansible-on-fedora-linux "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Fedora Linux provides both the full Ansible package and the minimal ansible-core package through the standard repositories. Install the full `ansible` package: $ sudo dnf install ansible Install the minimal `ansible-core` package: $ sudo dnf install ansible-core Fedora repositories include several Ansible collections as standalone packages that you can install alongside `ansible-core`. For example, install the `community.general` collection: $ sudo dnf install ansible-collection-community-general See the [Fedora Packages index](https://packages.fedoraproject.org/search?query=ansible-collection) for a complete list of Ansible collections packaged in Fedora. Contact the package maintainers by [filing a bug](https://bugzilla.redhat.com/enter_bug.cgi) against the `Fedora` product in Red Hat Bugzilla. Installing Ansible from EPEL[](https://docs.ansible.com/projects/ansible/latest/installation_guide/installation_distros.html#installing-ansible-from-epel "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- If you use CentOS Stream, Almalinux, Rocky Linux, or related distributions, you can install `ansible` or Ansible collections from the community-maintained [EPEL](https://docs.fedoraproject.org/en-US/epel/) (Extra Packages for Enterprise Linux) repository: 1. [Enable the EPEL repository](https://docs.fedoraproject.org/en-US/epel/#_quickstart) . 2. Use the same `dnf` commands as for Fedora Linux. Contact the package maintainers by [filing a bug](https://bugzilla.redhat.com/enter_bug.cgi) against the `Fedora EPEL` product in Red Hat Bugzilla. Installing Ansible on OpenSUSE Tumbleweed/Leap[](https://docs.ansible.com/projects/ansible/latest/installation_guide/installation_distros.html#installing-ansible-on-opensuse-tumbleweed-leap "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- OpenSUSE provides Ansible packages through the standard package manager. $ sudo zypper install ansible See the [OpenSUSE Support Portal](https://en.opensuse.org/Portal:Support) for additional help with Ansible on OpenSUSE. Installing Ansible on Ubuntu[](https://docs.ansible.com/projects/ansible/latest/installation_guide/installation_distros.html#installing-ansible-on-ubuntu "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Ubuntu provides Ansible packages through a Personal Package Archive (PPA) that contains more recent versions than the standard repositories. Ubuntu builds are available [in a PPA here](https://launchpad.net/~ansible/+archive/ubuntu/ansible) . Configure the PPA on your system and install Ansible: $ sudo apt update $ sudo apt install software-properties-common $ sudo add-apt-repository \--yes \--update ppa:ansible/ansible $ sudo apt install ansible File any issues in [the PPA’s issue tracker](https://github.com/ansible-community/ppa/issues) . Installing Ansible on Debian[](https://docs.ansible.com/projects/ansible/latest/installation_guide/installation_distros.html#installing-ansible-on-debian "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Debian users can choose between the standard repository or the Ubuntu PPA for more recent versions. While Ansible is available from the [main Debian repository](https://packages.debian.org/stable/ansible) , this version can be outdated. For a more recent version, Debian users can use the Ubuntu PPA according to the following table: | Debian | | Ubuntu | UBUNTU\_CODENAME | | --- | --- | --- | --- | | Debian 13 (Trixie) | \-> | Ubuntu 24.04 (Noble) | `noble` | | Debian 12 (Bookworm) | \-> | Ubuntu 22.04 (Jammy) | `jammy` | | Debian 11 (Bullseye) | \-> | Ubuntu 20.04 (Focal) | `focal` | The following example assumes that you already have `wget` and `gpg` installed. Add the repository and install Ansible. Set `UBUNTU_CODENAME=...` based on the table above (we use `jammy` in this example): $ UBUNTU\_CODENAME\=jammy $ wget \-O- "https://keyserver.ubuntu.com/pks/lookup?fingerprint=on&op=get&search=0x6125E2A8C77F2818FB7BD15B93C4A3FD7BB9C367" | sudo gpg \--dearmor \-o /usr/share/keyrings/ansible-archive-keyring.gpg $ echo "deb \[signed-by=/usr/share/keyrings/ansible-archive-keyring.gpg\] http://ppa.launchpad.net/ansible/ansible/ubuntu $UBUNTU\_CODENAME main" | sudo tee /etc/apt/sources.list.d/ansible.list $ sudo apt update && sudo apt install ansible Note Use double quotes around the keyserver URL and in the “echo deb” command like in the example above. These commands download the signing key and add an entry to apt’s sources pointing to the PPA. Previously, you may have used `apt-key add`. The `apt-key add` approach is now [deprecated](https://askubuntu.com/a/1307181) for security reasons (on Debian, Ubuntu, and elsewhere). As such, we do NOT add the key to `/etc/apt/trusted.gpg.d/` or to `/etc/apt/trusted.gpg` where the key would be allowed to sign releases from ANY repository. Installing Ansible on Arch Linux[](https://docs.ansible.com/projects/ansible/latest/installation_guide/installation_distros.html#installing-ansible-on-arch-linux "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Arch Linux provides both the full Ansible package and ansible-core through the standard package repositories. Install the full `ansible` package: $ sudo pacman \-S ansible Install the minimal `ansible-core` package: $ sudo pacman \-S ansible-core Arch Linux repositories include several Ansible ecosystem packages as standalone packages that you can install alongside `ansible-core`. See the [Arch Linux Packages index](https://archlinux.org/packages/?sort=&q=ansible) for a complete list of Ansible packages in Arch Linux. Contact the package maintainers by [opening an issue](https://gitlab.archlinux.org/archlinux/packaging/packages) in the related package GitLab repository. Installing Ansible on Windows[](https://docs.ansible.com/projects/ansible/latest/installation_guide/installation_distros.html#installing-ansible-on-windows "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You cannot use a Windows system for the Ansible control node. See [Using Windows as the control node](https://docs.ansible.com/projects/ansible/latest/os_guide/intro_windows.html#windows-control-node) See also [Installing Ansible on Arch Linux](https://wiki.archlinux.org/title/Ansible#Installation) Distro-specific installation on Arch Linux [Installing Ansible on Clear Linux](https://clearlinux.org/software/bundle/ansible) Distro-specific installation on Clear Linux --- # YAML Syntax — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * YAML Syntax * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/reference_appendices/YAMLSyntax.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * YAML Syntax[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/YAMLSyntax.html#yaml-syntax "Link to this heading") ========================================================================================================================================= This page provides a basic overview of correct YAML syntax, which is how Ansible playbooks (our configuration management language) are expressed. We use YAML because it is easier for humans to read and write than other common data formats like XML or JSON. Further, there are libraries available in most programming languages for working with YAML. You may also wish to read [Working with playbooks](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks.html#working-with-playbooks) at the same time to see how this is used in practice. YAML Basics[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/YAMLSyntax.html#yaml-basics "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------- For Ansible, nearly every YAML file starts with a list. Each item in the list is a list of key/value pairs, commonly called a “hash” or a “dictionary”. So, we need to know how to write lists and dictionaries in YAML. There’s another small quirk to YAML. All YAML files (regardless of their association with Ansible or not) can optionally begin with `---` and end with `...`. This is part of the YAML format and indicates the start and end of a document. All members of a list are lines beginning at the same indentation level starting with a `"- "` (a dash and a space): \--- \# A list of tasty fruits \- Apple \- Orange \- Strawberry \- Mango ... A dictionary is represented in a simple `key: value` form (the colon must be followed by a space): \# An employee record martin: name: Martin D'vloper job: Developer skill: Elite More complicated data structures are possible, such as lists of dictionaries, dictionaries whose values are lists or a mix of both: \# Employee records \- martin: name: Martin D'vloper job: Developer skills: \- python \- perl \- pascal \- tabitha: name: Tabitha Bitumen job: Developer skills: \- lisp \- fortran \- erlang Dictionaries and lists can also be represented in an abbreviated form if you really want to: \--- martin: {name: Martin D'vloper, job: Developer, skill: Elite} fruits: \['Apple', 'Orange', 'Strawberry', 'Mango'\] These are called “Flow collections”. Ansible doesn’t really use these too much, but you can also specify a [boolean value](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#playbooks-variables) (true/false) in several forms: create\_key: true needs\_agent: false knows\_oop: True likes\_emacs: TRUE uses\_cvs: false Use lowercase ‘true’ or ‘false’ for boolean values in dictionaries if you want to be compatible with default yamllint options. Values can span multiple lines using `|` or `>`. Spanning multiple lines using a “Literal Block Scalar” `|` will include the newlines and any trailing spaces. Using a “Folded Block Scalar” `>` will fold newlines to spaces; it is used to make what would otherwise be a very long line easier to read and edit. In either case the indentation will be ignored. Examples are: include\_newlines: | exactly as you see will appear these three lines of poetry fold\_newlines: \> this is really a single line of text despite appearances While in the above `>` example all newlines are folded into spaces, there are two ways to enforce a newline to be kept: fold\_some\_newlines: \> a b c d e f Alternatively, it can be enforced by including newline `\n` characters: fold\_same\_newlines: "a b\\nc d\\n e\\nf\\n" Let’s combine what we learned so far in an arbitrary YAML example. This really has nothing to do with Ansible, but will give you a feel for the format: \--- \# An employee record name: Martin D'vloper job: Developer skill: Elite employed: True foods: \- Apple \- Orange \- Strawberry \- Mango languages: perl: Elite python: Elite pascal: Lame education: | 4 GCSEs 3 A-Levels BSc in the Internet of Things That’s all you really need to know about YAML to start writing Ansible playbooks. Gotchas[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/YAMLSyntax.html#gotchas "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------- While you can put just about anything into an unquoted scalar, there are some exceptions. A colon followed by a space (or newline) `": "` is an indicator for a mapping. A space followed by the pound sign `" #"` starts a comment. Because of this, the following is going to result in a YAML syntax error: foo: somebody said I should put a colon here: so I did windows\_drive: c: …but this will work: windows\_path: c:\\windows You will want to quote hash values using colons followed by a space or the end of the line: foo: 'somebody said I should put a colon here: so I did' windows\_drive: 'c:' …and then the colon will be preserved. Alternatively, you can use double quotes: foo: "somebody said I should put a colon here: so I did" windows\_drive: "c:" The difference between single quotes and double quotes is that in double quotes you can use escapes: foo: "a \\t TAB and a \\n NEWLINE" The list of allowed escapes can be found in the YAML Specification under “Escape Sequences” (YAML 1.1) or “Escape Characters” (YAML 1.2). The following is invalid YAML: foo: "an escaped \\' single quote" Further, Ansible uses “{{ var }}” for variables. If a value after a colon starts with a “{”, YAML will think it is a dictionary, so you must quote it, like so: foo: "{{ variable }}" If your value starts with a quote the entire value must be quoted, not just part of it. Here are some additional examples of how to properly quote things: foo: "{{ variable }}/additional/string/literal" foo2: "{{ variable }}\\\\backslashes\\\\are\\\\also\\\\special\\\\characters" foo3: "even if it is just a string literal it must all be quoted" Not valid: foo: "E:\\\\path\\\\"rest\\\\of\\\\path In addition to `'` and `"` there are a number of characters that are special (or reserved) and cannot be used as the first character of an unquoted scalar: ``[] {} > | * & ! % # ` @ ,``. You should also be aware of `? : -`. In YAML, they are allowed at the beginning of a string if a non-space character follows, but YAML processor implementations differ, so it is better to use quotes. In Flow Collections, the rules are a bit more strict: a scalar in block mapping: this } is \[ all , valid\ \ flow mapping: { key: "you { should \[ use , quotes here" }\ \ Boolean conversion is helpful, but this can be a problem when you want a literal yes or other boolean values as a string. In these cases just use quotes:\ \ non\_boolean: "yes"\ other\_string: "False"\ \ YAML converts certain strings into floating-point values, such as the string 1.0. If you need to specify a version number (in a requirements.yml file, for example), you will need to quote the value if it looks like a floating-point value:\ \ version: "1.0"\ \ See also\ \ [Working with playbooks](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks.html#working-with-playbooks)\ \ Learn what playbooks can do and how to write/run them.\ \ [YAMLLint](http://yamllint.com/)\ \ YAML Lint (online) helps you debug YAML syntax if you are having problems\ \ [Wikipedia YAML syntax reference](https://en.wikipedia.org/wiki/YAML)\ \ A good guide to YAML syntax\ \ [YAML 1.1 Specification](https://yaml.org/spec/1.1/)\ \ The Specification for YAML 1.1, which PyYAML and libyaml are currently implementing\ \ [YAML 1.2 Specification](https://yaml.org/spec/1.2/spec.html)\ \ For completeness, YAML 1.2 is the successor of 1.1\ \ [Communication](https://docs.ansible.com/projects/ansible/latest/community/communication.html#communication)\ \ Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide --- # Controlling how Ansible behaves: precedence rules — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * Controlling how Ansible behaves: precedence rules * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/reference_appendices/general_precedence.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Controlling how Ansible behaves: precedence rules[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/general_precedence.html#controlling-how-ansible-behaves-precedence-rules "Link to this heading") ============================================================================================================================================================================================================================ To give you maximum flexibility in managing your environments, Ansible offers many ways to control how Ansible behaves: how it connects to managed nodes, how it works once it has connected. If you use Ansible to manage a large number of servers, network devices, and cloud resources, you may define Ansible behavior in several different places and pass that information to Ansible in several different ways. This flexibility is convenient, but it can backfire if you do not understand the precedence rules. These precedence rules apply to any setting that can be defined in multiple ways (by configuration settings, command-line options, playbook keywords, variables). [Precedence categories](https://docs.ansible.com/projects/ansible/latest/reference_appendices/general_precedence.html#id1) [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/general_precedence.html#precedence-categories "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Ansible offers four sources for controlling its behavior. In order of precedence from lowest (most easily overridden) to highest (overrides all others), the categories are: > * Configuration settings > > * Command-line options > > * Playbook keywords > > * Variables > > * Direct Assignment > Each category overrides any information from all lower-precedence categories. For example, a playbook keyword will override any configuration setting. Within each precedence category, specific rules apply. However, generally speaking, ‘last defined’ wins and overrides any previous definitions. ### [Configuration settings](https://docs.ansible.com/projects/ansible/latest/reference_appendices/general_precedence.html#id2) [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/general_precedence.html#configuration-settings "Link to this heading") [Configuration settings](https://docs.ansible.com/projects/ansible/latest/reference_appendices/config.html#ansible-configuration-settings) include both values from the `ansible.cfg` file and environment variables. Within this category, values set in configuration files have lower precedence. Ansible uses the first `ansible.cfg` file it finds, ignoring all others. Ansible searches for `ansible.cfg` in these locations in order: > * `ANSIBLE_CONFIG` (environment variable if set) > > * `ansible.cfg` (in the current directory) > > * `~/.ansible.cfg` (in the home directory) > > * `/etc/ansible/ansible.cfg` > Environment variables have a higher precedence than entries in `ansible.cfg`. If you have environment variables set on your control node, they override the settings in whichever `ansible.cfg` file Ansible loads. The value of any given environment variable follows normal shell precedence: the last value defined overwrites previous values. ### [Command-line options](https://docs.ansible.com/projects/ansible/latest/reference_appendices/general_precedence.html#id3) [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/general_precedence.html#command-line-options "Link to this heading") Any command-line option will override any configuration setting. When you type something directly at the command line, you may feel that your hand-crafted values should override all others, but Ansible does not work that way. Command-line options have low precedence - they override configuration only. They do not override playbook keywords, variables from inventory or variables from playbooks. You can override all other settings from all other sources in all other precedence categories at the command line by [Using -e extra variables at the command line](https://docs.ansible.com/projects/ansible/latest/reference_appendices/general_precedence.html#general-precedence-extra-vars) , but that is not a command-line option, it is a way of passing a [variable](https://docs.ansible.com/projects/ansible/latest/reference_appendices/general_precedence.html#general-precedence-variables) . At the command line, if you pass multiple values for a parameter that accepts only a single value, the last defined value wins. For example, this [ad hoc task](https://docs.ansible.com/projects/ansible/latest/command_guide/intro_adhoc.html#intro-adhoc) will connect as `carol`, not as `mike`: ansible \-u mike \-m ping myhost \-u carol Some parameters allow multiple values. In this case, Ansible will append all values from the hosts listed in inventory files inventory1 and inventory2: ansible \-i /path/inventory1 \-i /path/inventory2 \-m ping all The help for each [command-line tool](https://docs.ansible.com/projects/ansible/latest/command_guide/command_line_tools.html#command-line-tools) lists available options for that tool. ### [Playbook keywords](https://docs.ansible.com/projects/ansible/latest/reference_appendices/general_precedence.html#id4) [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/general_precedence.html#playbook-keywords "Link to this heading") Any [playbook keyword](https://docs.ansible.com/projects/ansible/latest/reference_appendices/playbooks_keywords.html#playbook-keywords) will override any command-line option and any configuration setting. Within playbook keywords, precedence flows with the playbook itself; the more specific wins against the more general: * play (most general) * blocks/includes/imports/roles (optional and can contain tasks and each other) * tasks (most specific) A simple example: \- hosts: all connection: ssh tasks: \- name: This task uses ssh. ping: \- name: This task uses paramiko. connection: paramiko ping: In this example, the `connection` keyword is set to `ssh` at the play level. The first task inherits that value, and connects using `ssh`. The second task inherits that value, overrides it, and connects using `paramiko`. The same logic applies to blocks and roles as well. All tasks, blocks, and roles within a play inherit play-level keywords; any task, block, or role can override any keyword by defining a different value for that keyword within the task, block, or role. Remember that these are KEYWORDS, not variables. Both playbooks and variable files are defined in YAML but they have different significance. Playbooks are the command or ‘state description’ structure for Ansible, variables are data we use to help make playbooks more dynamic. ### [Variables](https://docs.ansible.com/projects/ansible/latest/reference_appendices/general_precedence.html#id5) [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/general_precedence.html#variables "Link to this heading") Ansible variables are very high on the precedence stack. They will override any playbook keyword, any command-line option, environment variable and any configuration file setting. Variables that have equivalent playbook keywords, command-line options, and configuration settings are known as [Connection variables](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#connection-variables) . Originally designed for connection parameters, this category has expanded to include other core variables like the temporary directory and the python interpreter. Connection variables, like all variables, can be set in multiple ways and places. You can define variables for hosts and groups in [inventory](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#intro-inventory) . You can define variables for tasks and plays in `vars:` blocks in [playbooks](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_intro.html#about-playbooks) . However, they are still variables - they are data, not keywords or configuration settings. Variables that override playbook keywords, command-line options, and configuration settings follow the same rules of [variable precedence](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#ansible-variable-precedence) as any other variables. When set in a playbook, variables follow the same inheritance rules as playbook keywords. You can set a value for the play, then override it in a task, block, or role: \- hosts: cloud gather\_facts: false become: true vars: ansible\_become\_user: admin tasks: \- name: This task uses admin as the become user. dnf: name: some-service state: latest \- block: \- name: This task uses service-admin as the become user. \# a task to configure the new service \- name: This task also uses service-admin as the become user, defined in the block. \# second task to configure the service vars: ansible\_become\_user: service-admin \- name: This task (outside of the block) uses admin as the become user again. service: name: some-service state: restarted #### [Variable scope: how long is a value available?](https://docs.ansible.com/projects/ansible/latest/reference_appendices/general_precedence.html#id6) [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/general_precedence.html#variable-scope-how-long-is-a-value-available "Link to this heading") Variable values set in a playbook exist only within the playbook object that defines them. These ‘playbook object scope’ variables are not available to subsequent objects, including other plays. Variable values associated directly with a host or group, including variables defined in inventory, by vars plugins, or using modules like [set\_fact](https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/set_fact_module.html#set-fact-module) and [include\_vars](https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/include_vars_module.html#include-vars-module) , are available to all plays. These ‘host scope’ variables are also available through the `hostvars[]` dictionary. Variables set through `extra vars` have a global scope for the current run and will be present both as ‘playbook object vars’ and ‘hostvars’. #### [Using `-e` extra variables at the command line](https://docs.ansible.com/projects/ansible/latest/reference_appendices/general_precedence.html#id7) [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/general_precedence.html#using-e-extra-variables-at-the-command-line "Link to this heading") To override all other variables, you can use extra variables: `--extra-vars` or `-e` at the command line. Values passed with `-e`, while still a command-line option itself, have the highest precedence among variables and will, a bit counter intuitively, be of the higher precedence among most configuration sources, since variables themselves have high precedence. For example, this task will connect as `brian` not as `carol`: ansible \-u carol \-e 'ansible\_user=brian' \-a whoami all You must specify both the variable name and the value with `--extra-vars`. ### [Direct Assignment](https://docs.ansible.com/projects/ansible/latest/reference_appendices/general_precedence.html#id8) [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/general_precedence.html#direct-assignment "Link to this heading") This category only applies to things that take direct options, generally modules and some plugin types. Most modules and action plugins do not have any other way to assign settings so precedence rarely comes up in that context, but it still possible for some of them to do so and should be reflected in the documentation. \- debug: msg='this is a direct assignment option to an action plugin' \- ping: data: also a direct assignment Outside of task actions, the most recognizable ‘direct assignments’ are with lookup, filter and test plugins: lookup('plugin', direct1='value', direct2='value2') 'value\_directly\_assigned'|filter('another directly assigned') 'direct value' is testplugin Though most of these are not configured in other ways, specially tests, it is possible for plugins and filters to use input from other configuration sources if specified in their documentation. Inventory plugins are a bit tricky as they use ‘inventory sources’ and these sometimes can look like a configuration file and are passed in as a command line option, yet it is still considered ‘direct assignment’. It is a bit clearer when using an inline source `-i host1, host2, host3` than when using a file source `-i /path/to/inventory_source`, but they both have the same precedence. --- # Glossary — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * Glossary * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/reference_appendices/glossary.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Glossary[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#glossary "Link to this heading") ===================================================================================================================================== The following is a list (and re-explanation) of term definitions used elsewhere in the Ansible documentation. Consult the documentation home page for the full documentation and to see the terms in context, but this should be a good resource to check your knowledge of Ansible’s components and understand how they fit together. It is something you might wish to read for review or when a term comes up on the [Ansible Forum](https://docs.ansible.com/projects/ansible-core/devel/community/communication.html#ansible-forum) . Action[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Action "Link to this term") An action is a part of a task that specifies which of the modules to run and which arguments to pass to that module. Each task can have only one action, but it may also have other parameters. Ad Hoc[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Ad-Hoc "Link to this term") Refers to running Ansible to perform some quick command, using **/usr/bin/ansible**, rather than the [orchestration](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Orchestration) language, which is **/usr/bin/ansible-playbook**. An example of an ad hoc command might be rebooting 50 machines in your infrastructure. Anything you can do ad hoc can be accomplished by writing a [playbook](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Playbooks) and playbooks can also glue several other operations together. Ansible (the package)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Ansible-the-package "Link to this term") A software package (Python, deb, rpm, and so on) that contains ansible-core and a select group of collections. Playbooks that worked with Ansible 2.9 should still work with the Ansible 2.10 package. See the `ansible-.build` file in the release-specific directory at [ansible-build-data](https://github.com/ansible-community/ansible-build-data) for a list of collections included in Ansible, as well as the included `ansible-core` version. ansible-base[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-ansible-base "Link to this term") Used only for 2.10. The installable package (RPM/Python/Deb package) generated from the [ansible/ansible repository](https://github.com/ansible/ansible) . See `ansible-core`. ansible-core[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-ansible-core "Link to this term") Name used starting with 2.11. The installable package (RPM/Python/Deb package) generated from the [ansible/ansible repository](https://github.com/ansible/ansible) . Contains the command-line tools and the code for basic features and functions, such as copying module code to managed nodes. The `ansible-core` package includes a few modules and plugins and allows you to add others by installing collections. Ansible Galaxy[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Ansible-Galaxy "Link to this term") An [online distribution server](https://galaxy.ansible.com/ui/) for finding and sharing Ansible community content, sometimes referred to as community Galaxy. Also, the command-line utility that lets users install individual Ansible Collections, for example `ansible-galaxy collection install community.crypto`. Async[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Async "Link to this term") Refers to a task that is configured to run in the background rather than waiting for completion. If you have a long process that would run longer than the SSH timeout, it would make sense to launch that task in async mode. Async modes can poll for completion every so many seconds or can be configured to “fire and forget”, in which case Ansible will not even check on the task again; it will just kick it off and proceed to future steps. Async modes work with both **/usr/bin/ansible** and **/usr/bin/ansible-playbook**. Callback Plugin[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Callback-Plugin "Link to this term") Refers to some user-written code that can intercept results from Ansible and do something with them. Some supplied examples in the GitHub project perform custom logging, send email, or even play sound effects. Check Mode[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Check-Mode "Link to this term") Refers to running Ansible with the `--check` option, which does not make any changes on the remote systems, but only outputs the changes that might occur if the command ran without this flag. This is analogous to so-called “dry run” modes in other systems, though the user should be warned that this does not take into account unexpected command failures or cascade effects (which is true of similar modes in other systems). Use this to get an idea of what might happen, but do not substitute it for a good staging environment. Collection[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Collection "Link to this term") A packaging format for bundling and distributing Ansible content, including plugins, roles, modules, and more. Collections release independent of other collections or `ansible-core` so features can be available sooner to users. Some collections are packaged with Ansible (version 2.10 or later). You can install other collections (or other versions of collections) with `ansible-galaxy collection install `. Collection name[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Collection-name "Link to this term") The second part of a Fully Qualified Collection Name. The collection name divides the collection namespace and usually reflects the function of the collection content. For example, the `cisco` namespace might contain `cisco.ios`, `cisco.aci`, and `cisco.nxos`, with content for managing the different network devices maintained by Cisco. community.general (collection)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-community.general-collection "Link to this term") A special collection managed by the Ansible Community Team containing all the modules and plugins which shipped in Ansible 2.9 that do not have their own dedicated Collection. See [community.general](https://galaxy.ansible.com/community/general) on Galaxy. community.network (collection)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-community.network-collection "Link to this term") Similar to `community.general`, focusing on network content. [community.network](https://galaxy.ansible.com/community/network) on Galaxy. Connection Plugin[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Connection-Plugin "Link to this term") By default, Ansible talks to remote machines through pluggable libraries. Ansible uses native OpenSSH ([SSH (Native)](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-SSH-Native) ) or a Python implementation called [paramiko](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-paramiko) . OpenSSH is preferred if you are using a recent version, and also enables some features like Kerberos and jump hosts. This is covered in the [getting started section](https://docs.ansible.com/projects/ansible/2.9/user_guide/intro_getting_started.html#remote-connection-information "(in Ansible v2.9)") . There are also other connection types like `accelerate` mode, which must be bootstrapped over one of the SSH-based connection types but is very fast, and local mode, which acts on the local system. Users can also write their own connection plugins. Conditionals[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Conditionals "Link to this term") A conditional is an expression that evaluates to true or false that decides whether a given task is executed on a given machine or not. Ansible’s conditionals are powered by the ‘when’ statement, which are discussed in the [Working with playbooks](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks.html#working-with-playbooks) . Declarative[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Declarative "Link to this term") An approach to achieving a task that uses a description of the final state rather than a description of the sequence of steps necessary to achieve that state. For a real world example, a declarative specification of a task would be: “put me in California”. Depending on your current location, the sequence of steps to get you to California may vary, and if you are already in California, nothing at all needs to be done. Ansible’s Resources are declarative; it figures out the steps needed to achieve the final state. It also lets you know whether or not any steps needed to be taken to get to the final state. Diff Mode[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Diff-Mode "Link to this term") A `--diff` flag can be passed to Ansible to show what changed on modules that support it. You can combine it with `--check` to get a good ‘dry run’. File diffs are normally in unified diff format. Distribution server[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Distribution-server "Link to this term") A server, such as Ansible Galaxy or Red Hat Automation Hub where you can distribute your collections and allow others to access these collections. See [Distributing collections](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_collections_distributing.html#distributing-collections) for a list of distribution server types. Some Ansible features are only available on certain distribution servers. Executor[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Executor "Link to this term") A core software component of Ansible that is the power behind **/usr/bin/ansible** directly – and corresponds to the invocation of each task in a [playbook](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Playbooks) . The Executor is something Ansible developers may talk about, but it is not really user land vocabulary. Facts[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Facts "Link to this term") Facts are simply things that are discovered about remote nodes. While they can be used in [playbooks](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Playbooks) and templates just like variables, facts are things that are inferred, rather than set. Facts are automatically discovered by Ansible when running plays by executing the internal [setup module](https://docs.ansible.com/projects/ansible-core/devel/collections/ansible/builtin/setup_module.html#setup-module) on the remote nodes. You never have to call the setup module explicitly, it just runs, but it can be disabled to save time if it is not needed or you can tell ansible to collect only a subset of the full facts through the `gather_subset:` option. For the convenience of users who are switching from other configuration management systems, the fact module will also pull in facts from the **ohai** and **facter** tools if they are installed. These are fact libraries from Chef and Puppet, respectively. (These may also be disabled through `gather_subset:`) Filter Plugin[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Filter-Plugin "Link to this term") A filter plugin is something that most users will never need to understand. These allow for the creation of new [Jinja2](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Jinja2) filters, which are more or less only of use to people who know what Jinja2 filters are. If you need them, you can learn how to write them in the [API docs section](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_plugins.html#developing-filter-plugins) . Forks[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Forks "Link to this term") Ansible talks to remote nodes in parallel and the level of parallelism can be set either by passing `--forks` or editing the default in a configuration file. The default is a very conservative five (5) forks, though if you have a lot of RAM, you can easily set this to a value like 50 for increased parallelism. Fully Qualified Collection Name (FQCN)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Fully-Qualified-Collection-Name-FQCN "Link to this term") The full definition of a module, plugin, or role hosted within a collection, in the form . Allows a Playbook to refer to a specific module or plugin from a specific source in an unambiguous manner, for example, `community.grafana.grafana_dashboard`. The FQCN is required when you want to specify the exact source of a plugin. For example, if multiple collections contain a module plugin called `user`, the FQCN specifies which one to use for a given task. When you have multiple collections installed, the FQCN is always the explicit and authoritative indicator of which collection to search for the correct plugin for each task. Gather Facts (Boolean)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Gather-Facts-Boolean "Link to this term") [Facts](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Facts) are mentioned above. Sometimes when running a multi-play [playbook](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Playbooks) , it is desirable to have some plays that don’t bother with fact computation if they aren’t going to need to utilize any of these values. Setting `gather_facts: False` on a playbook allows this implicit fact gathering to be skipped. Globbing[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Globbing "Link to this term") Globbing is a way to select several hosts based on wildcards, rather than the name of the host specifically, or the name of the group they are in. For example, it is possible to select `ww*` to match all hosts starting with `www`. This concept is pulled directly from **Func**, one of Michael DeHaan’s (an Ansible Founder) earlier projects. In addition to basic globbing, various set operations are also possible, such as ‘hosts in this group and not in another group’, and so on. Group[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Group "Link to this term") A group consists of several hosts assigned to a pool that can be conveniently targeted together, as well as given variables that they share in common. Group Vars[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Group-Vars "Link to this term") The `group_vars/` files are files that live in a directory alongside an inventory file, with an optional file name named after each group. This is a convenient place to put variables that are provided to a given group, especially complex data structures, so that these variables do not have to be embedded in the [inventory](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Inventory) file or [playbook](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Playbooks) . Handlers[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Handlers "Link to this term") Handlers are just like regular tasks in an Ansible [playbook](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Playbooks) (see [Tasks](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Tasks) ) but are only run if the Task contains a `notify` keyword and also indicates that it changed something. For example, if a config file is changed, then the task referencing the config file templating operation may notify a service restart handler. This means services can be bounced only if they need to be restarted. Handlers can be used for things other than service restarts, but service restarts are the most common usage. Host[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Host "Link to this term") A host is simply a remote machine that Ansible manages. They can have individual variables assigned to them, and can also be organized in groups. All hosts have a name they can be reached at (which is either an IP address or a domain name) and, optionally, a port number, if they are not to be accessed on the default SSH port. Host Specifier[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Host-Specifier "Link to this term") Each [Play](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Plays) in Ansible maps a series of [tasks](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Tasks) (which define the role, purpose, or orders of a system) to a set of systems. This `hosts:` keyword in each play is often called the hosts specifier. It may select one system, many systems, one or more groups, or even some hosts that are in one group and explicitly not in another. Host Vars[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Host-Vars "Link to this term") Just like [Group Vars](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Group-Vars) , a directory alongside the inventory file named `host_vars/` can contain a file named after each hostname in the inventory file, in [YAML](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-YAML) format. This provides a convenient place to assign variables to the host without having to embed them in the [inventory](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Inventory) file. The Host Vars file can also be used to define complex data structures that can’t be represented in the inventory file. Idempotency[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Idempotency "Link to this term") An operation is idempotent if the result of performing it once is exactly the same as the result of performing it repeatedly without any intervening actions. Includes[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Includes "Link to this term") The idea that [playbook](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Playbooks) files (which are nothing more than lists of [plays](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Plays) ) can include other lists of plays, and task lists can externalize lists of [tasks](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Tasks) in other files, and similarly with [handlers](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Handlers) . Includes can be parameterized, which means that the loaded file can pass variables. For example, an included play for setting up a WordPress blog may take a parameter called `user` and that play could be included more than once to create a blog for both `alice` and `bob`. Inventory[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Inventory "Link to this term") A file (by default, Ansible uses a simple INI format) that describes [Hosts](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Host) and [Groups](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Group) in Ansible. Inventory can also be provided through an [Inventory Script](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Inventory-Script) (sometimes called an “External Inventory Script”). Inventory Script[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Inventory-Script "Link to this term") A very simple program (or a complicated one) that looks up [hosts](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Host) , [group](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Group) membership for hosts, and variable information from an external resource – whether that be a SQL database, a CMDB solution, or something like LDAP. This concept was adapted from Puppet (where it is called an “External Nodes Classifier”) and works more or less exactly the same way. Jinja2[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Jinja2 "Link to this term") Jinja2 is the preferred templating language of Ansible’s template module. It is a very simple Python template language that is generally readable and easy to write. JSON[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-JSON "Link to this term") Ansible uses JSON for return data from remote modules. This allows modules to be written in any language, not just Python. Keyword[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Keyword "Link to this term") The main expressions that make up Ansible, which apply to playbook objects (Play, Block, Role and Task). For example ‘vars:’ is a keyword that lets you define variables in the scope of the playbook object it is applied to. Lazy Evaluation[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Lazy-Evaluation "Link to this term") In general, Ansible evaluates any variables in [playbook](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Playbooks) content at the last possible second, which means that if you define a data structure that data structure itself can define variable values within it, and everything “just works” as you would expect. This also means variable strings can include other variables inside of those strings. Library[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Library "Link to this term") A collection of modules made available to **/usr/bin/ansible** or an Ansible [playbook](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Playbooks) . Limit Groups[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Limit-Groups "Link to this term") By passing `--limit somegroup` to **ansible** or **ansible-playbook**, the commands can be limited to a subset of [hosts](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Host) . For example, this can be used to run a [playbook](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Playbooks) that normally targets an entire set of servers to one particular server. Local Action[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Local-Action "Link to this term") This keyword is an alias for `delegate_to: localhost`. Used when you want to redirect an action from the remote to execute on the control node itself. Local Connection[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Local-Connection "Link to this term") By using `connection: local` in a [playbook](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Playbooks) , or passing `-c local` to **/usr/bin/ansible**, this indicates that we are executing a local fork instead of executing on the remote machine. You probably want `local_action` or `delegate_to: localhost` instead as this ONLY changes the connection and no other context for execution. Lookup Plugin[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Lookup-Plugin "Link to this term") A lookup plugin is a way to get data into Ansible from the outside world. Lookup plugins are an extension of Jinja2 and can be accessed in templates, for example, `{{ lookup('file','/path/to/file') }}`. These are how such things as `with_items`, are implemented. There are also lookup plugins like `file` which loads data from a file and ones for querying environment variables, DNS text records, or key value stores. Loops[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Loops "Link to this term") Generally, Ansible is not a programming language. It prefers to be more declarative, though various constructs like `loop` allow a particular task to be repeated for multiple items in a list. Certain modules, like [yum](https://docs.ansible.com/projects/ansible/2.9/modules/yum_module.html#yum-module "(in Ansible v2.9)") and [apt](https://docs.ansible.com/projects/ansible-core/devel/collections/ansible/builtin/apt_module.html#apt-module) , actually take lists directly, and can install all packages given in those lists within a single transaction, dramatically speeding up total time to configuration, so they can be used without loops. Modules[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Modules "Link to this term") Modules are the units of work that Ansible ships out to remote machines. Modules are kicked off by either **/usr/bin/ansible** or **/usr/bin/ansible-playbook** (where multiple tasks use several different modules in conjunction). Modules can be implemented in any language, including Perl, Bash, or Ruby – but can take advantage of some useful communal library code if written in Python. Modules just have to return [JSON](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-JSON) . Once modules are executed on remote machines, they are removed, so no long running daemons are used. Ansible refers to the collection of available modules as a [library](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Library) . Multi-Tier[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Multi-Tier "Link to this term") The concept that IT systems are not managed one system at a time, but by interactions between multiple systems and groups of systems in well defined orders. For example, a web server may need to be updated before a database server and pieces on the web server may need to be updated after _THAT_ database server and various load balancers and monitoring servers may need to be contacted. Ansible models entire IT topologies and workflows rather than looking at configuration from a “one system at a time” perspective. Namespace[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Namespace "Link to this term") The first part of a fully qualified collection name, the namespace usually reflects a functional content category. Example: in `cisco.ios.ios_config`, `cisco` is the namespace. Namespaces are reserved and distributed by Red Hat at Red Hat’s discretion. Many, but not all, namespaces will correspond with vendor names. See [Galaxy namespaces](https://galaxy.ansible.com/docs/contributing/namespaces.html#galaxy-namespaces) on the Galaxy docsite for namespace requirements. Notify[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Notify "Link to this term") The act of a [task](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Tasks) registering a change event and informing a [handler](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Handlers) task that another [action](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Action) needs to be run at the end of the [play](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Plays) . If a handler is notified by multiple tasks, it will still be run only once. Handlers are run in the order they are listed, not in the order that they are notified. Orchestration[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Orchestration "Link to this term") Many software automation systems use this word to mean different things. Ansible uses it as a conductor would conduct an orchestra. A datacenter or cloud architecture is full of many systems, playing many parts – web servers, database servers, maybe load balancers, monitoring systems, continuous integration systems, and so on. In performing any process, it is necessary to touch systems in particular orders, often to simulate rolling updates or to deploy software correctly. Some system may perform some steps, then others, then previous systems already processed may need to perform more steps. Along the way, emails may need to be sent or web services contacted. Ansible orchestration is all about modeling that kind of process. paramiko[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-paramiko "Link to this term") Ansible can use a Python SSH implementation called `paramiko`. The paramiko library is generally fast and easy to manage. To use paramiko you need to specify the connection type in your [playbooks](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Playbooks) , or by using the `-c paramiko` flag. Playbooks[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Playbooks "Link to this term") Playbooks are the language by which Ansible orchestrates, configures, administers, or deploys systems. They are called playbooks partially because it is a sports analogy, and it is supposed to be fun using them. They aren’t workbooks :) Plays[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Plays "Link to this term") A [playbook](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Playbooks) is a list of plays. A play is minimally a mapping between a set of [hosts](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Host) selected by a host specifier (usually chosen by [groups](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Group) but sometimes by hostname [globs](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Globbing) ) and the [tasks](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Tasks) which run on those hosts to define the role that those systems will perform. There can be one or many plays in a playbook. Pull Mode[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Pull-Mode "Link to this term") By default, Ansible runs in [push mode](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Push-Mode) , which allows it very fine-grained control over when it talks to each system. Pull mode is provided for when you would rather have nodes check in every N minutes on a particular schedule. It uses a program called **ansible-pull** and can also be set up (or reconfigured) using a push-mode [playbook](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Playbooks) . Most Ansible users use push mode, but pull mode is included for variety and the sake of having choices. **ansible-pull** works by checking configuration orders out of Git on a crontab and then managing the machine locally, using the [local connection](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Local-Connection) plugin. Pulp 3 Galaxy[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Pulp-3-Galaxy "Link to this term") A self-hosted distribution server based on the [GalaxyNG codebase](https://galaxyng.netlify.app/) , based on Pulp version 3. Use it to find and share your own curated set of content. You can access your content with the `ansible-galaxy collection` command. Push Mode[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Push-Mode "Link to this term") Push mode is the default mode of Ansible. In fact, it is not really a mode at all – it is just how Ansible works when you aren’t thinking about it. Push mode allows Ansible to be fine-grained and conduct nodes through complex orchestration processes without waiting for them to check in. Register Variable[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Register-Variable "Link to this term") The result of running any [task](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Tasks) in Ansible can be stored in a variable for use in a template or a conditional statement. The keyword used to define the variable is called `register`, taking its name from the idea of registers in assembly programming (though Ansible will never feel like assembly programming). There are an infinite number of variable names you can use for registration. Resource Model[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Resource-Model "Link to this term") Ansible modules work in terms of resources. For example, the [file module](https://docs.ansible.com/projects/ansible-core/devel/collections/ansible/builtin/file_module.html#file-module) will select a particular file and ensure that the attributes of that resource match a particular model. As an example, we might wish to change the owner of `/etc/motd` to `root` if it is not already set to `root`, or set its mode to `0644` if it is not already set to `0644`. The resource models are [idempotent](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Idempotency) meaning change commands are not run unless needed, and Ansible will bring the system back to a desired state regardless of the actual state – rather than you having to tell it how to get to the state. Roles[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Roles "Link to this term") Roles are units of organization in Ansible. Assigning a role to a group of [hosts](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Host) (or a set of [groups](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Group) , or [host patterns](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Globbing) , and so on) implies that they should implement a specific behavior. A role may include applying certain variable values, certain [tasks](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Tasks) , and certain [handlers](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Handlers) – or just one or more of these things. Because of the file structure associated with a role, roles become redistributable units that allow you to share behavior among [playbooks](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Playbooks) – or even with other users. Rolling Update[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Rolling-Update "Link to this term") The act of addressing a number of nodes in a group N at a time to avoid updating them all at once and bringing the system offline. For instance, in a web topology of 500 nodes handling very large volume, it may be reasonable to update 10 or 20 machines at a time, moving on to the next 10 or 20 when done. The `serial:` keyword in an Ansible [playbooks](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Playbooks) control the size of the rolling update pool. The default is to address the batch size all at once, so this is something that you must opt-in to. OS configuration (such as making sure config files are correct) does not typically have to use the rolling update model, but can do so if desired. Serial[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Serial "Link to this term") See also [Rolling Update](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Rolling-Update) Sudo[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Sudo "Link to this term") Ansible does not require root logins, and since it is daemonless, definitely does not require root level daemons (which can be a security concern in sensitive environments). Ansible can log in and perform many operations wrapped in a sudo command, and can work with both password-less and password-based sudo. Some operations that don’t normally work with sudo (like scp file transfer) can be achieved with Ansible’s [copy](https://docs.ansible.com/projects/ansible-core/devel/collections/ansible/builtin/copy_module.html#copy-module) , [template](https://docs.ansible.com/projects/ansible-core/devel/collections/ansible/builtin/template_module.html#template-module) , and [fetch](https://docs.ansible.com/projects/ansible-core/devel/collections/ansible/builtin/fetch_module.html#fetch-module) modules while running in sudo mode. SSH (Native)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-SSH-Native "Link to this term") Native OpenSSH as an Ansible transport is specified with `-c ssh` (or a config file, or a keyword in the [playbook](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Playbooks) ) and can be useful if wanting to login through Kerberized SSH or using SSH jump hosts, and so on. In 1.2.1, `ssh` will be used by default if the OpenSSH binary on the control machine is sufficiently new. Previously, Ansible selected `paramiko` as a default. Using a client that supports `ControlMaster` and `ControlPersist` is recommended for maximum performance – if you don’t have that and don’t need Kerberos, jump hosts, or other features, `paramiko` is a good choice. Ansible will warn you if it doesn’t detect ControlMaster/ControlPersist capability. Tags[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Tags "Link to this term") Ansible allows tagging resources in a [playbook](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Playbooks) with arbitrary keywords, and then running only the parts of the playbook that correspond to those keywords. For example, it is possible to have an entire OS configuration, and have certain steps labeled `ntp`, and then run just the `ntp` steps to reconfigure the time server information on a remote host. Task[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Task "Link to this term") [Playbooks](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Playbooks) exist to run tasks. Tasks combine an [action](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Action) (a module and its arguments) with a name and optionally some other keywords (like [looping keywords](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Loops) ). [Handlers](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Handlers) are also tasks, but they are a special kind of task that do not run unless they are notified by name when a task reports an underlying change on a remote system. Tasks[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Tasks "Link to this term") A list of [Task](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Task) . Templates[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Templates "Link to this term") Ansible can easily transfer files to remote systems but often it is desirable to substitute variables in other files. Variables may come from the [inventory](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Inventory) file, [Host Vars](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Host-Vars) , [Group Vars](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Group-Vars) , or [Facts](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Facts) . Templates use the [Jinja2](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Jinja2) template engine and can also include logical constructs like loops and if statements. Transport[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Transport "Link to this term") Ansible uses :term:`Connection Plugins` to define types of available transports. These are simply how Ansible will reach out to managed systems. Transports included are [paramiko](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-paramiko) , [ssh](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-SSH-Native) (using OpenSSH), and [local](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Local-Connection) . When[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-When "Link to this term") An optional conditional statement attached to a [task](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Tasks) that is used to determine if the task should run or not. If the expression following the `when:` keyword evaluates to false, the task will be ignored. Vars (Variables)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Vars-Variables "Link to this term") As opposed to [Facts](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Facts) , variables are names of values (they can be simple scalar values – integers, booleans, strings) or complex ones (dictionaries/hashes, lists) that can be used in templates and [playbooks](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Playbooks) . They are declared things, not things that are inferred from the remote system’s current state or nature (which is what Facts are). YAML[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-YAML "Link to this term") Ansible does not want to force people to write programming language code to automate infrastructure, so Ansible uses YAML to define [playbook](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/glossary.html#term-Playbooks) configuration languages and also variable files. YAML is nice because it has a minimum of syntax and is very clean and easy for people to skim. It is a good data format for configuration files and humans, but also machine readable. Ansible’s usage of YAML stemmed from Michael DeHaan’s first use of it inside of Cobbler around 2006. YAML is fairly popular in the dynamic language community and the format has libraries available for serialization in many languages (Python, Perl, Ruby, and so on). See also [Frequently Asked Questions](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#ansible-faq) Frequently asked questions [Working with playbooks](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks.html#working-with-playbooks) An introduction to playbooks [Ansible tips and tricks](https://docs.ansible.com/projects/ansible-core/devel/tips_tricks/index.html#playbooks-best-practices) Tips and tricks for playbooks [Communication](https://docs.ansible.com/projects/ansible-core/devel/community/communication.html#communication) Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide --- # Introduction to Ansible — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * [Getting started with Ansible](https://docs.ansible.com/projects/ansible/latest/getting_started/index.html) * Introduction to Ansible * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/getting_started/introduction.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Introduction to Ansible[](https://docs.ansible.com/projects/ansible/latest/getting_started/introduction.html#introduction-to-ansible "Link to this heading") ============================================================================================================================================================== Ansible provides open-source automation that reduces complexity and runs everywhere. Using Ansible lets you automate virtually any task. Here are some common use cases for Ansible: * Eliminate repetition and simplify workflows * Manage and maintain system configuration * Continuously deploy complex software * Perform zero-downtime rolling updates Ansible uses simple, human-readable scripts called playbooks to automate your tasks. You declare the desired state of a local or remote system in your playbook. Ansible ensures that the system remains in that state. As automation technology, Ansible is designed around the following principles: Agent-less architecture Low maintenance overhead by avoiding the installation of additional software across IT infrastructure. Simplicity Automation playbooks use straightforward YAML syntax for code that reads like documentation. Ansible is also decentralized, using SSH with existing OS credentials to access remote machines. Scalability and flexibility Easily and quickly scale the systems you automate through a modular design that supports a large range of operating systems, cloud platforms, and network devices. Idempotence and predictability When the system is in the state your playbook describes, Ansible does not change anything, even if the playbook runs multiple times. Ready to start using Ansible? [Get up and running in a few easy steps](https://docs.ansible.com/projects/ansible/latest/getting_started/get_started_ansible.html#get-started-ansible) . --- # Start automating with Ansible — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * [Getting started with Ansible](https://docs.ansible.com/projects/ansible/latest/getting_started/index.html) * Start automating with Ansible * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/getting_started/get_started_ansible.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Start automating with Ansible[](https://docs.ansible.com/projects/ansible/latest/getting_started/get_started_ansible.html#start-automating-with-ansible "Link to this heading") ================================================================================================================================================================================= Get started with Ansible by creating an automation project, building an inventory, and creating a “Hello World” playbook. 1. Install Ansible. pip install ansible 2. Create a project folder on your filesystem. mkdir ansible\_quickstart && cd ansible\_quickstart Using a single directory structure makes it easier to add to source control as well as to reuse and share automation content. Continue getting started with Ansible by [building an inventory](https://docs.ansible.com/projects/ansible/latest/getting_started/get_started_inventory.html#get-started-inventory) . See also [Installing Ansible](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#installation-guide) Installation guide with instructions for installing Ansible on various operating systems [Ansible Demos](https://github.com/ansible/product-demos) Demonstrations of different Ansible usecases [Ansible Labs](https://www.ansible.com/products/ansible-training) Labs to provide further knowledge on different topics [Ansible Communication Guide](https://docs.ansible.com/projects/ansible/latest/community/communication.html#communication) Questions? Help? Ideas? Ask the community --- # Ansible-core 2.15 Porting Guide — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * [Ansible Core Porting Guides](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/core_porting_guides.html) * Ansible-core 2.15 Porting Guide * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/porting_guides/porting_guide_core_2.15.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * [Ansible-core 2.15 Porting Guide](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.15.html#id1) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.15.html#ansible-core-2-15-porting-guide "Link to this heading") ===================================================================================================================================================================================================================================================================================================== This section discusses the behavioral changes between `ansible-core` 2.14 and `ansible-core` 2.15. It is intended to assist in updating your playbooks, plugins and other parts of your Ansible infrastructure so they will work with this version of Ansible. We suggest you read this page along with [ansible-core Changelog for 2.15](https://github.com/ansible/ansible/blob/stable-2.15/changelogs/CHANGELOG-v2.15.rst) to understand what updates you may need to make. This document is part of a collection on porting. The complete list of porting guides can be found at [porting guides](https://docs.ansible.com/projects/ansible/2.9/porting_guides/porting_guides.html#porting-guides "(in Ansible v2.9)") . [Playbook](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.15.html#id2) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.15.html#playbook "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * Conditionals - due to mitigation of security issue CVE-2023-5764 in ansible-core 2.15.7, conditional expressions with embedded template blocks can fail with the message “`Conditional is marked as unsafe, and cannot be evaluated.`” when an embedded template consults data from untrusted sources like module results or vars marked `!unsafe`. Conditionals with embedded templates can be a source of malicious template injection when referencing untrusted data, and can nearly always be rewritten without embedded templates. Playbook task conditional keywords such as `when` and `until` have long displayed warnings discouraging use of embedded templates in conditionals; this warning has been expanded to non-task conditionals as well, such as the `assert` action. \- name: task with a module result (always untrusted by Ansible) shell: echo "hi mom" register: untrusted\_result \# don't do it this way... \# - name: insecure conditional with embedded template consulting untrusted data \# assert: \# that: '"hi mom" is in {{ untrusted\_result.stdout }}' \- name: securely access untrusted values directly as Jinja variables instead assert: that: '"hi mom" is in untrusted\_result.stdout' ### [Handlers](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.15.html#id3) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.15.html#handlers "Link to this heading") As documented, if multiple handlers of a specific name have been defined, the last one added into the play is the one that is executed when being notified. Prior to `ansible-core` 2.15, this was not the case for handlers included dynamically into the play with the `include_role` task. This issue has been addressed in `ansible-core` 2.15, and users relying on the `ansible-core` 2.14 and older behavior may need to adjust their playbooks accordingly. > As an example of the behavior change, consider the following: > > \- include\_role: > name: foo > vars: > invocation: 1 > > \- block: > \- include\_role: > name: foo > vars: > invocation: 2 > when: inventory\_hostname == "bar" > > \- meta: flush\_handlers Note The example assumes there is a task within the role `foo` that notifies a handler named `foo_handler` within the role `foo`. Note The fact that different variables and/or their values are attached to `include_role` tasks including the same role makes them distinct roles. Note The second invocation of the `include_role` task results in including tasks and handlers from the role regardless of the `when` conditional evaluation result. The `when` conditional is attached to the `block` wrapping the `include_role` task and as such the `when` conditional is applied to all tasks and handlers from the role after they are included into the play. By the time the `flush_handlers` task runs, all hosts notified `foo_handler` within the first invocation of `include_role`. Additionally the host `bar` (due to `when` restricting all other hosts) notified `foo_handler` again during the second invocation of `include_role`. On `ansible-core` 2.15, the last handler named `foo_handler` added into the play is from the second `include_role` invocation and therefore has `when: inventory_hostname == "bar"` attached to it, resulting in the handler being actually run only on the host `bar` and skipped on all other hosts. Consequently the notifications from the host `bar` have been de-duplicated. On `ansible-core` 2.14 and older, `foo_handler` from the first invocation runs on all hosts. Additionally, `foo_handler` from the second invocation is run on the host `bar` again. [Command Line](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.15.html#id4) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.15.html#command-line "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * The return code of `ansible-galaxy search` is now 0 instead of 1 and the stdout is empty when results are empty to align with other `ansible-galaxy` commands. [Deprecated](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.15.html#id5) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.15.html#deprecated "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * Providing a list of dictionaries to `vars:` is deprecated in favor of supplying a dictionary. Instead of: vars: \- var1: foo \- var2: bar Use: vars: var1: foo var2: bar [Modules](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.15.html#id6) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.15.html#modules "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- No notable changes ### [Modules removed](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.15.html#id7) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.15.html#modules-removed "Link to this heading") The following modules no longer exist: * No notable changes ### [Deprecation notices](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.15.html#id8) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.15.html#deprecation-notices "Link to this heading") No notable changes ### [Noteworthy module changes](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.15.html#id9) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.15.html#noteworthy-module-changes "Link to this heading") No notable changes [Plugins](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.15.html#id10) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.15.html#plugins "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ No notable changes [Porting custom scripts](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.15.html#id11) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.15.html#porting-custom-scripts "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ No notable changes [Networking](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.15.html#id12) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.15.html#networking "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ No notable changes --- # Ansible-core 2.14 Porting Guide — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * [Ansible Core Porting Guides](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/core_porting_guides.html) * Ansible-core 2.14 Porting Guide * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/porting_guides/porting_guide_core_2.14.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * [Ansible-core 2.14 Porting Guide](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.14.html#id1) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.14.html#ansible-core-2-14-porting-guide "Link to this heading") ===================================================================================================================================================================================================================================================================================================== This section discusses the behavioral changes between `ansible-core` 2.13 and `ansible-core` 2.14. It is intended to assist in updating your playbooks, plugins and other parts of your Ansible infrastructure so they will work with this version of Ansible. We suggest you read this page along with [ansible-core Changelog for 2.14](https://github.com/ansible/ansible/blob/stable-2.14/changelogs/CHANGELOG-v2.14.rst) to understand what updates you may need to make. This document is part of a collection on porting. The complete list of porting guides can be found at [porting guides](https://docs.ansible.com/projects/ansible/2.9/porting_guides/porting_guides.html#porting-guides "(in Ansible v2.9)") . [Playbook](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.14.html#id2) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.14.html#playbook "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * Conditionals - due to mitigation of security issue CVE-2023-5764 in ansible-core 2.14.12, conditional expressions with embedded template blocks can fail with the message “`Conditional is marked as unsafe, and cannot be evaluated.`” when an embedded template consults data from untrusted sources like module results or vars marked `!unsafe`. Conditionals with embedded templates can be a source of malicious template injection when referencing untrusted data, and can nearly always be rewritten without embedded templates. Playbook task conditional keywords such as `when` and `until` have long displayed warnings discouraging use of embedded templates in conditionals; this warning has been expanded to non-task conditionals as well, such as the `assert` action. \- name: task with a module result (always untrusted by Ansible) shell: echo "hi mom" register: untrusted\_result \# don't do it this way... \# - name: insecure conditional with embedded template consulting untrusted data \# assert: \# that: '"hi mom" is in {{ untrusted\_result.stdout }}' \- name: securely access untrusted values directly as Jinja variables instead assert: that: '"hi mom" is in untrusted\_result.stdout' * Variables are now evaluated lazily; only when they are actually used. For example, in ansible-core 2.14 an expression `{{ defined_variable or undefined_variable }}` does not fail on `undefined_variable` if the first part of `or` is evaluated to `True` as it is not needed to evaluate the second part. One particular case of a change in behavior to note is the task below which uses the `undefined` test. Prior to version 2.14 this would result in a fatal error trying to access the undefined value in the dictionary. In 2.14 the assertion passes as the dictionary is evaluated as undefined through one of its undefined values: > \- assert: > that: > \- some\_defined\_dict\_with\_undefined\_values is undefined > vars: > dict\_value: 1 > some\_defined\_dict\_with\_undefined\_values: > key1: value1 > key2: '{{ dict\_value }}' > key3: '{{ undefined\_dict\_value }}' [Command Line](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.14.html#id3) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.14.html#command-line "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * Python 3.9 on the controller node is a hard requirement for this release. * At startup the filesystem encoding and locale are checked to verify they are UTF-8. If not, the process exits with an error reporting the errant encoding. If you were previously using the `C` or `POSIX` locale, you may be able to use `C.UTF-8`. If you were previously using a locale such as `en_US.ISO-8859-1`, you may be able to use `en_US.UTF-8`. For simplicity it may be easiest to export the appropriate locale using the `LC_ALL` environment variable. An alternative to modifying your system locale is to run Python in UTF-8 mode; See the [Python documentation](https://docs.python.org/3/using/cmdline.html#envvar-PYTHONUTF8) for more information. [Deprecated](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.14.html#id4) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.14.html#deprecated "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- No notable changes [Modules](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.14.html#id5) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.14.html#modules "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- No notable changes ### [Modules removed](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.14.html#id6) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.14.html#modules-removed "Link to this heading") The following modules no longer exist: * No notable changes ### [Deprecation notices](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.14.html#id7) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.14.html#deprecation-notices "Link to this heading") No notable changes ### [Noteworthy module changes](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.14.html#id8) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.14.html#noteworthy-module-changes "Link to this heading") No notable changes [Plugins](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.14.html#id9) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.14.html#plugins "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- No notable changes [Porting custom scripts](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.14.html#id10) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.14.html#porting-custom-scripts "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ No notable changes [Networking](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.14.html#id11) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.14.html#networking "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ No notable changes --- # Ansible-core 2.12 Porting Guide — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * [Ansible Core Porting Guides](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/core_porting_guides.html) * Ansible-core 2.12 Porting Guide * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/porting_guides/porting_guide_core_2.12.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * [Ansible-core 2.12 Porting Guide](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.12.html#id1) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.12.html#ansible-core-2-12-porting-guide "Link to this heading") ===================================================================================================================================================================================================================================================================================================== This section discusses the behavioral changes between `ansible-core` 2.11 and `ansible-core` 2.12. It is intended to assist in updating your playbooks, plugins and other parts of your Ansible infrastructure so they will work with this version of Ansible. We suggest you read this page along with [ansible-core Changelog for 2.12](https://github.com/ansible/ansible/blob/stable-2.12/changelogs/CHANGELOG-v2.12.rst) to understand what updates you may need to make. This document is part of a collection on porting. The complete list of porting guides can be found at [porting guides](https://docs.ansible.com/projects/ansible/2.9/porting_guides/porting_guides.html#porting-guides "(in Ansible v2.9)") . [Playbook](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.12.html#id2) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.12.html#playbook "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * When calling tasks and setting `async`, setting `ANSIBLE_ASYNC_DIR` under `environment:` is no longer valid. Instead, use the shell configuration variable `async_dir`, for example by setting `ansible_async_dir`: tasks: \- dnf: name: '\*' state: latest async: 300 poll: 5 vars: ansible\_async\_dir: /path/to/my/custom/dir * The `undef()` function is added to the templating environment for creating undefined variables directly in a template. Optionally, a hint may be provided for variables which are intended to be overridden. vars: old: "{{ undef }}" new: "{{ undef() }}" new\_with\_hint: "{{ undef(hint='You must override this variable') }}" [Python Interpreter Discovery](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.12.html#id3) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.12.html#python-interpreter-discovery "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The default value of `INTERPRETER_PYTHON` changed to `auto`. The list of Python interpreters in `INTERPRETER_PYTHON_FALLBACK` changed to prefer Python 3 over Python 2. The combination of these two changes means the new default behavior is to quietly prefer Python 3 over Python 2 on remote hosts. Previously a deprecation warning was issued in situations where interpreter discovery would have used Python 3 but the interpreter was set to `/usr/bin/python`. `INTERPRETER_PYTHON_FALLBACK` can be changed from the default list of interpreters by setting the `ansible_interpreter_python_fallback` variable. See [interpreter discovery documentation](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/interpreter_discovery.html#interpreter-discovery) for more details. [Command Line](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.12.html#id4) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.12.html#command-line "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * Python 3.8 on the controller node is a hard requirement for this release. The command line scripts will not function with a lower Python version. * `ansible-vault` no longer supports `PyCrypto` and requires `cryptography`. [Deprecated](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.12.html#id5) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.12.html#deprecated "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * Python 2.6 on the target node is deprecated in this release. `ansible-core` 2.13 will remove support for Python 2.6. * Bare variables in conditionals: `when` conditionals no longer automatically parse string booleans such as `"true"` and `"false"` into actual booleans. Any variable containing a non-empty string is considered true. This was previously configurable with the `CONDITIONAL_BARE_VARS` configuration option (and the `ANSIBLE_CONDITIONAL_BARE_VARS` environment variable). This setting no longer has any effect. Users can work around the issue by using the `|bool` filter: vars: teardown: 'false' tasks: \- include\_tasks: teardown.yml when: teardown | bool \- include\_tasks: provision.yml when: not teardown | bool * The `_remote_checksum()` method in `ActionBase` is deprecated. Any action plugin using this method should use `_execute_remote_stat()` instead. [Modules](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.12.html#id6) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.12.html#modules "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * `cron` now requires `name` to be specified in all cases. * `cron` no longer allows a `reboot` parameter. Use `special_time: reboot` instead. * `hostname` - On FreeBSD, the `before` result will no longer be `"temporarystub"` if permanent hostname file does not exist. It will instead be `""` (empty string) for consistency with other systems. * `hostname` - On OpenRC and Solaris based systems, the `before` result will no longer be `"UNKNOWN"` if the permanent hostname file does not exist. It will instead be `""` (empty string) for consistency with other systems. * `pip` now uses the `pip` Python module installed for the Ansible module’s Python interpreter, if available, unless `executable` or `virtualenv` were specified. ### [Modules removed](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.12.html#id7) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.12.html#modules-removed "Link to this heading") The following modules no longer exist: * No notable changes ### [Deprecation notices](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.12.html#id8) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.12.html#deprecation-notices "Link to this heading") No notable changes ### [Noteworthy module changes](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.12.html#id9) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.12.html#noteworthy-module-changes "Link to this heading") No notable changes [Plugins](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.12.html#id10) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.12.html#plugins "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ * `unique` filter with Jinja2 < 2.10 is case-sensitive and now raise coherently an error if `case_sensitive=False` instead of when `case_sensitive=True`. * Set theory filters (`intersect`, `difference`, `symmetric_difference` and `union`) are now case-sensitive. Explicitly use `case_sensitive=False` to keep previous behavior. Note: with Jinja2 < 2.10, the filters were already case-sensitive by default. * `password_hash` now uses `passlib` defaults when an option is unspecified, for example `bcrypt_sha256` now default to the “2b” format and if the “2a” format is required it must be specified. [Porting custom scripts](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.12.html#id11) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.12.html#porting-custom-scripts "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ No notable changes [Networking](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.12.html#id12) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.12.html#networking "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ No notable changes --- # Ansible-base 2.10 Porting Guide — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * [Ansible Core Porting Guides](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/core_porting_guides.html) * Ansible-base 2.10 Porting Guide * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/porting_guides/porting_guide_base_2.10.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * [Ansible-base 2.10 Porting Guide](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_base_2.10.html#id1) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_base_2.10.html#ansible-base-2-10-porting-guide "Link to this heading") ===================================================================================================================================================================================================================================================================================================== Warning In preparation for the release of 2.10, many plugins and modules have migrated to Collections on [Ansible Galaxy](https://galaxy.ansible.com/) . For the current development status of Collections and FAQ see [Ansible Collections Community Guide](https://github.com/ansible-collections/overview/blob/main/README.rst) . We expect the 2.10 Porting Guide to change frequently up to the 2.10 release. Follow the conversations about collections on our various [Communicating with the Ansible community](https://docs.ansible.com/projects/ansible-core/devel/community/communication.html#communication) channels for the latest information on the status of the `devel` branch. This section discusses the behavioral changes between Ansible 2.9 and Ansible-base 2.10. It is intended to assist in updating your playbooks, plugins and other parts of your Ansible infrastructure so they will work with this version of Ansible-base. We suggest you read this page along with the [Ansible-base Changelog for 2.10](https://github.com/ansible/ansible/blob/stable-2.10/changelogs/CHANGELOG-v2.10.rst) to understand what updates you may need to make. Ansible-base is mainly of interest for developers and users who only want to use a small, controlled subset of the available collections. Regular users should install ansible. The complete list of porting guides can be found at [porting guides](https://docs.ansible.com/projects/ansible/2.9/porting_guides/porting_guides.html#porting-guides "(in Ansible v2.9)") . [Playbook](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_base_2.10.html#id2) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_base_2.10.html#playbook "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * Fixed a bug on boolean keywords that made random strings return ‘False’, now they should return an error if they are not a proper boolean Example: `diff: yes-` was returning `False`. * A new fact, `ansible_processor_nproc` reflects the number of vcpus available to processes (falls back to the number of vcpus available to the scheduler). [Command Line](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_base_2.10.html#id3) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_base_2.10.html#command-line "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * The `ansible-galaxy login` command has been removed, as the underlying API it used for GitHub auth is being shut down. Publishing roles or collections to Galaxy through `ansible-galaxy` now requires that a Galaxy API token be passed to the CLI through a token file (default location `~/.ansible/galaxy_token`) or (insecurely) through the `--token` argument to `ansible-galaxy`. [Deprecated](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_base_2.10.html#id4) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_base_2.10.html#deprecated "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * Windows Server 2008 and 2008 R2 will no longer be supported or tested in the next Ansible release, see [Are Server 2008, 2008 R2 and Windows 7 supported?](https://docs.ansible.com/ansible-core/2.15/os_guide/windows_faq.html#are-server-2008-2008-r2-and-windows-7-supported) . [Modules](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_base_2.10.html#id5) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_base_2.10.html#modules "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Warning Links on this page may not point to the most recent versions of modules. We will update them when we can. * Version 2.10.0 of ansible-base changed the default mode of file-based tasks to `0o600 & ~umask` when the user did not specify a `mode` parameter on file-based tasks. This was in response to a CVE report which we have reconsidered. As a result, the mode change has been reverted in 2.10.1, and mode will now default to `0o666 & ~umask` as in previous versions of Ansible. * If you changed any tasks to specify less restrictive permissions while using 2.10.0, those changes will be unnecessary (but will do no harm) in 2.10.1. * To avoid the issue raised in CVE-2020-1736, specify a `mode` parameter in all file-based tasks that accept it. * `dnf` and `yum` - As of version 2.10.1, the `dnf` module (and `yum` action when it uses `dnf`) now correctly validates GPG signatures of packages (CVE-2020-14365). If you see an error such as `Failed to validate GPG signature for [package name]`, please ensure that you have imported the correct GPG key for the DNF repository and/or package you are using. One way to do this is with the `rpm_key` module. Although we discourage it, in some cases it may be necessary to disable the GPG check. This can be done by explicitly adding `disable_gpg_check: yes` in your `dnf` or `yum` task. ### [Noteworthy module changes](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_base_2.10.html#id6) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_base_2.10.html#noteworthy-module-changes "Link to this heading") * Ansible modules created with `add_file_common_args=True` added a number of undocumented arguments which were mostly there to ease implementing certain action plugins. The undocumented arguments `src`, `follow`, `force`, `content`, `backup`, `remote_src`, `regexp`, `delimiter`, and `directory_mode` are now no longer added. Modules relying on these options to be added need to specify them by themselves. * Ansible no longer looks for Python modules in the current working directory (typically the `remote_user`’s home directory) when an Ansible module is run. This is to fix becoming an unprivileged user on OpenBSD and to mitigate any attack vector if the current working directory is writable by a malicious user. Install any Python modules needed to run the Ansible modules on the managed node in a system-wide location or in another directory which is in the `remote_user`’s `$PYTHONPATH` and readable by the `become_user`. [Plugins](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_base_2.10.html#id7) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_base_2.10.html#plugins "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [Lookup plugin names case-sensitivity](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_base_2.10.html#id8) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_base_2.10.html#lookup-plugin-names-case-sensitivity "Link to this heading") * Prior to Ansible `2.10` lookup plugin names passed in as an argument to the `lookup()` function were treated as case-insensitive as opposed to lookups invoked through `with_`. `2.10` brings consistency to `lookup()` and `with_` to be both case-sensitive. ### [Noteworthy plugin changes](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_base_2.10.html#id9) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_base_2.10.html#noteworthy-plugin-changes "Link to this heading") * Cache plugins in collections can be used to cache data from inventory plugins. Previously, cache plugins in collections could only be used for fact caching. * Some undocumented arguments from `FILE_COMMON_ARGUMENTS` have been removed; plugins using these, in particular action plugins, need to be adjusted. The undocumented arguments which were removed are `src`, `follow`, `force`, `content`, `backup`, `remote_src`, `regexp`, `delimiter`, and `directory_mode`. ### [Action plugins which execute modules should use fully-qualified module names](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_base_2.10.html#id10) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_base_2.10.html#action-plugins-which-execute-modules-should-use-fully-qualified-module-names "Link to this heading") * Action plugins that call modules should pass explicit, fully-qualified module names to `_execute_module()` whenever possible (eg, `ansible.builtin.file` rather than `file`). This ensures that the task’s collection search order is not consulted to resolve the module. Otherwise, a module from a collection earlier in the search path could be used when not intended. [Porting custom scripts](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_base_2.10.html#id11) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_base_2.10.html#porting-custom-scripts "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ No notable changes --- # Testing Strategies — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * Testing Strategies * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/reference_appendices/test_strategies.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Testing Strategies[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/test_strategies.html#testing-strategies "Link to this heading") ============================================================================================================================================================ Integrating Testing With Ansible Playbooks[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/test_strategies.html#integrating-testing-with-ansible-playbooks "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ Many times, people ask, “how can I best integrate testing with Ansible playbooks?” There are many options. Ansible is actually designed to be a “fail-fast” and ordered system, therefore it makes it easy to embed testing directly in Ansible playbooks. In this chapter, we’ll go into some patterns for integrating tests of infrastructure and discuss the right level of testing that may be appropriate. Note This is a chapter about testing the application you are deploying, not the chapter on how to test Ansible modules during development. For that content, please hop over to the Development section. By incorporating a degree of testing into your deployment workflow, there will be fewer surprises when code hits production and, in many cases, tests can be used in production to prevent failed updates from migrating across an entire installation. Since it is push-based, it is also very easy to run the steps on the localhost or testing servers. Ansible lets you insert as many checks and balances into your upgrade workflow as you would like to have. The Right Level of Testing[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/test_strategies.html#the-right-level-of-testing "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Ansible resources are models of desired-state. As such, it should not be necessary to test that services are started, packages are installed, or other such things. Ansible is the system that will ensure these things are declaratively true. Instead, assert these things in your playbooks. tasks: \- ansible.builtin.service: name: foo state: started enabled: true If you think the service may not be started, the best thing to do is request it to be started. If the service fails to start, Ansible will yell appropriately. (This should not be confused with whether the service is doing something functional, which we’ll show more about how to do later). Check Mode As A Drift Test[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/test_strategies.html#check-mode-as-a-drift-test "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- In the above setup, `--check` mode in Ansible can be used as a layer of testing as well. If running a deployment playbook against an existing system, using the `--check` flag to the ansible command will report if Ansible thinks it would have had to have made any changes to bring the system into a desired state. This can let you know up front if there is any need to deploy onto the given system. Ordinarily, scripts and commands don’t run in check mode, so if you want certain steps to execute in normal mode even when the `--check` flag is used, such as calls to the script module, disable check mode for those tasks: roles: \- webserver tasks: \- ansible.builtin.script: verify.sh check\_mode: false Modules That Are Useful for Testing[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/test_strategies.html#modules-that-are-useful-for-testing "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Certain playbook modules are particularly good for testing. Below is an example that ensures a port is open: tasks: \- ansible.builtin.wait\_for: host: "{{ inventory\_hostname }}" port: 22 delegate\_to: localhost Here’s an example of using the URI module to make sure a web service returns: tasks: \- action: uri url=https://www.example.com return\_content=yes register: webpage \- fail: msg: 'service is not happy' when: "'AWESOME' not in webpage.content" It is easy to push an arbitrary script (in any language) on a remote host and the script will automatically fail if it has a non-zero return code: tasks: \- ansible.builtin.script: test\_script1 \- ansible.builtin.script: test\_script2 --parameter value --parameter2 value If using roles (you should be, roles are great!), scripts pushed by the script module can live in the ‘files/’ directory of a role. And the assert module makes it very easy to validate various kinds of truth: tasks: \- ansible.builtin.shell: /usr/bin/some-command --parameter value register: cmd\_result \- ansible.builtin.assert: that: \- "'not ready' not in cmd\_result.stderr" \- "'gizmo enabled' in cmd\_result.stdout" Should you feel the need to test for the existence of files that are not declaratively set by your Ansible configuration, the ‘stat’ module is a great choice: tasks: \- ansible.builtin.stat: path: /path/to/something register: p \- ansible.builtin.assert: that: \- p.stat.exists and p.stat.isdir As mentioned above, there’s no need to check things like the return codes of commands. Ansible is checking them automatically. Rather than checking for a user to exist, consider using the user module to make it exist. Ansible is a fail-fast system, so when there is an error creating that user, it will stop the playbook run. You do not have to check up behind it. Testing Lifecycle[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/test_strategies.html#testing-lifecycle "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------- If writing some degree of basic validation of your application into your playbooks, they will run every time you deploy. As such, deploying into a local development VM and a staging environment will both validate that things are according to plan ahead of your production deploy. Your workflow may be something like this: \- Use the same playbook all the time with embedded tests in development - Use the playbook to deploy to a staging environment (with the same playbooks) that simulates production - Run an integration test battery written by your QA team against staging - Deploy to production, with the same integrated tests. Something like an integration test battery should be written by your QA team if you are a production webservice. This would include things like Selenium tests or automated API tests and would usually not be something embedded into your Ansible playbooks. However, it does make sense to include some basic health checks into your playbooks, and in some cases it may be possible to run a subset of the QA battery against remote nodes. This is what the next section covers. Integrating Testing With Rolling Updates[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/test_strategies.html#integrating-testing-with-rolling-updates "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- If you have read into [Controlling where tasks run: delegation and local actions](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_delegation.html#playbooks-delegation) it may quickly become apparent that the rolling update pattern can be extended, and you can use the success or failure of the playbook run to decide whether to add a machine into a load balancer or not. This is the great culmination of embedded tests: \--- \- hosts: webservers serial: 5 pre\_tasks: \- name: take out of load balancer pool ansible.builtin.command: /usr/bin/take\_out\_of\_pool {{ inventory\_hostname }} delegate\_to: 127.0.0.1 tasks: \- ansible.builtin.include\_role: name: "{{ item }}" loop: \- common \- webserver \- name: run any notified handlers ansible.builtin.meta: flush\_handlers \- name: test the configuration ansible.builtin.include\_role: name: apply\_testing\_checks post\_tasks: \- name: add back to load balancer pool ansible.builtin.command: /usr/bin/add\_back\_to\_pool {{ inventory\_hostname }} delegate\_to: 127.0.0.1 Of course in the above, the “take out of the pool” and “add back” steps would be replaced with a call to an Ansible load balancer module or appropriate shell command. You might also have steps that use a monitoring module to start and end an outage window for the machine. However, what you can see from the above is that tests are used as a gate – if the “apply\_testing\_checks” step is not performed, the machine will not go back into the pool. Read the delegation chapter about “max\_fail\_percentage” and you can also control how many failing tests will stop a rolling update from proceeding. This above approach can also be modified to run a step from a testing machine remotely against a machine: \--- \- hosts: webservers serial: 5 pre\_tasks: \- name: take out of load balancer pool ansible.builtin.command: /usr/bin/take\_out\_of\_pool {{ inventory\_hostname }} delegate\_to: 127.0.0.1 roles: \- common \- webserver tasks: \- ansible.builtin.script: /srv/qa\_team/app\_testing\_script.sh --server {{ inventory\_hostname }} delegate\_to: testing\_server post\_tasks: \- name: add back to load balancer pool ansible.builtin.command: /usr/bin/add\_back\_to\_pool {{ inventory\_hostname }} delegate\_to: 127.0.0.1 In the above example, a script is run from the testing server against a remote node prior to bringing it back into the pool. In the event of a problem, fix the few servers that fail using Ansible’s automatically generated retry file to repeat the deploy on just those servers. Achieving Continuous Deployment[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/test_strategies.html#achieving-continuous-deployment "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- If desired, the above techniques may be extended to enable continuous deployment practices. The workflow may look like this: \- Write and use automation to deploy local development VMs - Have a CI system like Jenkins deploy to a staging environment on every code change - The deploy job calls testing scripts to pass/fail a build on every deploy - If the deploy job succeeds, it runs the same deploy playbook against production inventory Some Ansible users use the above approach to deploy a half-dozen or dozen times an hour without taking all of their infrastructure offline. A culture of automated QA is vital if you wish to get to this level. If you are still doing a large amount of manual QA, you should still make the decision on whether to deploy manually as well, but it can still help to work in the rolling update patterns of the previous section and incorporate some basic health checks using modules like ‘script’, ‘stat’, ‘uri’, and ‘assert’. Conclusion[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/test_strategies.html#conclusion "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------- Ansible believes you should not need another framework to validate basic things of your infrastructure is true. This is the case because Ansible is an order-based system that will fail immediately on unhandled errors for a host, and prevent further configuration of that host. This forces errors to the top and shows them in a summary at the end of the Ansible run. However, as Ansible is designed as a multi-tier orchestration system, it makes it very easy to incorporate tests into the end of a playbook run, either using loose tasks or roles. When used with rolling updates, testing steps can decide whether to put a machine back into a load balanced pool or not. Finally, because Ansible errors propagate all the way up to the return code of the Ansible program itself, and Ansible by default runs in an easy push-based mode, Ansible is a great step to put into a build environment if you wish to use it to roll out systems as part of a Continuous Integration/Continuous Delivery pipeline, as is covered in sections above. The focus should not be on infrastructure testing, but on application testing, so we strongly encourage getting together with your QA team and ask what sort of tests would make sense to run every time you deploy development VMs, and which sort of tests they would like to run against the staging environment on every deploy. Obviously at the development stage, unit tests are great too. But don’t unit test your playbook. Ansible describes states of resources declaratively, so you don’t have to. If there are cases where you want to be sure of something though, that’s great, and things like stat/assert are great go-to modules for that purpose. In all, testing is a very organizational and site-specific thing. Everybody should be doing it, but what makes the most sense for your environment will vary with what you are deploying and who is using it – but everyone benefits from a more robust and reliable deployment system. See also [Collection Index](https://docs.ansible.com/projects/ansible/latest/collections/index.html#list-of-collections) Browse existing collections, modules, and plugins [Working with playbooks](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks.html#working-with-playbooks) An introduction to playbooks [Controlling where tasks run: delegation and local actions](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_delegation.html#playbooks-delegation) Delegation, useful for working with load balancers, clouds, and locally executed steps. [Communication](https://docs.ansible.com/projects/ansible/latest/community/communication.html#communication) Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide --- # Ansible Reference: Module Utilities — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * Ansible Reference: Module Utilities * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/reference_appendices/module_utils.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Ansible Reference: Module Utilities[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible-reference-module-utilities "Link to this heading") ============================================================================================================================================================================================== This page documents utilities intended to be helpful when writing Ansible modules in Python. AnsibleModule[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansiblemodule "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------- To use this functionality, include `from ansible.module_utils.basic import AnsibleModule` in your module. _class_ ansible.module\_utils.basic.AnsibleModule(_argument\_spec_, _bypass\_checks\=False_, _no\_log\=False_, _mutually\_exclusive\=None_, _required\_together\=None_, _required\_one\_of\=None_, _add\_file\_common\_args\=False_, _supports\_check\_mode\=False_, _required\_if\=None_, _required\_by\=None_) Common code for quickly building an ansible module in Python (although you can write modules with anything that can return JSON). See [Developing modules](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_general.html#developing-modules-general) for a general introduction and [Ansible module architecture](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_program_flow_modules.html#developing-program-flow-modules) for more detailed explanation. add\_path\_info(_kwargs_) for results that are files, supplement the info about the file in the return path with stats about the file path. atomic\_move(_src_, _dest_, _unsafe\_writes\=False_, _keep\_dest\_attrs\=True_) atomically move src to dest, copying attributes from dest, returns true on success it uses os.rename to ensure this as it is an atomic operation, rest of the function is to work around limitations, corner cases and ensure selinux context is saved if possible backup\_local(_fn_) make a date-marked backup of the specified file, return True or False on success or failure boolean(_arg_) Convert the argument to a boolean deprecate(_msg: [str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") _, _version: [str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") | [None](https://docs.python.org/3/library/constants.html#None "(in Python v3.14)") \= None_, _date: [str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") | [None](https://docs.python.org/3/library/constants.html#None "(in Python v3.14)") \= None_, _collection\_name: [str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") | [None](https://docs.python.org/3/library/constants.html#None "(in Python v3.14)") \= None_, _\*_, _deprecator: PluginInfo | [None](https://docs.python.org/3/library/constants.html#None "(in Python v3.14)") \= None_, _help\_text: [str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") | [None](https://docs.python.org/3/library/constants.html#None "(in Python v3.14)") \= None_) → [None](https://docs.python.org/3/library/constants.html#None "(in Python v3.14)") Record a deprecation warning to be returned with the module result. Most callers do not need to provide collection\_name or deprecator – but provide only one if needed. Specify version or date, but not both. If date is a string, it must be in the form YYYY-MM-DD. digest\_from\_file(_filename_, _algorithm_) Return hex digest of local file for a digest\_method specified by name, or None if file is not present. error\_as\_warning(_msg: [str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") | [None](https://docs.python.org/3/library/constants.html#None "(in Python v3.14)") _, _exception: [BaseException](https://docs.python.org/3/library/exceptions.html#BaseException "(in Python v3.14)") _, _\*_, _help\_text: [str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") | [None](https://docs.python.org/3/library/constants.html#None "(in Python v3.14)") \= None_) → [None](https://docs.python.org/3/library/constants.html#None "(in Python v3.14)") Display an exception as a warning. exit\_json(_\*\*kwargs_) → [NoReturn](https://docs.python.org/3/library/typing.html#typing.NoReturn "(in Python v3.14)") return from the module, without error fail\_json(_msg: str_, _\*_, _exception: BaseException | str | None \= _, _\*\*kwargs_) → [NoReturn](https://docs.python.org/3/library/typing.html#typing.NoReturn "(in Python v3.14)") Return from the module with an error message and optional exception/traceback detail. A traceback will only be included in the result if error traceback capturing has been enabled. When exception is an exception object, its message chain will be automatically combined with msg to create the final error message. The message chain includes the exception’s message as well as messages from any \_\_cause\_\_ exceptions. The traceback from exception will be used for the formatted traceback. When exception is a string, it will be used as the formatted traceback. When exception is set to None, the current call stack will be used for the formatted traceback. When exception is not specified, a formatted traceback will be retrieved from the current exception. If no exception is pending, the current call stack will be used instead. find\_mount\_point(_path_) > Takes a path and returns its mount point Parameters: **path** – a string type with a filesystem path Returns: the path to the mount point as a text type get\_bin\_path(_arg_, _required\=False_, _opt\_dirs\=None_) Find system executable in PATH. Parameters: * **arg** – The executable to find. * **required** – if the executable is not found and required is `True`, fail\_json * **opt\_dirs** – optional list of directories to search in addition to `PATH` Returns: if found return full path; otherwise return original arg, unless ‘warning’ then return None Raises: Sysexit: if arg is not found and required=True (via fail\_json) is\_executable(_path_) is the given path executable? Parameters: **path** – The path of the file to check. Limitations: * Does not account for FSACLs. * Most times we really want to know “Can the current user execute this file”. This function does not tell us that, only if any execute bit is set. is\_special\_selinux\_path(_path_) Returns a tuple containing (True, selinux\_context) if the given path is on a NFS or other ‘special’ fs mount point, otherwise the return will be (False, None). load\_file\_common\_arguments(_params_, _path\=None_) many modules deal with files, this encapsulates common options that the file module accepts such that it is directly available to all modules and they can share code. Allows to overwrite the path/dest module argument by providing path. md5(_filename_) Return MD5 hex digest of local file using digest\_from\_file(). Do not use this function unless you have no other choice for: 1. Optional backwards compatibility 2. Compatibility with a third party protocol This function will not work on systems complying with FIPS-140-2. Most uses of this function can use the module.sha1 function instead. preserved\_copy(_src_, _dest_) Copy a file with preserved ownership, permissions and context run\_command(_args_, _check\_rc\=False_, _close\_fds\=True_, _executable\=None_, _data\=None_, _binary\_data\=False_, _path\_prefix\=None_, _cwd\=None_, _use\_unsafe\_shell\=False_, _prompt\_regex\=None_, _environ\_update\=None_, _umask\=None_, _encoding\='utf-8'_, _errors\='surrogate\_or\_strict'_, _expand\_user\_and\_vars\=True_, _pass\_fds\=None_, _before\_communicate\_callback\=None_, _ignore\_invalid\_cwd\=True_, _handle\_exceptions\=True_) Execute a command, returns rc, stdout, and stderr. The mechanism of this method for reading stdout and stderr differs from that of CPython subprocess.Popen.communicate, in that this method will stop reading once the spawned command has exited and stdout and stderr have been consumed, as opposed to waiting until stdout/stderr are closed. This can be an important distinction, when taken into account that a forked or backgrounded process may hold stdout or stderr open for longer than the spawned command. Parameters: **args** – is the command to run \* If args is a list, the command will be run with shell=False. \* If args is a string and use\_unsafe\_shell=False it will split args to a list and run with shell=False \* If args is a string and use\_unsafe\_shell=True it runs with shell=True. Kw check\_rc: Whether to call fail\_json in case of non zero RC. Default False Kw close\_fds: See documentation for subprocess.Popen(). Default True Kw executable: See documentation for subprocess.Popen(). Default None Kw data: If given, information to write to the stdin of the command Kw binary\_data: If False, append a newline to the data. Default False Kw path\_prefix: If given, additional path to find the command in. This adds to the PATH environment variable so helper commands in the same directory can also be found Kw cwd: If given, working directory to run the command inside Kw use\_unsafe\_shell: See args parameter. Default False Kw prompt\_regex: Regex string (not a compiled regex) which can be used to detect prompts in the stdout which would otherwise cause the execution to hang (especially if no input data is specified) Kw environ\_update: dictionary to _update_ environ variables with Kw umask: Umask to be used when running the command. Default None Kw encoding: Since we return strings, we need to know the encoding to use to transform from bytes to text. If you want to always get bytes back, use encoding=None. The default is “utf-8”. This does not affect transformation of strings given as args. Kw errors: Since we return strings, we need to transform stdout and stderr from bytes to text. If the bytes are undecodable in the `encoding` specified, then use this error handler to deal with them. The default is `surrogate_or_strict` which means that the bytes will be decoded using the surrogateescape error handler if available (available on all Python versions we support) otherwise a UnicodeError traceback will be raised. This does not affect transformations of strings given as args. Kw expand\_user\_and\_vars: When `use_unsafe_shell=False` this argument dictates whether `~` is expanded in paths and environment variables are expanded before running the command. When `True` a string such as `$SHELL` will be expanded regardless of escaping. When `False` and `use_unsafe_shell=False` no path or variable expansion will be done. Kw pass\_fds: This argument dictates which file descriptors should be passed to an underlying `Popen` constructor. Kw before\_communicate\_callback: This function will be called after `Popen` object will be created but before communicating to the process. (`Popen` object will be passed to callback as a first argument) Kw ignore\_invalid\_cwd: This flag indicates whether an invalid `cwd` (non-existent or not a directory) should be ignored or should raise an exception. Kw handle\_exceptions: This flag indicates whether an exception will be handled inline and issue a failed\_json or if the caller should handle it. Returns: A 3-tuple of return code (int), stdout (str), and stderr (str). stdout and stderr are text strings converted according to the encoding and errors parameters. If you want byte strings, use encoding=None to turn decoding to text off. sha1(_filename_) Return SHA1 hex digest of local file using digest\_from\_file(). sha256(_filename_) Return SHA-256 hex digest of local file using digest\_from\_file(). Basic[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#basic "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------- To use this functionality, include `import ansible.module_utils.basic` in your module. ansible.module\_utils.basic.get\_platform()[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.basic.get_platform "Link to this definition") Returns: Name of the platform the module is running on in a native string Returns a native string that labels the platform (“Linux”, “Solaris”, etc). Currently, this is the result of calling [`platform.system()`](https://docs.python.org/3/library/platform.html#platform.system "(in Python v3.14)") . ansible.module\_utils.basic.heuristic\_log\_sanitize(_data_, _no\_log\_values\=None_)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.basic.heuristic_log_sanitize "Link to this definition") Remove strings that look like passwords from log messages Argument Spec[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#argument-spec "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------- Classes and functions for validating parameters against an argument spec. ### ArgumentSpecValidator[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#argumentspecvalidator "Link to this heading") _class_ ansible.module\_utils.common.arg\_spec.ArgumentSpecValidator(_argument\_spec_, _mutually\_exclusive\=None_, _required\_together\=None_, _required\_one\_of\=None_, _required\_if\=None_, _required\_by\=None_)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.arg_spec.ArgumentSpecValidator "Link to this definition") Argument spec validation class Creates a validator based on the `argument_spec` that can be used to validate a number of parameters using the [`validate()`](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.arg_spec.ArgumentSpecValidator.validate "ansible.module_utils.common.arg_spec.ArgumentSpecValidator.validate") method. Parameters: * **argument\_spec** ([_dict_](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.14)") _\[_[_str_](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ _,_ [_dict_](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.14)")\ _\]_) – Specification of valid parameters and their type. May include nested argument specs. * **mutually\_exclusive** ([_list_](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.14)") _\[_[_str_](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ _\] or_ [_list_](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.14)") _\[_[_list_](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.14)")\ _\[_[_str_](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ _\]__\]_) – List or list of lists of terms that should not be provided together. * **required\_together** ([_list_](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.14)") _\[_[_list_](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.14)")\ _\[_[_str_](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ _\]__\]_) – List of lists of terms that are required together. * **required\_one\_of** ([_list_](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.14)") _\[_[_list_](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.14)")\ _\[_[_str_](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ _\]__\]_) – List of lists of terms, one of which in each list is required. * **required\_if** ([_list_](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.14)") ) – List of lists of `[parameter, value, [parameters]]` where one of `[parameters]` is required if `parameter == value`. * **required\_by** ([_dict_](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.14)") _\[_[_str_](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ _,_ [_list_](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.14)")\ _\[_[_str_](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ _\]__\]_) – Dictionary of parameter names that contain a list of parameters required by each key in the dictionary. validate(_parameters_, _\*args_, _\*\*kwargs_)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.arg_spec.ArgumentSpecValidator.validate "Link to this definition") Validate `parameters` against argument spec. Error messages in the [`ValidationResult`](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.arg_spec.ValidationResult "ansible.module_utils.common.arg_spec.ValidationResult") may contain no\_log values and should be sanitized with [`sanitize_keys()`](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.parameters.sanitize_keys "ansible.module_utils.common.parameters.sanitize_keys") before logging or displaying. Parameters: **parameters** ([_dict_](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.14)") _\[_[_str_](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ _,_ [_dict_](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.14)")\ _\]_) – Parameters to validate against the argument spec Returns: [`ValidationResult`](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.arg_spec.ValidationResult "ansible.module_utils.common.arg_spec.ValidationResult") containing validated parameters. Simple Example: argument\_spec = { 'name': {'type': 'str'}, 'age': {'type': 'int'}, } parameters = { 'name': 'bo', 'age': '42', } validator = ArgumentSpecValidator(argument\_spec) result = validator.validate(parameters) if result.error\_messages: sys.exit("Validation failed: {0}".format(", ".join(result.error\_messages)) valid\_params = result.validated\_parameters ### ValidationResult[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#validationresult "Link to this heading") _class_ ansible.module\_utils.common.arg\_spec.ValidationResult(_parameters_)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.arg_spec.ValidationResult "Link to this definition") Result of argument spec validation. This is the object returned by [`ArgumentSpecValidator.validate()`](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.arg_spec.ArgumentSpecValidator.validate "ansible.module_utils.common.arg_spec.ArgumentSpecValidator.validate") containing the validated parameters and any errors. Parameters: **parameters** ([_dict_](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.14)") ) – Terms to be validated and coerced to the correct type. errors[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.arg_spec.ValidationResult.errors "Link to this definition") [`AnsibleValidationErrorMultiple`](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.errors.AnsibleValidationErrorMultiple "ansible.module_utils.errors.AnsibleValidationErrorMultiple") containing all [`AnsibleValidationError`](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.errors.AnsibleValidationError "ansible.module_utils.errors.AnsibleValidationError") objects if there were any failures during validation. _property_ validated\_parameters[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.arg_spec.ValidationResult.validated_parameters "Link to this definition") Validated and coerced parameters. _property_ unsupported\_parameters[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.arg_spec.ValidationResult.unsupported_parameters "Link to this definition") [`set`](https://docs.python.org/3/library/stdtypes.html#set "(in Python v3.14)") of unsupported parameter names. _property_ error\_messages[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.arg_spec.ValidationResult.error_messages "Link to this definition") [`list`](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.14)") of all error messages from each exception in [`errors`](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.arg_spec.ValidationResult.errors "ansible.module_utils.common.arg_spec.ValidationResult.errors") . ### Parameters[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#module-ansible.module_utils.common.parameters "Link to this heading") ansible.module\_utils.common.parameters.DEFAULT\_TYPE\_VALIDATORS[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.parameters.DEFAULT_TYPE_VALIDATORS "Link to this definition") [`dict`](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.14)") of type names, such as `'str'`, and the default function used to check that type, [`check_type_str()`](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_str "ansible.module_utils.common.validation.check_type_str") in this case. ansible.module\_utils.common.parameters.env\_fallback(_\*args_, _\*\*kwargs_)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.parameters.env_fallback "Link to this definition") Load value from environment variable ansible.module\_utils.common.parameters.remove\_values(_value_, _no\_log\_strings_)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.parameters.remove_values "Link to this definition") Remove strings in `no_log_strings` from value. If value is a container type, then remove a lot more. Use of `deferred_removals` exists, rather than a pure recursive solution, because of the potential to hit the maximum recursion depth when dealing with large amounts of data (see [issue #24560](https://github.com/ansible/ansible/issues/24560) ). ansible.module\_utils.common.parameters.sanitize\_keys(_obj_, _no\_log\_strings_, _ignore\_keys\=frozenset({})_)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.parameters.sanitize_keys "Link to this definition") Sanitize the keys in a container object by removing `no_log` values from key names. This is a companion function to the [`remove_values()`](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.parameters.remove_values "ansible.module_utils.common.parameters.remove_values") function. Similar to that function, we make use of `deferred_removals` to avoid hitting maximum recursion depth in cases of large data structures. Parameters: * **obj** – The container object to sanitize. Non-container objects are returned unmodified. * **no\_log\_strings** – A set of string values we do not want logged. * **ignore\_keys** – A set of string values of keys to not sanitize. Returns: An object with sanitized keys. ### Validation[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#validation "Link to this heading") Standalone functions for validating various parameter types. ansible.module\_utils.common.validation.check\_missing\_parameters(_parameters_, _required\_parameters\=None_)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_missing_parameters "Link to this definition") This is for checking for required params when we can not check via argspec because we need more information than is simply given in the argspec. Raises [`TypeError`](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") if any required parameters are missing Parameters: * **parameters** – Dictionary of parameters * **required\_parameters** – List of parameters to look for in the given parameters. Returns: Empty list or raises [`TypeError`](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") if the check fails. ansible.module\_utils.common.validation.check\_mutually\_exclusive(_terms_, _parameters_, _options\_context\=None_)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_mutually_exclusive "Link to this definition") Check mutually exclusive terms against argument parameters Accepts a single list or list of lists that are groups of terms that should be mutually exclusive with one another Parameters: * **terms** – List of mutually exclusive parameters * **parameters** – Dictionary of parameters * **options\_context** – List of strings of parent key names if `terms` are in a sub spec. Returns: Empty list or raises [`TypeError`](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") if the check fails. ansible.module\_utils.common.validation.check\_required\_arguments(_argument\_spec_, _parameters_, _options\_context\=None_)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_required_arguments "Link to this definition") Check all parameters in argument\_spec and return a list of parameters that are required but not present in parameters. Raises [`TypeError`](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") if the check fails Parameters: * **argument\_spec** – Argument spec dictionary containing all parameters and their specification * **parameters** – Dictionary of parameters * **options\_context** – List of strings of parent key names if `argument_spec` are in a sub spec. Returns: Empty list or raises [`TypeError`](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") if the check fails. ansible.module\_utils.common.validation.check\_required\_by(_requirements_, _parameters_, _options\_context\=None_)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_required_by "Link to this definition") For each key in requirements, check the corresponding list to see if they exist in parameters. Accepts a single string or list of values for each key. Parameters: * **requirements** – Dictionary of requirements * **parameters** – Dictionary of parameters * **options\_context** – List of strings of parent key names if `requirements` are in a sub spec. Returns: Empty dictionary or raises [`TypeError`](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") if the check fails. ansible.module\_utils.common.validation.check\_required\_if(_requirements_, _parameters_, _options\_context\=None_)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_required_if "Link to this definition") Check parameters that are conditionally required Raises [`TypeError`](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") if the check fails Parameters: **requirements** – List of lists specifying a parameter, value, parameters required when the given parameter is the specified value, and optionally a boolean indicating any or all parameters are required. Example: required\_if\=\[\ \['state', 'present', ('path',), True\],\ \['someint', 99, ('bool\_param', 'string\_param')\],\ \] Parameters: * **parameters** – Dictionary of parameters * **options\_context** – List of strings of parent key names if `requirements` are in a sub spec. Returns: Empty list or raises [`TypeError`](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") if the check fails. The results attribute of the exception contains a list of dictionaries. Each dictionary is the result of evaluating each item in requirements. Each return dictionary contains the following keys: > key missing: > > List of parameters that are required but missing > > key requires: > > ’any’ or ‘all’ > > key parameter: > > Parameter name that has the requirement > > key value: > > Original value of the parameter > > key requirements: > > Original required parameters Example: \[\ {\ 'parameter': 'someint',\ 'value': 99\ 'requirements': ('bool\_param', 'string\_param'),\ 'missing': \['string\_param'\],\ 'requires': 'all',\ }\ \] ansible.module\_utils.common.validation.check\_required\_one\_of(_terms_, _parameters_, _options\_context\=None_)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_required_one_of "Link to this definition") Check each list of terms to ensure at least one exists in the given module parameters Accepts a list of lists or tuples Parameters: * **terms** – List of lists of terms to check. For each list of terms, at least one is required. * **parameters** – Dictionary of parameters * **options\_context** – List of strings of parent key names if `terms` are in a sub spec. Returns: Empty list or raises [`TypeError`](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") if the check fails. ansible.module\_utils.common.validation.check\_required\_together(_terms_, _parameters_, _options\_context\=None_)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_required_together "Link to this definition") Check each list of terms to ensure every parameter in each list exists in the given parameters. Accepts a list of lists or tuples. Parameters: * **terms** – List of lists of terms to check. Each list should include parameters that are all required when at least one is specified in the parameters. * **parameters** – Dictionary of parameters * **options\_context** – List of strings of parent key names if `terms` are in a sub spec. Returns: Empty list or raises [`TypeError`](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") if the check fails. ansible.module\_utils.common.validation.check\_type\_bits(_value_)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_bits "Link to this definition") Convert a human-readable string bits value to bits in integer. Example: `check_type_bits('1Mb')` returns integer 1048576. Raises [`TypeError`](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") if unable to convert the value. ansible.module\_utils.common.validation.check\_type\_bool(_value_)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_bool "Link to this definition") Verify that the value is a bool or convert it to a bool and return it. Raises [`TypeError`](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") if unable to convert to a bool Parameters: **value** – String, int, or float to convert to bool. Valid booleans include: ‘1’, ‘on’, 1, ‘0’, 0, ‘n’, ‘f’, ‘false’, ‘true’, ‘y’, ‘t’, ‘yes’, ‘no’, ‘off’ Returns: Boolean True or False ansible.module\_utils.common.validation.check\_type\_bytes(_value_)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_bytes "Link to this definition") Convert a human-readable string value to bytes Raises [`TypeError`](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") if unable to convert the value ansible.module\_utils.common.validation.check\_type\_dict(_value_)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_dict "Link to this definition") Verify that value is a dict or convert it to a dict and return it. Raises [`TypeError`](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") if unable to convert to a dict Parameters: **value** – Dict or string to convert to a dict. Accepts `k1=v2, k2=v2` or `k1=v2 k2=v2`. Returns: value converted to a dictionary ansible.module\_utils.common.validation.check\_type\_float(_value_)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_float "Link to this definition") Verify that value is a float or convert it to a float and return it Raises [`TypeError`](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") if unable to convert to a float Parameters: **value** – float, int, str, or bytes to verify or convert and return. Returns: float of given value. ansible.module\_utils.common.validation.check\_type\_int(_value_)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_int "Link to this definition") Verify that the value is an integer and return it or convert the value to an integer and return it Raises [`TypeError`](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") if unable to convert to an int Parameters: **value** – String or int to convert of verify Returns: int of given value ansible.module\_utils.common.validation.check\_type\_jsonarg(_value_)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_jsonarg "Link to this definition") JSON serialize dict/list/tuple, strip str and bytes. Previously required for cases where Ansible/Jinja classic-mode literal eval pass could inadvertently deserialize objects. ansible.module\_utils.common.validation.check\_type\_list(_value_)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_list "Link to this definition") Verify that the value is a list or convert to a list A comma separated string will be split into a list. Raises a [`TypeError`](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") if unable to convert to a list. Parameters: **value** – Value to validate or convert to a list Returns: Original value if it is already a list, single item list if a float, int, or string without commas, or a multi-item list if a comma-delimited string. ansible.module\_utils.common.validation.check\_type\_path(_value_)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_path "Link to this definition") Verify the provided value is a string or convert it to a string, then return the expanded path ansible.module\_utils.common.validation.check\_type\_raw(_value_)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_raw "Link to this definition") Returns the raw value ansible.module\_utils.common.validation.check\_type\_str(_value_, _allow\_conversion\=True_, _param\=None_, _prefix\=''_)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_str "Link to this definition") Verify that the value is a string or convert to a string. Since unexpected changes can sometimes happen when converting to a string, `allow_conversion` controls whether or not the value will be converted or a TypeError will be raised if the value is not a string and would be converted Parameters: * **value** – Value to validate or convert to a string * **allow\_conversion** – Whether to convert the string and return it or raise a TypeError Returns: Original value if it is a string, the value converted to a string if allow\_conversion=True, or raises a TypeError if allow\_conversion=False. ansible.module\_utils.common.validation.count\_terms(_terms_, _parameters_)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.validation.count_terms "Link to this definition") Count the number of occurrences of a key in a given dictionary Parameters: * **terms** – String or iterable of values to check * **parameters** – Dictionary of parameters Returns: An integer that is the number of occurrences of the terms values in the provided dictionary. Errors[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#module-ansible.module_utils.errors "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------- _exception_ ansible.module\_utils.errors.AnsibleFallbackNotFound[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.errors.AnsibleFallbackNotFound "Link to this definition") Fallback validator was not found _exception_ ansible.module\_utils.errors.AnsibleValidationError(_message_)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.errors.AnsibleValidationError "Link to this definition") Single argument spec validation error error\_message[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.errors.AnsibleValidationError.error_message "Link to this definition") The error message passed in when the exception was raised. _property_ msg[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.errors.AnsibleValidationError.msg "Link to this definition") The error message passed in when the exception was raised. _exception_ ansible.module\_utils.errors.AnsibleValidationErrorMultiple(_errors\=None_)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.errors.AnsibleValidationErrorMultiple "Link to this definition") Multiple argument spec validation errors errors[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.errors.AnsibleValidationErrorMultiple.errors "Link to this definition") [`list`](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.14)") of [`AnsibleValidationError`](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.errors.AnsibleValidationError "ansible.module_utils.errors.AnsibleValidationError") objects _property_ msg[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.errors.AnsibleValidationErrorMultiple.msg "Link to this definition") The first message from the first error in `errors`. _property_ messages[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.errors.AnsibleValidationErrorMultiple.messages "Link to this definition") [`list`](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.14)") of each error message in `errors`. append(_error_)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.errors.AnsibleValidationErrorMultiple.append "Link to this definition") Append a new error to `self.errors`. Only [`AnsibleValidationError`](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.errors.AnsibleValidationError "ansible.module_utils.errors.AnsibleValidationError") should be added. extend(_errors_)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.errors.AnsibleValidationErrorMultiple.extend "Link to this definition") Append each item in `errors` to `self.errors`. Only [`AnsibleValidationError`](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.errors.AnsibleValidationError "ansible.module_utils.errors.AnsibleValidationError") should be added. _exception_ ansible.module\_utils.errors.AliasError(_message_)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.errors.AliasError "Link to this definition") Error handling aliases _exception_ ansible.module\_utils.errors.ArgumentTypeError(_message_)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.errors.ArgumentTypeError "Link to this definition") Error with parameter type _exception_ ansible.module\_utils.errors.ArgumentValueError(_message_)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.errors.ArgumentValueError "Link to this definition") Error with parameter value _exception_ ansible.module\_utils.errors.DeprecationError(_message_)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.errors.DeprecationError "Link to this definition") Error processing parameter deprecations _exception_ ansible.module\_utils.errors.ElementError(_message_)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.errors.ElementError "Link to this definition") Error when validating elements _exception_ ansible.module\_utils.errors.MutuallyExclusiveError(_message_)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.errors.MutuallyExclusiveError "Link to this definition") Mutually exclusive parameters were supplied _exception_ ansible.module\_utils.errors.NoLogError(_message_)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.errors.NoLogError "Link to this definition") Error converting no\_log values _exception_ ansible.module\_utils.errors.RequiredByError(_message_)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.errors.RequiredByError "Link to this definition") Error with parameters that are required by other parameters _exception_ ansible.module\_utils.errors.RequiredDefaultError(_message_)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.errors.RequiredDefaultError "Link to this definition") A required parameter was assigned a default value _exception_ ansible.module\_utils.errors.RequiredError(_message_)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.errors.RequiredError "Link to this definition") Missing a required parameter _exception_ ansible.module\_utils.errors.RequiredIfError(_message_)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.errors.RequiredIfError "Link to this definition") Error with conditionally required parameters _exception_ ansible.module\_utils.errors.RequiredOneOfError(_message_)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.errors.RequiredOneOfError "Link to this definition") Error with parameters where at least one is required _exception_ ansible.module\_utils.errors.RequiredTogetherError(_message_)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.errors.RequiredTogetherError "Link to this definition") Error with parameters that are required together _exception_ ansible.module\_utils.errors.SubParameterTypeError(_message_)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.errors.SubParameterTypeError "Link to this definition") Incorrect type for subparameter _exception_ ansible.module\_utils.errors.UnsupportedError(_message_)[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.errors.UnsupportedError "Link to this definition") Unsupported parameters were supplied --- # Ansible Community Guide — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * Ansible Community Guide * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/community/index.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Ansible Community Guide[](https://docs.ansible.com/projects/ansible/latest/community/index.html#ansible-community-guide "Link to this heading") ================================================================================================================================================= Note **Making Open Source More Inclusive** 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) . Welcome to the Ansible Community Guide! In the Ansible community, our mission is to produce, maintain, and popularize simple, flexible, and powerful open-source software tools tailored to automating a large variety of tasks. We strive to innovate in making infrastructure configuration and management as effortless and efficient as possible with automation, enabling people to focus on their core objectives. We welcome members from all skill levels to participate in our open, inclusive, and vibrant community. Whether you are an expert or just beginning your journey with Ansible, you are encouraged to contribute, share insights, and collaborate with fellow enthusiasts! The purpose of this guide is to teach you everything you need to know about being a contributing member of the Ansible community. All types of contributions are welcome and necessary for Ansible’s continued success. * [Getting started](https://docs.ansible.com/projects/ansible/latest/community/getting_started.html) * [Community Code of Conduct](https://docs.ansible.com/projects/ansible/latest/community/code_of_conduct.html) * [Developer Certificate Of Origin](https://docs.ansible.com/projects/ansible/latest/community/developer_certificate_of_origin.html) * [Communicating with the Ansible community](https://docs.ansible.com/projects/ansible/latest/community/communication.html) * [How can I help?](https://docs.ansible.com/projects/ansible/latest/community/how_can_I_help.html) * [Other ways to get involved](https://docs.ansible.com/projects/ansible/latest/community/getting_started.html#other-ways-to-get-involved) * [Contributor path](https://docs.ansible.com/projects/ansible/latest/community/contributor_path.html) * [Determine your area of interest](https://docs.ansible.com/projects/ansible/latest/community/contributor_path.html#determine-your-area-of-interest) * [Find the corresponding project](https://docs.ansible.com/projects/ansible/latest/community/contributor_path.html#find-the-corresponding-project) * [Learn](https://docs.ansible.com/projects/ansible/latest/community/contributor_path.html#learn) * [Making your first contribution](https://docs.ansible.com/projects/ansible/latest/community/contributor_path.html#making-your-first-contribution) * [Continue to contribute](https://docs.ansible.com/projects/ansible/latest/community/contributor_path.html#continue-to-contribute) * [Teach others](https://docs.ansible.com/projects/ansible/latest/community/contributor_path.html#teach-others) * [Become a collection maintainer](https://docs.ansible.com/projects/ansible/latest/community/contributor_path.html#become-a-collection-maintainer) * [Become a steering committee member](https://docs.ansible.com/projects/ansible/latest/community/contributor_path.html#become-a-steering-committee-member) --- # Building an inventory — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * [Getting started with Ansible](https://docs.ansible.com/projects/ansible/latest/getting_started/index.html) * Building an inventory * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/getting_started/get_started_inventory.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Building an inventory[](https://docs.ansible.com/projects/ansible/latest/getting_started/get_started_inventory.html#building-an-inventory "Link to this heading") =================================================================================================================================================================== Inventories organize managed nodes in centralized files that provide Ansible with system information and network locations. Using an inventory file, Ansible can manage a large number of hosts with a single command. To complete the following steps, you will need the IP address or fully qualified domain name (FQDN) of at least one host system. For demonstration purposes, the host could be running locally in a container or a virtual machine. You must also ensure that your public SSH key is added to the `authorized_keys` file on each host. Continue getting started with Ansible and build an inventory as follows: 1. Create a file named `inventory.ini` in the `ansible_quickstart` directory that you created in the [preceding step](https://docs.ansible.com/projects/ansible/latest/getting_started/get_started_ansible.html#get-started-ansible) . 2. Add a new `[myhosts]` group to the `inventory.ini` file and specify the IP address or fully qualified domain name (FQDN) of each host system. \[myhosts\] 192.0.2.50 192.0.2.51 192.0.2.52 3. Verify your inventory. ansible-inventory \-i inventory.ini \--list 4. Ping the `myhosts` group in your inventory. ansible myhosts \-m ping \-i inventory.ini Note Pass the `-u` option with the `ansible` command if the username is different on the control node and the managed node(s). 192.0.2.50 | SUCCESS => { "ansible\_facts": { "discovered\_interpreter\_python": "/usr/bin/python3" }, "changed": false, "ping": "pong" } 192.0.2.51 | SUCCESS => { "ansible\_facts": { "discovered\_interpreter\_python": "/usr/bin/python3" }, "changed": false, "ping": "pong" } 192.0.2.52 | SUCCESS => { "ansible\_facts": { "discovered\_interpreter\_python": "/usr/bin/python3" }, "changed": false, "ping": "pong" } Congratulations, you have successfully built an inventory. Continue getting started with Ansible by [creating a playbook](https://docs.ansible.com/projects/ansible/latest/getting_started/get_started_playbook.html#get-started-playbook) . Inventories in INI or YAML format[](https://docs.ansible.com/projects/ansible/latest/getting_started/get_started_inventory.html#inventories-in-ini-or-yaml-format "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can create inventories in either `INI` files or in `YAML`. In most cases, such as the example in the preceding steps, `INI` files are straightforward and easy to read for a small number of managed nodes. Creating an inventory in `YAML` format becomes a sensible option as the number of managed nodes increases. For example, the following is an equivalent of the `inventory.ini` that declares unique names for managed nodes and uses the `ansible_host` field: myhosts: hosts: my\_host\_01: ansible\_host: 192.0.2.50 my\_host\_02: ansible\_host: 192.0.2.51 my\_host\_03: ansible\_host: 192.0.2.52 Tips for building inventories[](https://docs.ansible.com/projects/ansible/latest/getting_started/get_started_inventory.html#tips-for-building-inventories "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * Ensure that group names are meaningful and unique. Group names are also case sensitive. * Avoid spaces, hyphens, and preceding numbers (use `floor_19`, not `19th_floor`) in group names. * Group hosts in your inventory logically according to their **What**, **Where**, and **When**. What Group hosts according to the topology, for example: db, web, leaf, spine. Where Group hosts by geographic location, for example: datacenter, region, floor, building. When Group hosts by stage, for example: development, test, staging, production. ### Use metagroups[](https://docs.ansible.com/projects/ansible/latest/getting_started/get_started_inventory.html#use-metagroups "Link to this heading") Create a metagroup that organizes multiple groups in your inventory with the following syntax: metagroupname: children: The following inventory illustrates a basic structure for a data center. This example inventory contains a `network` metagroup that includes all network devices and a `datacenter` metagroup that includes the `network` group and all webservers. leafs: hosts: leaf01: ansible\_host: 192.0.2.100 leaf02: ansible\_host: 192.0.2.110 spines: hosts: spine01: ansible\_host: 192.0.2.120 spine02: ansible\_host: 192.0.2.130 network: children: leafs: spines: webservers: hosts: webserver01: ansible\_host: 192.0.2.140 webserver02: ansible\_host: 192.0.2.150 datacenter: children: network: webservers: ### Create variables[](https://docs.ansible.com/projects/ansible/latest/getting_started/get_started_inventory.html#create-variables "Link to this heading") Variables set values for managed nodes, such as the IP address, FQDN, operating system, and SSH user, so you do not need to pass them when running Ansible commands. Variables can apply to specific hosts. webservers: hosts: webserver01: ansible\_host: 192.0.2.140 http\_port: 80 webserver02: ansible\_host: 192.0.2.150 http\_port: 443 Variables can also apply to all hosts in a group. webservers: hosts: webserver01: ansible\_host: 192.0.2.140 http\_port: 80 webserver02: ansible\_host: 192.0.2.150 http\_port: 443 vars: ansible\_user: my\_server\_user See also [How to build your inventory](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#intro-inventory) Learn more about inventories in `YAML` or `INI` format. [Adding variables to inventory](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#variables-in-inventory) Find out more about inventory variables and their syntax. [Ansible Vault](https://docs.ansible.com/projects/ansible/latest/vault_guide/vault.html#vault) Find out how to encrypt sensitive content in your inventory such as passwords and keys. --- # Running your EE — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * [Getting started with Execution Environments](https://docs.ansible.com/projects/ansible/latest/getting_started_ee/index.html) * Running your EE * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/getting_started_ee/run_execution_environment.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Running your EE[](https://docs.ansible.com/projects/ansible/latest/getting_started_ee/run_execution_environment.html#running-your-ee "Link to this heading") ============================================================================================================================================================== You can run your EE on the command line against `localhost` or a remote target using `ansible-navigator`. Note There are other tools besides `ansible-navigator` you can run EEs with. Run against localhost[](https://docs.ansible.com/projects/ansible/latest/getting_started_ee/run_execution_environment.html#run-against-localhost "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- 1. Create a `test_localhost.yml` playbook. \- name: Gather and print local facts hosts: localhost become: true gather\_facts: true tasks: \- name: Print facts ansible.builtin.debug: var: ansible\_facts 2. Run the playbook inside the `postgresql_ee` EE. ansible-navigator run test\_localhost.yml \--execution-environment-image postgresql\_ee \--mode stdout \--pull-policy missing \--container-options\='--user=0' You may notice the facts being gathered are about the container and not the developer machine. This is because the ansible playbook was run inside the container. Run against a remote target[](https://docs.ansible.com/projects/ansible/latest/getting_started_ee/run_execution_environment.html#run-against-a-remote-target "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Before you start, ensure you have the following: > * At least one IP address or resolvable hostname for a remote target. > > * Valid credentials for the remote host. > > * A user with sudo permissions on the remote host. > Execute a playbook inside the `postgresql_ee` EE against a remote host machine as in the following example: 1. Create a directory for inventory files. mkdir inventory 2. Create the `hosts.yml` inventory file in the `inventory` directory. all: hosts: 192.168.0.2 \# Replace with the IP of your target host 3. Create a `test_remote.yml` playbook. \- name: Gather and print facts hosts: all become: true gather\_facts: true tasks: \- name: Print facts ansible.builtin.debug: var: ansible\_facts 4. Run the playbook inside the `postgresql_ee` EE. Replace `student` with the appropriate username. Some arguments in the command can be optional depending on your target host authentication method. ansible-navigator run test\_remote.yml \-i inventory \--execution-environment-image postgresql\_ee:latest \--mode stdout \--pull-policy missing \--enable-prompts \-u student \-k \-K See also [Execution Environment Definition](https://ansible-builder.readthedocs.io/en/stable/definition/) Provides information about the about Execution Environment definition file and available options. [Ansible Builder CLI usage](https://ansible-builder.readthedocs.io/en/stable/usage/) Provides details about using Ansible Builder. [Ansible Navigator documentation](https://ansible-navigator.readthedocs.io/) Provides details about using Ansible Navigator. [Running a local container registry for EEs](https://forum.ansible.com/t/running-local-container-registry-for-execution-environments/206) This guide in the Ansible community forum explains how to set up a local registry for your Execution Environment images. --- # Building your first Execution Environment — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * [Getting started with Execution Environments](https://docs.ansible.com/projects/ansible/latest/getting_started_ee/index.html) * Building your first Execution Environment * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/getting_started_ee/build_execution_environment.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Building your first Execution Environment[](https://docs.ansible.com/projects/ansible/latest/getting_started_ee/build_execution_environment.html#building-your-first-execution-environment "Link to this heading") ==================================================================================================================================================================================================================== We are going to build an EE that represents an Ansible control node containing standard packages such as `ansible-core` and Python in addition to an Ansible collection (`community.postgresql`) and its dependency (the `psycopg2-binary` Python connector). To build your first EE: 1. Create a project folder on your filesystem. mkdir my\_first\_ee && cd my\_first\_ee 2. Create a `execution-environment.yml` file that specifies dependencies to include in the image. version: 3 images: base\_image: name: registry.fedoraproject.org/fedora:42 dependencies: python\_interpreter: package\_system: python3 ansible\_core: package\_pip: ansible-core ansible\_runner: package\_pip: ansible-runner system: \- openssh-clients \- sshpass galaxy: collections: \- name: community.postgresql Note The psycopg2-binary Python package is included in the requirements.txt file for the collection. For collections that do not include requirements.txt files, you need to specify Python dependencies explicitly. See the [Ansible Builder documentation](https://ansible-builder.readthedocs.io/en/stable/definition/) for details. 3. Build a EE container image called `postgresql_ee`. If you use docker, add the `--container-runtime docker` argument. ansible-builder build \--tag postgresql\_ee 4. List container images to verify that you built it successfully. podman image list localhost/postgresql\_ee latest 2e866777269b 6 minutes ago 1.11 GB You can verify the image you created by inspecting the `Containerfile` or `Dockerfile` in the `context` directory to view its configuration. less context/Containerfile You can also use Ansible Navigator to view detailed information about the image. Run the ansible-navigator command, type `:images` in the TUI, and then choose `postgresql_ee`. Proceed to [Running your EE](https://docs.ansible.com/projects/ansible/latest/getting_started_ee/run_execution_environment.html#running-custom-execution-environment) and test the EE you just built. See also [Running a local container registry for Execution Environments](https://forum.ansible.com/t/running-a-local-container-registry-for-execution-environments/206) This guide in the Ansible community forum explains how to set up a local registry for your Execution Environment images. --- # Playbook Keywords — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * Playbook Keywords * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/templates/playbooks_keywords.rst.j2?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Playbook Keywords[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/playbooks_keywords.html#playbook-keywords "Link to this heading") ============================================================================================================================================================= These are the keywords available on common playbook objects. Keywords are one of several sources for configuring Ansible behavior. See [Controlling how Ansible behaves: precedence rules](https://docs.ansible.com/projects/ansible/latest/reference_appendices/general_precedence.html#general-precedence-rules) for details on the relative precedence of each source. Note Please note: * Aliases for the directives are not reflected here, nor are mutable ones. For example, [action](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Action) in task can be substituted by the name of any Ansible module. * The keywords do not have `version_added` information at this time * Some keywords set defaults for the objects inside of them rather than for the objects themselves [Play](https://docs.ansible.com/projects/ansible/latest/reference_appendices/playbooks_keywords.html#id2) [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/playbooks_keywords.html#play "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- > any\_errors\_fatal > > Force any un-handled task errors on any host to propagate to all hosts and end the play. > > become > > Boolean that controls if privilege escalation is used or not on [Task](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Task) > execution. Implemented by the become plugin. See [Become plugins](https://docs.ansible.com/projects/ansible/latest/plugins/become.html#become-plugins) > . > > become\_exe > > Path to the executable used to elevate privileges. Implemented by the become plugin. See [Become plugins](https://docs.ansible.com/projects/ansible/latest/plugins/become.html#become-plugins) > . > > become\_flags > > A string of flag(s) to pass to the privilege escalation program when [become](https://docs.ansible.com/projects/ansible/2.9/reference_appendices/playbooks_keywords.html#term-50 "(in Ansible v2.9)") > is True. > > become\_method > > Which method of privilege escalation to use (such as sudo or su). > > become\_user > > User that you ‘become’ after using privilege escalation. The remote/login user must have permissions to become this user. > > check\_mode > > A boolean that controls if a task is run normally or avoids changes to the target and tries to report what it would have done (check mode/dry run). See [Validating tasks: check mode and diff mode](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_checkmode.html#check-mode-dry) > . > > collections > > List of collection namespaces to search for modules, plugins, and roles. See [Using collections in a playbook](https://docs.ansible.com/projects/ansible/latest/collections_guide/collections_using_playbooks.html#collections-using-playbook) > > Note > > Tasks within a role do not inherit the value of `collections` from the play. To have a role search a list of collections, use the `collections` keyword in `meta/main.yml` within a role. > > connection > > Allows you to change the connection plugin used for tasks to execute on the target. See [Using connection plugins](https://docs.ansible.com/projects/ansible/latest/plugins/connection.html#using-connection) > . > > debugger > > Enable debugging tasks based on the state of the task result. See [Debugging tasks](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_debugger.html#playbook-debugger) > . > > diff > > Toggle to make tasks return ‘diff’ information or not. > > environment > > A dictionary that gets converted into environment vars to be provided for the task upon execution. This can ONLY be used with modules. This is not supported for any other type of plugins nor Ansible itself nor its configuration, it just sets the variables for the code responsible for executing the task. This is not a recommended way to pass in confidential data. > > fact\_path > > Set the fact path option for the fact gathering plugin controlled by [gather\_facts](https://docs.ansible.com/projects/ansible/2.9/reference_appendices/playbooks_keywords.html#term-gather_facts "(in Ansible v2.9)") > . > > force\_handlers > > Will force notified handler execution for hosts even if they failed during the play. Will not trigger if the play itself fails. > > gather\_facts > > A boolean that controls if the play will automatically run the ‘setup’ task to gather facts for the hosts. > > gather\_subset > > Allows you to pass subset options to the fact gathering plugin controlled by [gather\_facts](https://docs.ansible.com/projects/ansible/2.9/reference_appendices/playbooks_keywords.html#term-gather_facts "(in Ansible v2.9)") > . > > gather\_timeout > > Allows you to set the timeout for the fact gathering plugin controlled by [gather\_facts](https://docs.ansible.com/projects/ansible/2.9/reference_appendices/playbooks_keywords.html#term-gather_facts "(in Ansible v2.9)") > . > > handlers > > A section with tasks that are treated as handlers, these won’t get executed normally, only when notified after each section of tasks is complete. A handler’s listen field is not templatable. > > hosts > > A list of groups, hosts or host pattern that translates into a list of hosts that are the play’s target. > > ignore\_errors > > Boolean that allows you to ignore task failures and continue with play. It does not affect connection errors. > > ignore\_unreachable > > Boolean that allows you to ignore task failures due to an unreachable host and continue with the play. This does not affect other task errors (see [ignore\_errors](https://docs.ansible.com/projects/ansible/2.9/reference_appendices/playbooks_keywords.html#term-63 "(in Ansible v2.9)") > ) but is useful for groups of volatile/ephemeral hosts. > > max\_fail\_percentage > > can be used to abort the run after a given percentage of hosts in the current batch has failed. This only works on linear or linear-derived strategies. > > module\_defaults > > Specifies default parameter values for modules. > > name > > Identifier. Can be used for documentation, or in tasks/handlers. > > no\_log > > Boolean that controls information disclosure. > > order > > Controls the sorting of hosts as they are used for executing the play. Possible values are inventory (default), sorted, reverse\_sorted, reverse\_inventory and shuffle. > > port > > Used to override the default port used in a connection. > > post\_tasks > > A list of tasks to execute after the [tasks](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Tasks) > section. > > pre\_tasks > > A list of tasks to execute before [roles](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Roles) > . > > remote\_user > > User used to log into the target via the connection plugin. > > roles > > List of roles to be imported into the play > > run\_once > > Boolean that will bypass the host loop, forcing the task to attempt to execute on the first host available and afterward apply any results and facts to all active hosts in the same batch. > > serial > > Explicitly define how Ansible batches the execution of the current play on the play’s target. See [Setting the batch size with serial](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_strategies.html#rolling-update-batch-size) > . > > strategy > > Allows you to choose the strategy plugin to use for the play. See [Strategy plugins](https://docs.ansible.com/projects/ansible/latest/plugins/strategy.html#strategy-plugins) > . > > tags > > Tags applied to the task or included tasks, this allows selecting subsets of tasks from the command line. > > tasks > > Main list of tasks to execute in the play, they run after [roles](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Roles) > and before [post\_tasks](https://docs.ansible.com/projects/ansible/2.9/reference_appendices/playbooks_keywords.html#term-post_tasks "(in Ansible v2.9)") > . > > throttle > > Limit the number of concurrent task runs on task, block and playbook level. This is independent of the forks and serial settings, but cannot be set higher than those limits. For example, if forks is set to 10 and the throttle is set to 15, at most 10 hosts will be operated on in parallel. > > timeout > > Time limit for the task action to execute in, if exceeded, Ansible will interrupt the process. Timeout does not include templating or looping. > > validate\_argspec > > UNDOCUMENTED!! > > vars > > Dictionary/map of variables > > vars\_files > > List of files that contain vars to include in the play. > > vars\_prompt > > list of variables to prompt for. [Role](https://docs.ansible.com/projects/ansible/latest/reference_appendices/playbooks_keywords.html#id3) [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/playbooks_keywords.html#role "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- > any\_errors\_fatal > > Force any un-handled task errors on any host to propagate to all hosts and end the play. > > become > > Boolean that controls if privilege escalation is used or not on [Task](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Task) > execution. Implemented by the become plugin. See [Become plugins](https://docs.ansible.com/projects/ansible/latest/plugins/become.html#become-plugins) > . > > become\_exe > > Path to the executable used to elevate privileges. Implemented by the become plugin. See [Become plugins](https://docs.ansible.com/projects/ansible/latest/plugins/become.html#become-plugins) > . > > become\_flags > > A string of flag(s) to pass to the privilege escalation program when [become](https://docs.ansible.com/projects/ansible/2.9/reference_appendices/playbooks_keywords.html#term-50 "(in Ansible v2.9)") > is True. > > become\_method > > Which method of privilege escalation to use (such as sudo or su). > > become\_user > > User that you ‘become’ after using privilege escalation. The remote/login user must have permissions to become this user. > > check\_mode > > A boolean that controls if a task is run normally or avoids changes to the target and tries to report what it would have done (check mode/dry run). See [Validating tasks: check mode and diff mode](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_checkmode.html#check-mode-dry) > . > > collections > > List of collection namespaces to search for modules, plugins, and roles. See [Using collections in a playbook](https://docs.ansible.com/projects/ansible/latest/collections_guide/collections_using_playbooks.html#collections-using-playbook) > > Note > > Tasks within a role do not inherit the value of `collections` from the play. To have a role search a list of collections, use the `collections` keyword in `meta/main.yml` within a role. > > connection > > Allows you to change the connection plugin used for tasks to execute on the target. See [Using connection plugins](https://docs.ansible.com/projects/ansible/latest/plugins/connection.html#using-connection) > . > > debugger > > Enable debugging tasks based on the state of the task result. See [Debugging tasks](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_debugger.html#playbook-debugger) > . > > delegate\_facts > > Boolean that allows you to apply facts to a delegated host instead of inventory\_hostname. > > delegate\_to > > Host to execute task instead of the target (inventory\_hostname). Connection vars from the delegated host will also be used for the task. > > diff > > Toggle to make tasks return ‘diff’ information or not. > > environment > > A dictionary that gets converted into environment vars to be provided for the task upon execution. This can ONLY be used with modules. This is not supported for any other type of plugins nor Ansible itself nor its configuration, it just sets the variables for the code responsible for executing the task. This is not a recommended way to pass in confidential data. > > ignore\_errors > > Boolean that allows you to ignore task failures and continue with play. It does not affect connection errors. > > ignore\_unreachable > > Boolean that allows you to ignore task failures due to an unreachable host and continue with the play. This does not affect other task errors (see [ignore\_errors](https://docs.ansible.com/projects/ansible/2.9/reference_appendices/playbooks_keywords.html#term-63 "(in Ansible v2.9)") > ) but is useful for groups of volatile/ephemeral hosts. > > module\_defaults > > Specifies default parameter values for modules. > > name > > Identifier. Can be used for documentation, or in tasks/handlers. > > no\_log > > Boolean that controls information disclosure. > > port > > Used to override the default port used in a connection. > > remote\_user > > User used to log into the target via the connection plugin. > > run\_once > > Boolean that will bypass the host loop, forcing the task to attempt to execute on the first host available and afterward apply any results and facts to all active hosts in the same batch. > > tags > > Tags applied to the task or included tasks, this allows selecting subsets of tasks from the command line. > > throttle > > Limit the number of concurrent task runs on task, block and playbook level. This is independent of the forks and serial settings, but cannot be set higher than those limits. For example, if forks is set to 10 and the throttle is set to 15, at most 10 hosts will be operated on in parallel. > > timeout > > Time limit for the task action to execute in, if exceeded, Ansible will interrupt the process. Timeout does not include templating or looping. > > vars > > Dictionary/map of variables > > when > > Conditional expression, determines if an iteration of a task is run or not. [Block](https://docs.ansible.com/projects/ansible/latest/reference_appendices/playbooks_keywords.html#id4) [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/playbooks_keywords.html#block "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- > always > > List of tasks, in a block, that execute no matter if there is an error in the block or not. > > any\_errors\_fatal > > Force any un-handled task errors on any host to propagate to all hosts and end the play. > > become > > Boolean that controls if privilege escalation is used or not on [Task](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Task) > execution. Implemented by the become plugin. See [Become plugins](https://docs.ansible.com/projects/ansible/latest/plugins/become.html#become-plugins) > . > > become\_exe > > Path to the executable used to elevate privileges. Implemented by the become plugin. See [Become plugins](https://docs.ansible.com/projects/ansible/latest/plugins/become.html#become-plugins) > . > > become\_flags > > A string of flag(s) to pass to the privilege escalation program when [become](https://docs.ansible.com/projects/ansible/2.9/reference_appendices/playbooks_keywords.html#term-50 "(in Ansible v2.9)") > is True. > > become\_method > > Which method of privilege escalation to use (such as sudo or su). > > become\_user > > User that you ‘become’ after using privilege escalation. The remote/login user must have permissions to become this user. > > block > > List of tasks in a block. > > check\_mode > > A boolean that controls if a task is run normally or avoids changes to the target and tries to report what it would have done (check mode/dry run). See [Validating tasks: check mode and diff mode](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_checkmode.html#check-mode-dry) > . > > collections > > List of collection namespaces to search for modules, plugins, and roles. See [Using collections in a playbook](https://docs.ansible.com/projects/ansible/latest/collections_guide/collections_using_playbooks.html#collections-using-playbook) > > Note > > Tasks within a role do not inherit the value of `collections` from the play. To have a role search a list of collections, use the `collections` keyword in `meta/main.yml` within a role. > > connection > > Allows you to change the connection plugin used for tasks to execute on the target. See [Using connection plugins](https://docs.ansible.com/projects/ansible/latest/plugins/connection.html#using-connection) > . > > debugger > > Enable debugging tasks based on the state of the task result. See [Debugging tasks](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_debugger.html#playbook-debugger) > . > > delegate\_facts > > Boolean that allows you to apply facts to a delegated host instead of inventory\_hostname. > > delegate\_to > > Host to execute task instead of the target (inventory\_hostname). Connection vars from the delegated host will also be used for the task. > > diff > > Toggle to make tasks return ‘diff’ information or not. > > environment > > A dictionary that gets converted into environment vars to be provided for the task upon execution. This can ONLY be used with modules. This is not supported for any other type of plugins nor Ansible itself nor its configuration, it just sets the variables for the code responsible for executing the task. This is not a recommended way to pass in confidential data. > > ignore\_errors > > Boolean that allows you to ignore task failures and continue with play. It does not affect connection errors. > > ignore\_unreachable > > Boolean that allows you to ignore task failures due to an unreachable host and continue with the play. This does not affect other task errors (see [ignore\_errors](https://docs.ansible.com/projects/ansible/2.9/reference_appendices/playbooks_keywords.html#term-63 "(in Ansible v2.9)") > ) but is useful for groups of volatile/ephemeral hosts. > > module\_defaults > > Specifies default parameter values for modules. > > name > > Identifier. Can be used for documentation, or in tasks/handlers. > > no\_log > > Boolean that controls information disclosure. > > notify > > List of handlers to notify when the task returns a ‘changed=True’ status. > > port > > Used to override the default port used in a connection. > > remote\_user > > User used to log into the target via the connection plugin. > > rescue > > List of tasks in a [block](https://docs.ansible.com/projects/ansible/2.9/reference_appendices/playbooks_keywords.html#term-block "(in Ansible v2.9)") > that run if there is a task error in the main [block](https://docs.ansible.com/projects/ansible/2.9/reference_appendices/playbooks_keywords.html#term-block "(in Ansible v2.9)") > list. > > run\_once > > Boolean that will bypass the host loop, forcing the task to attempt to execute on the first host available and afterward apply any results and facts to all active hosts in the same batch. > > tags > > Tags applied to the task or included tasks, this allows selecting subsets of tasks from the command line. > > throttle > > Limit the number of concurrent task runs on task, block and playbook level. This is independent of the forks and serial settings, but cannot be set higher than those limits. For example, if forks is set to 10 and the throttle is set to 15, at most 10 hosts will be operated on in parallel. > > timeout > > Time limit for the task action to execute in, if exceeded, Ansible will interrupt the process. Timeout does not include templating or looping. > > vars > > Dictionary/map of variables > > when > > Conditional expression, determines if an iteration of a task is run or not. [Task](https://docs.ansible.com/projects/ansible/latest/reference_appendices/playbooks_keywords.html#id5) [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/playbooks_keywords.html#task "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- > action > > The ‘action’ to execute for a task, it normally translates into a C(module) or action plugin. > > any\_errors\_fatal > > Force any un-handled task errors on any host to propagate to all hosts and end the play. > > args > > A secondary way to add arguments into a task. Takes a dictionary in which keys map to options and values. > > async > > Run a task asynchronously if the C(action) supports this; the value is the maximum runtime in seconds. > > become > > Boolean that controls if privilege escalation is used or not on [Task](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Task) > execution. Implemented by the become plugin. See [Become plugins](https://docs.ansible.com/projects/ansible/latest/plugins/become.html#become-plugins) > . > > become\_exe > > Path to the executable used to elevate privileges. Implemented by the become plugin. See [Become plugins](https://docs.ansible.com/projects/ansible/latest/plugins/become.html#become-plugins) > . > > become\_flags > > A string of flag(s) to pass to the privilege escalation program when [become](https://docs.ansible.com/projects/ansible/2.9/reference_appendices/playbooks_keywords.html#term-50 "(in Ansible v2.9)") > is True. > > become\_method > > Which method of privilege escalation to use (such as sudo or su). > > become\_user > > User that you ‘become’ after using privilege escalation. The remote/login user must have permissions to become this user. > > changed\_when > > Conditional expression that overrides the task’s normal ‘changed’ status. > > check\_mode > > A boolean that controls if a task is run normally or avoids changes to the target and tries to report what it would have done (check mode/dry run). See [Validating tasks: check mode and diff mode](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_checkmode.html#check-mode-dry) > . > > collections > > List of collection namespaces to search for modules, plugins, and roles. See [Using collections in a playbook](https://docs.ansible.com/projects/ansible/latest/collections_guide/collections_using_playbooks.html#collections-using-playbook) > > Note > > Tasks within a role do not inherit the value of `collections` from the play. To have a role search a list of collections, use the `collections` keyword in `meta/main.yml` within a role. > > connection > > Allows you to change the connection plugin used for tasks to execute on the target. See [Using connection plugins](https://docs.ansible.com/projects/ansible/latest/plugins/connection.html#using-connection) > . > > debugger > > Enable debugging tasks based on the state of the task result. See [Debugging tasks](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_debugger.html#playbook-debugger) > . > > delay > > Number of seconds to delay between retries. This setting is only used in combination with [until](https://docs.ansible.com/projects/ansible/2.9/reference_appendices/playbooks_keywords.html#term-until "(in Ansible v2.9)") > . > > delegate\_facts > > Boolean that allows you to apply facts to a delegated host instead of inventory\_hostname. > > delegate\_to > > Host to execute task instead of the target (inventory\_hostname). Connection vars from the delegated host will also be used for the task. > > diff > > Toggle to make tasks return ‘diff’ information or not. > > environment > > A dictionary that gets converted into environment vars to be provided for the task upon execution. This can ONLY be used with modules. This is not supported for any other type of plugins nor Ansible itself nor its configuration, it just sets the variables for the code responsible for executing the task. This is not a recommended way to pass in confidential data. > > failed\_when > > Conditional expression that overrides the task’s normal ‘failed’ status. > > ignore\_errors > > Boolean that allows you to ignore task failures and continue with play. It does not affect connection errors. > > ignore\_unreachable > > Boolean that allows you to ignore task failures due to an unreachable host and continue with the play. This does not affect other task errors (see [ignore\_errors](https://docs.ansible.com/projects/ansible/2.9/reference_appendices/playbooks_keywords.html#term-63 "(in Ansible v2.9)") > ) but is useful for groups of volatile/ephemeral hosts. > > local\_action > > Same as action but also implies `delegate_to: localhost` > > loop > > Takes a list for the task to iterate over, saving each list element into the `item` variable (configurable via loop\_control) > > loop\_control > > Several keys here allow you to modify/set loop behavior in a task. See [Adding controls to loops](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_loops.html#loop-control) > . > > module\_defaults > > Specifies default parameter values for modules. > > name > > Identifier. Can be used for documentation, or in tasks/handlers. > > no\_log > > Boolean that controls information disclosure. > > notify > > List of handlers to notify when the task returns a ‘changed=True’ status. > > poll > > Sets the polling interval in seconds for async tasks (default 10s). > > port > > Used to override the default port used in a connection. > > register > > Name of variable that will contain task status and module return data. > > remote\_user > > User used to log into the target via the connection plugin. > > retries > > Number of retries before giving up in a [until](https://docs.ansible.com/projects/ansible/2.9/reference_appendices/playbooks_keywords.html#term-until "(in Ansible v2.9)") > loop. This setting is only used in combination with [until](https://docs.ansible.com/projects/ansible/2.9/reference_appendices/playbooks_keywords.html#term-until "(in Ansible v2.9)") > . > > run\_once > > Boolean that will bypass the host loop, forcing the task to attempt to execute on the first host available and afterward apply any results and facts to all active hosts in the same batch. > > tags > > Tags applied to the task or included tasks, this allows selecting subsets of tasks from the command line. > > throttle > > Limit the number of concurrent task runs on task, block and playbook level. This is independent of the forks and serial settings, but cannot be set higher than those limits. For example, if forks is set to 10 and the throttle is set to 15, at most 10 hosts will be operated on in parallel. > > timeout > > Time limit for the task action to execute in, if exceeded, Ansible will interrupt the process. Timeout does not include templating or looping. > > until > > This keyword implies a ‘[retries](https://docs.ansible.com/projects/ansible/2.9/reference_appendices/playbooks_keywords.html#term-retries "(in Ansible v2.9)") > loop’ that will go on until the condition supplied here is met or we hit the [retries](https://docs.ansible.com/projects/ansible/2.9/reference_appendices/playbooks_keywords.html#term-retries "(in Ansible v2.9)") > limit. > > vars > > Dictionary/map of variables > > when > > Conditional expression, determines if an iteration of a task is run or not. > > with\_ > > The same as `loop` but magically adds the output of any lookup plugin to generate the item list. --- # Ansible documentation style guide — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * Ansible documentation style guide * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/dev_guide/style_guide/index.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Ansible documentation style guide[](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#ansible-documentation-style-guide "Link to this heading") ================================================================================================================================================================================= Welcome to the Ansible style guide! To create clear, concise, consistent, useful materials on docs.ansible.com, follow these guidelines: [Linguistic guidelines](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#id3) [](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#linguistic-guidelines "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- We want the Ansible documentation to be: * clear * direct * conversational * easy to translate We want reading the docs to feel like having an experienced, friendly colleague explain how Ansible works. ### [Stylistic cheat-sheet](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#id4) [](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#stylistic-cheat-sheet "Link to this heading") This cheat-sheet illustrates a few rules that help achieve the “Ansible tone”: | Rule | Good example | Bad example | | --- | --- | --- | | Use active voice | You can run a task by | A task can be run by | | Use the present tense | This command creates a | This command will create a | | Address the reader | As you expand your inventory | When the number of managed nodes grows | | Use standard English | Return to this page | Hop back to this page | | Use American English | The color of the output | The colour of the output | ### [Title and heading case](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#id5) [](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#title-and-heading-case "Link to this heading") Titles and headings should be written in sentence case. For example, this section’s title is `Title and heading case`, not `Title and Heading Case` or `TITLE AND HEADING CASE`. ### [Avoid using Latin phrases](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#id6) [](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#avoid-using-latin-phrases "Link to this heading") 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. Use the following English terms in place of Latin terms or abbreviations: | Latin | English | | --- | --- | | i.e | in other words | | e.g. | for example | | etc | and so on | | via | by/ through | | vs./versus | rather than/against | [reStructuredText guidelines](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#id7) [](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#restructuredtext-guidelines "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The Ansible documentation is written in reStructuredText and processed by Sphinx. We follow these technical or mechanical guidelines on all rST pages: ### [Heading notation](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#id8) [](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#heading-notation "Link to this heading") [Section headings 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 headings. To make our documents easy to read and to edit, we follow a standard set of heading notations. We use: * `###` with overline, for parts: ############### Developer guide ############### * `***` with overline, for chapters: \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\* Ansible style guide \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\* * `===` for sections: Mechanical guidelines \===================== * `---` for subsections: Internal navigation \------------------- * `^^^` for sub-subsections: Adding anchors ^^^^^^^^^^^^^^ * `"""` for paragraphs: Paragraph that needs a title """""""""""""""""""""""""""" ### [Syntax highlighting - Pygments](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#id9) [](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#syntax-highlighting-pygments "Link to this heading") 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. The Ansible documentation allows the following values: * none (no highlighting) * ansible-output (a custom lexer for Ansible output) * bash * console * csharp * diff * ini * jinja * json * md * powershell * python * rst * sh * shell * shell-session * text * yaml * yaml+jinja For example, you can highlight Python code using following syntax: .. code-block:: python def my\_beautiful\_python\_code(): pass ### [Internal navigation](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#id10) [](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#internal-navigation "Link to this heading") [Anchors (also called labels) and links](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref) 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 headings, can also include a local TOC. Note Avoid raw URLs. RST and sphinx allow `https://my.example.com`, but this is unhelpful for those using screen readers. `:ref:` links automatically pick up the heading from the anchor, but for external links, always use the `` `link title `_ `` format. #### [Adding anchors](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#id11) [](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#adding-anchors "Link to this heading") * Include at least one anchor on every page * Place the main anchor above the main heading * If the file has a unique title, use that for the main page anchor: .. \_unique\_page:: * You may also add anchors elsewhere on the page #### [Adding internal links](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#id12) [](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#adding-internal-links "Link to this heading") * All internal links must use `:ref:` syntax. These links both point to the anchor defined above: :ref:\`unique\_page\` :ref:\`this page \` The second example adds custom text for the link. #### [Adding links to modules and plugins](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#id13) [](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#adding-links-to-modules-and-plugins "Link to this heading") Use the `:ansplugin:` RST role to link to modules and plugins using their Fully Qualified Collection Name (FQCN): The ansible.builtin.copy module can be linked with :ansplugin:\`ansible.builtin.copy#module\` If you want to specify an explicit type, use: :ansplugin:\`the copy module \` This displays as “The ansible.builtin.copy module can be linked with [ansible.builtin.copy](https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/copy_module.html#ansible-collections-ansible-builtin-copy-module) ” and “If you want to specify an explicit type, use: [the copy module](https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/copy_module.html#ansible-collections-ansible-builtin-copy-module) ”. Instead of `#module`, you can also specify `#` to reference to a plugin of type ``: :ansplugin:\`arista.eos.eos\_config \` :ansplugin:\`kubernetes.core.kubectl connection plugin \` :ansplugin:\`ansible.builtin.file lookup plugin \` Note `ansible.builtin` is the FQCN for modules included in ansible-core. #### [Adding links to module and plugin options and return values](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#id14) [](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#adding-links-to-module-and-plugin-options-and-return-values "Link to this heading") Use the `:ansopt:` and `:ansretval:` roles to reference options and return values of modules and plugins while showing the option’s resp. return value’s name and optionally a value. Use the `:ansoptref:` and `:ansretvalref:` roles to reference options and return values of modules and plugins while displaying a provided title. The following example shows their usage: :ansopt:\`ansible.builtin.file#module:path\` references the \`\`path\`\` parameter of the \`\`ansible.builtin.file\`\` module; :ansopt:\`ansible.builtin.file#module:path=/root/.ssh/known\_hosts\` shows the assignment \`\`path=/root/.ssh/known\_hosts\`\` as a clickable link. You can :ansoptref:\`provide a path \` to the :ansplugin:\`ansible.builtin.file#module\`; its value is :ansretvalref:\`returned as a return value \`. :ansretval:\`ansible.builtin.stat#module:stat.exists\` references the \`\`stat.exists\`\` return value of the \`\`ansible.builtin.stat\`\` module. You can also use \`\`=\`\` as for option values: :ansretval:\`ansible.builtin.stat#module:stat.exists=true\` shows \`\`stat.exists=true\`\`. :ansopt:\`foo\` and :ansopt:\`foo=bar\` use the same markup for an option and an option assignment without a link; the same is true for return values: :ansretval:\`foo\` and :ansretval:\`foo=bar\`. This displays as: > `**[path](https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/file_module.html#ansible-collections-ansible-builtin-file-module-parameter-path) **` references the `path` parameter of the `ansible.builtin.file` module; `[path=/root/.ssh/known_hosts](https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/file_module.html#ansible-collections-ansible-builtin-file-module-parameter-path) ` shows the assignment `path=/root/.ssh/known_hosts` as a clickable link. > > You can [provide a path](https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/file_module.html#ansible-collections-ansible-builtin-file-module-parameter-path) > to the [ansible.builtin.file](https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/file_module.html#ansible-collections-ansible-builtin-file-module) > ; its value is [returned as a return value](https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/file_module.html#ansible-collections-ansible-builtin-file-module-return-path) > . > > `[stat.exists](https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/stat_module.html#ansible-collections-ansible-builtin-stat-module-return-stat-exists) ` references the `stat.exists` return value of the `ansible.builtin.stat` module. You can also use `=` as for option values: `[stat.exists=true](https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/stat_module.html#ansible-collections-ansible-builtin-stat-module-return-stat-exists) ` shows `stat.exists=true`. > > `**foo**` and `foo=bar` use the same markup for an option and an option assignment without a link; the same is true for return values: `foo` and `foo=bar`. For both option and return values, `.` is used to reference suboptions and contained return values. Array stubs (`[...]`) can be used to indicate that something is a list, for example the `:ansretval:` argument `ansible.builtin.service_facts#module:ansible_facts.services['systemd'].state` references the `ansible_facts.services.state` return value of the `ansible.builtin.service_facts` module (`[ansible_facts.services['systemd'].state](https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/service_facts_module.html#ansible-collections-ansible-builtin-service-facts-module-return-ansible-facts-services-state) `). #### [Adding local TOCs](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#id15) [](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#adding-local-tocs "Link to this heading") 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: * place it below, not above, the main heading and (optionally) introductory text * use the `:local:` directive so the page’s main heading is not included * do not include a title The syntax is: .. contents:: :local: [Markdown guidelines](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#id16) [](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#markdown-guidelines "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ Some Ansible ecosystem documentation is written in markdown and processed by mkdocs. We follow these technical or mechanical guidelines on all .md pages: ### [Heading notation](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#id17) [](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#headings-style-md "Link to this heading") [Section headings in markdown](https://daringfireball.net/projects/markdown/syntax#header) can use a variety of notations. To make our documents easy to read and to edit, we follow a standard set of heading notations. We use: * `#` for page titles: \# Installation * `##` for section headings: \## Installing on Linux Subsections add an additional `#` for each subsection. We recommend not going beyond `####` as that suggests a deeply nested document that could present better as multiple pages. ### [Linking in Markdown](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#id18) [](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#linking-in-markdown "Link to this heading") Using Mkdocs, you can format internal links \`\_ using the file name of the local file instead of an external URL. \[configuration\](/configuration) You can also link directly to a heading within a file Use the lower-case form of the heading. \[dependency\](/configuration/#dependency) External links use a similar format with the external URL. \[Ansible Documentation\](https://docs.ansible.com) ### [Code blocks](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#id19) [](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#code-blocks "Link to this heading") Markdown supports code blocks in the following format. \`\`\`text docs/ index.md user-guide/getting-started.md user-guide/configuration-options.md license.md \`\`\` [Accessibility guidelines](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#id20) [](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#accessibility-guidelines "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Ansible documentation has a goal to be more accessible. Use the following guidelines to help us reach this goal. ### [Images and alternative text](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#id21) [](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#images-and-alternative-text "Link to this heading") Ensure all icons, images, diagrams, and non text elements have a meaningful alternative-text description. Do not include screen captures of CLI output. Use a code block instead. To add alt text in rst: > .. image:: path/networkdiag.png > :width: 400 > :alt: SpiffyCorp network diagram To add alt text in md: > !\[SpiffyCorp network diagram\](path/networkdiag.png) ### [Links and hypertext](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#id22) [](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#links-and-hypertext "Link to this heading") URLs and cross-reference links have descriptive text that conveys information about the content of the linked target. See [Internal navigation](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#style-links) for how to format links in RST and see [Linking in Markdown](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#style-links-md) for Markdown. ### [Tables](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#id23) [](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#tables "Link to this heading") Tables have a simple, logical reading order from left to right, and top to bottom. Tables include a heading row and avoid empty or blank table cells. Label tables with a descriptive title. For RST: > .. table:: File descriptions > > +----------+----------------------------+ > |File |Purpose | > +==========+============================+ > |foo.txt |foo configuration settings | > +----------+----------------------------+ > |bar.txt |bar configuration settings | > +----------+----------------------------+ For Markdown: > \#### File descriptions > > |File |Purpose | > |---------- | -------------------------- | > |foo.txt | foo configuration settings | > |bar.txt | bar configuration settings | ### [Colors and other visual information](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#id24) [](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#colors-and-other-visual-information "Link to this heading") > * Avoid instructions that rely solely on sensory characteristics. For example, do not use `Click the square, blue button to continue.` > > * Convey information by methods and not by color alone. > > * Ensure there is sufficient contrast between foreground and background text or graphical elements in images and diagrams. > > * Instructions for navigating through an interface make sense without directional indicators such as left, right, above, and below. > ### [Accessibility resources](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#id25) [](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#accessibility-resources "Link to this heading") Use the following resources to help test your documentation changes: * [axe DevTools browser extension](https://chrome.google.com/webstore/detail/axe-devtools-web-accessib/lhdoppojpmngadmnindnejefpokejbdd?hl=en-US&_ga=2.98933278.1490638154.1645821120-953800914.1645821120) - Highlights accessibility issues on a website page. * [WAVE browser extension](https://wave.webaim.org/extension/) from WebAIM - another accessibility tester. * [Orca screen reader](https://help.gnome.org/users/orca/stable/) - Common tool used by people with vision impairments. * [color filter](https://www.toptal.com/designers/colorfilter/) - For color-blind testing. [More resources](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#id26) [](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#more-resources "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- These pages offer more help with grammatical, stylistic, and technical rules for documentation. * [Basic rules](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/basic_rules.html) * [Voice Style](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/voice_style.html) * [Trademark Usage](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/trademarks.html) * [Grammar and Punctuation](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/grammar_punctuation.html) * [Spelling - Word Usage - Common Words and Phrases to Use and Avoid](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/spelling_word_choice.html) * [Preferred terminology](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/preferred_terms.html) * [Writing documentation so search can find it](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/search_hints.html) * [Resources](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/resources.html) See also [Contributing to the Ansible Documentation](https://docs.ansible.com/projects/ansible/latest/community/documentation_contributions.html#community-documentation-contributions) How to contribute to the Ansible documentation [Testing the documentation locally](https://docs.ansible.com/projects/ansible/latest/community/documentation_contributions.html#testing-documentation-locally) How to build the Ansible documentation [Communication](https://docs.ansible.com/projects/ansible/latest/community/communication.html#communication) Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide --- # Releases and maintenance — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * Releases and maintenance * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/reference_appendices/release_and_maintenance.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Releases and maintenance[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#releases-and-maintenance "Link to this heading") ================================================================================================================================================================================ This section describes release cycles, rules, and maintenance schedules for both Ansible community projects: the Ansible community package and `ansible-core`. The two projects have different versioning systems, maintenance structures, contents, and workflows. | Ansible community package | ansible-core | | --- | --- | | Uses new versioning (2.10, then 3.0.0) | Continues “classic Ansible” versioning (2.11, then 2.12) | | Follows semantic versioning rules | Does not use semantic versioning | | Maintains only one version at a time | Maintains latest version plus two older versions | | Includes language, runtime, and selected Collections | Includes language, runtime, and builtin plugins | | Developed and maintained in Collection repositories | Developed and maintained in ansible/ansible repository | Many community users install the Ansible community package. The Ansible community package offers the functionality that existed in Ansible 2.9, with more than 85 Collections containing thousands of modules and plugins. The `ansible-core` option is primarily for developers and users who want to install only the collections they need. [Release cycle overview](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#id25) [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#release-cycle-overview "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The two community releases are related - the release cycle follows this pattern: 1. Release of a new ansible-core major version, for example, ansible-core 2.11 * New release of ansible-core and two prior versions are now maintained (in this case, ansible-base 2.10, Ansible 2.9) * Work on new features for ansible-core continues in the `devel` branch 2. Collection freeze (no new Collections or new versions of existing Collections) on the Ansible community package 3. Release candidate for Ansible community package, testing, additional release candidates as necessary 4. Release of a new Ansible community package major version based on the new ansible-core, for example, Ansible 4.0.0 based on ansible-core 2.11 * Newest release of the Ansible community package is the only version now maintained * Work on new features continues in Collections * Individual Collections can make multiple minor and major releases 5. Minor releases of three maintained ansible-core versions every four weeks (2.11.1) 6. Minor releases of the single maintained Ansible community package version every four weeks (4.1.0) 7. Feature freeze on ansible-core 8. Release candidate for ansible-core, testing, additional release candidates as necessary 9. Release of the next ansible-core major version, cycle begins again ### [Ansible community package release cycle](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#id26) [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#ansible-community-package-release-cycle "Link to this heading") The Ansible community team typically releases two major versions of the community package per year, on a flexible release cycle that trails the release of `ansible-core`. This cycle can be extended to allow for larger changes to be properly implemented and tested before a new release is made available. See [Ansible Roadmap](https://docs.ansible.com/projects/ansible/latest/roadmap/ansible_roadmap_index.html#ansible-roadmaps) for upcoming release details. Between major versions, we release a new minor version of the Ansible community package every four weeks. Minor releases include new backwards-compatible features, modules and plugins, as well as bug fixes. Starting with version 2.10, the Ansible community team guarantees maintenance for only one major community package release at a time. For example, when Ansible 4.0.0 gets released, the team will stop making new 3.x releases. Community members may maintain older versions if desired. Note Each Ansible EOL version may issue one final maintenance release at or shortly after the first release of the next version. When this happens, the final maintenance release is EOL at the date it releases. Note Older, unmaintained versions of the Ansible community package might contain unfixed security vulnerabilities (_CVEs_). If you are using a release of the Ansible community package that is no longer maintained, we strongly encourage you to upgrade as soon as possible to benefit from the latest features and security fixes. Each major release of the Ansible community package accepts the latest released version of each included Collection and the latest released version of ansible-core. For specific schedules and deadlines, see the [Ansible Roadmap](https://docs.ansible.com/projects/ansible/latest/roadmap/ansible_roadmap_index.html#ansible-roadmaps) for each version. Major releases of the Ansible community package can contain breaking changes in the modules and other plugins within the included Collections and in core features. The Ansible community package follows semantic versioning rules. Minor releases of the Ansible community package accept only backwards-compatible changes in included Collections, that is, not Collections major releases. Collections must also use semantic versioning, so the Collection version numbers reflect this rule. For example, if Ansible 3.0.0 releases with community.general 2.0.0, then all minor releases of Ansible 3.x (such as Ansible 3.1.0 or Ansible 3.5.0) must include a 2.x release of community.general (such as 2.8.0 or 2.9.5) and not 3.x.x or later major releases. Work in Collections is tracked within the individual Collection repositories. You can refer to the [Ansible package porting guides](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guides.html#porting-guides) for tips on updating your playbooks to run on newer versions of Ansible. For Ansible 2.10 and later releases, you can install the Ansible package with `pip`. See [Installing Ansible](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#intro-installation-guide) for details. You can download older Ansible releases from [https://releases.ansible.com/ansible/](https://releases.ansible.com/ansible/) . ### [Ansible community changelogs](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#id27) [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#ansible-community-changelogs "Link to this heading") This table links to the changelogs for each major Ansible release. These changelogs contain the dates and significant changes in each minor release. | Ansible Community Package Release | Status | Core version dependency | | --- | --- | --- | | 14.0.0 | In development (unreleased) | 2.21 | | [13.x Changelogs](https://github.com/ansible-community/ansible-build-data/blob/main/13/CHANGELOG-v13.md) | Current- Latest | 2.20 | | [12.x Changelogs](https://github.com/ansible-community/ansible-build-data/blob/main/12/CHANGELOG-v12.md) | EOL in Dec 2025 | 2.19 | | [11.x Changelogs](https://github.com/ansible-community/ansible-build-data/blob/main/11/CHANGELOG-v11.md) | EOL in Dec 2025 | 2.18 | | [10.x Changelogs](https://github.com/ansible-community/ansible-build-data/blob/main/10/CHANGELOG-v10.md) | Unmaintained (end of life) | 2.17 | | [9.x Changelogs](https://github.com/ansible-community/ansible-build-data/blob/main/9/CHANGELOG-v9.rst) | Unmaintained (end of life) | 2.16 | | [8.x Changelogs](https://github.com/ansible-community/ansible-build-data/blob/main/8/CHANGELOG-v8.rst) | Unmaintained (end of life) | 2.15 | | [7.x Changelogs](https://github.com/ansible-community/ansible-build-data/blob/main/7/CHANGELOG-v7.rst) | Unmaintained (end of life) | 2.14 | | [6.x Changelogs](https://github.com/ansible-community/ansible-build-data/blob/main/6/CHANGELOG-v6.rst) | Unmaintained (end of life) | 2.13 | | [5.x Changelogs](https://github.com/ansible-community/ansible-build-data/blob/main/5/CHANGELOG-v5.rst) | Unmaintained (end of life) | 2.12 | | [4.x Changelogs](https://github.com/ansible-community/ansible-build-data/blob/main/4/CHANGELOG-v4.rst) | Unmaintained (end of life) | 2.11 | | [3.x Changelogs](https://github.com/ansible-community/ansible-build-data/blob/main/3/CHANGELOG-v3.rst) | Unmaintained (end of life) | 2.10 | | [2.10 Changelogs](https://github.com/ansible-community/ansible-build-data/blob/main/2.10/CHANGELOG-v2.10.rst) | Unmaintained (end of life) | 2.10 | ### [ansible-core release cycle](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#id28) [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#ansible-core-release-cycle "Link to this heading") `ansible-core` is developed and released on a flexible release cycle. We can extend this cycle to properly implement and test larger changes before a new release is made available. See [ansible-core Roadmaps](https://docs.ansible.com/projects/ansible/latest/roadmap/ansible_core_roadmap_index.html#ansible-core-roadmaps) for upcoming release details. `ansible-core` has a graduated maintenance structure that extends to three major releases. For more information, read about the [Development and maintenance workflows](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#development-and-stable-version-maintenance-workflow) or see the chart in [ansible-core control node Python support](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#release-schedule) for the degrees to which current releases are maintained. Note Older, unmaintained versions of `ansible-core` can contain unfixed security vulnerabilities (_CVEs_). If you are using a release of `ansible-core` that is no longer maintained, we strongly encourage you to upgrade as soon as possible to benefit from the latest features and security fixes. `ansible-core` maintenance continues for 3 releases. Thus the latest release receives security and general bug fixes when it is first released, security and critical bug fixes when the next `ansible-core` version is released, and **only** security fixes once the follow on to that version is released. You can refer to the [Ansible Core Porting Guides](https://docs.ansible.com/projects/ansible/latest/porting_guides/core_porting_guides.html#core-porting-guides) for tips on updating your playbooks to run on newer versions of `ansible-core`. You can install `ansible-core` with `pip`. See [Installing Ansible](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#intro-installation-guide) for details. ### [`ansible-core` control node Python support](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#id29) [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#ansible-core-control-node-python-support "Link to this heading") Starting with `ansible-core` version 2.12, each release includes control node support for the three most recently released Python versions. ### [`ansible-core` target node Python support](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#id30) [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#ansible-core-target-node-python-support "Link to this heading") Starting with `ansible-core` version 2.16, each release includes target node support for: * The 6 most recently released Python versions. * The 7 most recently released Python versions every 6th `ansible-core` release (2.16, 2.22, etc.) Support for Python 2.7 is included in `ansible-core` version 2.16 and earlier. ### [`ansible-core` target node PowerShell and Windows support](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#id31) [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#ansible-core-target-node-powershell-and-windows-support "Link to this heading") `ansible-core` on Windows supports the baseline version of PowerShell that each Windows version ships with. For example, Windows Server 2016 shipped with PowerShell 5.1 so Ansible will support PowerShell 5.1 for the life of Windows Server 2016 support. Support for each Windows version is determined by the Windows lifecycle policy and when each version reaches the extended end date. For example Windows Server 2012 and 2012 R2 extended end date was for October 10th 2023 while Windows Server 2016 is January 12th 2027. Windows support does not align with the 3 year Extended Security Updates (`ESU`) support from Microsoft which is a paid support option for products that are past the normal end of support date from Microsoft. ### [`ansible-core` support matrix](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#id32) [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#ansible-core-support-matrix "Link to this heading") This table links to the changelogs for each major `ansible-core` release. These changelogs contain the dates and significant changes in each minor release. Dates listed indicate the start date of the maintenance cycle. | Version | Support | End Of Life | Control Node Python | Target Python / PowerShell | | --- | --- | --- | --- | --- | | [2.20](https://github.com/ansible/ansible/blob/stable-2.20/changelogs/CHANGELOG-v2.20.rst) | GA: 03 Nov 2025

Critical: 18 May 2026

Security: 02 Nov 2026 | May 2027 | Python 3.12 - 3.14 | Python 3.9 - 3.14

PowerShell 5.1 | | [2.19](https://github.com/ansible/ansible/blob/stable-2.19/changelogs/CHANGELOG-v2.19.rst) | GA: 21 July 2025

Critical: 03 Nov 2025

Security: 18 May 2026 | Nov 2026 | Python 3.11 - 3.13 | Python 3.8 - 3.13

PowerShell 5.1 | | [2.18](https://github.com/ansible/ansible/blob/stable-2.18/changelogs/CHANGELOG-v2.18.rst) | GA: 04 Nov 2024

Critical: 19 May 2025

Security: 03 Nov 2025 | May 2026 | Python 3.11 - 3.13 | Python 3.8 - 3.13

PowerShell 5.1 | | [2.17](https://github.com/ansible/ansible/blob/stable-2.17/changelogs/CHANGELOG-v2.17.rst) | GA: 20 May 2024

Critical: 04 Nov 2024

Security: 19 May 2025 | **EOL**

Nov 2025 | Python 3.10 - 3.12 | Python 3.7 - 3.12

PowerShell 5.1 | | [2.16](https://github.com/ansible/ansible/blob/stable-2.16/changelogs/CHANGELOG-v2.16.rst) | GA: 06 Nov 2023

Critical: 20 May 2024

Security: Nov 2024 | **EOL**

July 2025 | Python 3.10 - 3.12 | Python 2.7

Python 3.6 - 3.12

Powershell 5.1 | | [2.15](https://github.com/ansible/ansible/blob/stable-2.15/changelogs/CHANGELOG-v2.15.rst) | GA: 22 May 2023

Critical: 06 Nov 2023

Security: 20 May 2024 | **EOL**

Nov 2024 | Python 3.9 - 3.11 | Python 2.7

Python 3.5 - 3.11

PowerShell 3 - 5.1 | | [2.14](https://github.com/ansible/ansible/blob/stable-2.14/changelogs/CHANGELOG-v2.14.rst) | GA: 07 Nov 2022

Critical: 22 May 2023

Security: 06 Nov 2023 | **EOL**

20 May 2024 | Python 3.9 - 3.11 | Python 2.7

Python 3.5 - 3.11

PowerShell 3 - 5.1 | | [2.13](https://github.com/ansible/ansible/blob/stable-2.13/changelogs/CHANGELOG-v2.13.rst) | GA: 23 May 2022

Critical: 07 Nov 2022

Security: 22 May 2023 | **EOL**

06 Nov 2023 | Python 3.8 - 3.10 | Python 2.7

Python 3.5 - 3.10

PowerShell 3 - 5.1 | | [2.12](https://github.com/ansible/ansible/blob/stable-2.12/changelogs/CHANGELOG-v2.12.rst) | GA: 08 Nov 2021

Critical: 23 May 2022

Security: 07 Nov 2022 | **EOL**

22 May 2023 | Python 3.8 - 3.10 | Python 2.6 - 2.7

Python 3.5 - 3.10

PowerShell 3 - 5.1 | | [2.11](https://github.com/ansible/ansible/blob/stable-2.11/changelogs/CHANGELOG-v2.11.rst) | GA: 26 Apr 2021

Critical: 08 Nov 2021

Security: 23 May 2022 | **EOL**

07 Nov 2022 | Python 2.7

Python 3.5 - 3.9 | Python 2.6 - 2.7

Python 3.5 - 3.9

PowerShell 3 - 5.1 | | [2.10](https://github.com/ansible/ansible/blob/stable-2.10/changelogs/CHANGELOG-v2.10.rst) | GA: 13 Aug 2020

Critical: 26 Apr 2021

Security: 08 Nov 2021 | **EOL**

23 May 2022 | Python 2.7

Python 3.5 - 3.9 | Python 2.6 - 2.7

Python 3.5 - 3.9

PowerShell 3 - 5.1 | | [2.9](https://github.com/ansible/ansible/blob/stable-2.9/changelogs/CHANGELOG-v2.9.rst) | GA: 31 Oct 2019

Critical: 13 Aug 2020

Security: 26 Apr 2021 | **EOL**

23 May 2022 | Python 2.7

Python 3.5 - 3.8 | Python 2.6 - 2.7

Python 3.5 - 3.8

PowerShell 3 - 5.1 | ### [`ansible-core` versioning](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#id33) [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#ansible-core-versioning "Link to this heading") The ansible-core project uses a historical versioning scheme, most similar to the versioning scheme used by Python. This scheme follows the formatting of `X.Y.Z` which is described in detail below. #### [What is the `X` in `X.Y.Z`?](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#id34) [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#what-is-the-x-in-x-y-z "Link to this heading") The `X` represents the internal architecture of `ansible-core`. The `X` here does not imply any form of compatibility, nor anything about the scope of the changes. * `v1` can be best described as the internal architecture revolving around `ansible.runner.Runner` as the “execution” engine * `v2` can be best described as the internal architecture revolving around the `TaskQueueManager`, `PlayIterator`, and the strategy as the “execution” engine #### [What is the `Y` in `X.Y.Z`?](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#id35) [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#what-is-the-y-in-x-y-z "Link to this heading") Approximately every 6 months, in May and November ansible-core releases a new _Major_ release. This is denoted by the `Y` in the `X.Y.Z` version scheme. Although the `Y` denotes the Major version, it is not referenced independently, and instead a Major version is indicated in the format of `X.Y`, such as `2.16`. As such, versions like `2.9.0`, `2.10.0`, `2.11.0`, `2.16.0` and `2.19.0` are all major releases. `X.Y.0` releases do not carry any guarantee of 100% backwards compatibility with the version before it. Some may be more or less impactful based on the scope of the work for the release. Check porting guides for changes that may necessitate user intervention. #### [What is the `Z` in `X.Y.Z`?](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#id36) [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#what-is-the-z-in-x-y-z "Link to this heading") This is the patch version. ansible-core operates on a 4 week patch schedule. The `Z` release of a major version will include bugfixes and security fixes as outlined in the [ansible-core support matrix](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#ansible-core-support-matrix) . [Preparing for a new release](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#id37) [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#preparing-for-a-new-release "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [Feature freezes](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#id38) [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#feature-freezes "Link to this heading") During final preparations for a new release, core developers and maintainers focus on improving the release candidate, not on adding or reviewing new features. We may impose a feature freeze. A feature freeze means that we delay new features and fixes unrelated to the pending release so we can create the new release as soon as possible. ### [Release candidates](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#id39) [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#release-candidates "Link to this heading") We create at least one release candidate before each new major release of Ansible or `ansible-core`. Release candidates allow the Ansible community to try out new features, test existing playbooks on the release candidate, and report bugs or issues they find. Ansible and `ansible-core` tag the first release candidate (RC1) which is usually scheduled to last five business days. If no major bugs or issues are identified during this period, the release candidate becomes the final release. If there are major problems with the first candidate, the team and the community fix them and tag a second release candidate (RC2). This second candidate lasts for a shorter duration than the first. If no problems have been reported for an RC2 after two business days, the second release candidate becomes the final release. If there are major problems in RC2, the cycle begins again with another release candidate and repeats until the maintainers agree that all major problems have been fixed. [Development and maintenance workflows](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#id40) [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#development-and-maintenance-workflows "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- In between releases, the Ansible community develops new features, maintains existing functionality, and fixes bugs in `ansible-core` and in the collections included in the Ansible community package. ### [Ansible community package workflow](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#id41) [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#ansible-community-package-workflow "Link to this heading") The Ansible community develops and maintains the features and functionality included in the Ansible community package in Collections repositories, with a workflow that looks like this: > * Developers add new features and bug fixes to the individual Collections, following each Collection’s rules on contributing. > > * Each new feature and each bug fix includes a changelog fragment describing the work. > > * Release engineers create a minor release for the current version every four weeks to ensure that the latest bug fixes are available to users. > > * At the end of the development period, the release engineers announce which Collections, and which major version of each included Collection, will be included in the next release of the Ansible community package. New Collections and new major versions may not be added after this, and the work of creating a new release begins. > We generally do not provide fixes for unmaintained releases of the Ansible community package, however, there can sometimes be exceptions for critical issues. Some Collections are maintained by the Ansible team, some by Partner organizations, and some by community teams. For more information on adding features or fixing bugs in Ansible-maintained Collections, see [Contributing to Ansible-maintained Collections](https://docs.ansible.com/projects/ansible/latest/community/contributing_maintained_collections.html#contributing-maintained-collections) . ### [ansible-core workflow](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#id42) [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#ansible-core-workflow "Link to this heading") The Ansible community develops and maintains `ansible-core` on [GitHub](https://github.com/ansible/ansible) , with a workflow that looks like this: > * Developers add new features and bug fixes to the `devel` branch. > > * Each new feature and each bug fix includes a changelog fragment describing the work. > > * The development team backports bug fixes to one, two, or three stable branches, depending on the severity of the bug. They do not backport new features. > > * Release engineers create a minor release for each maintained version every four weeks to ensure that the latest bug fixes are available to users. > > * At the end of the development period, the release engineers impose a feature freeze and the work of creating a new release begins. > We generally do not provide fixes for unmaintained releases of `ansible-core`, however, there can sometimes be exceptions for critical issues. For more information about adding features or fixing bugs in `ansible-core` see [The Ansible Development Cycle](https://docs.ansible.com/projects/ansible/latest/community/development_process.html#community-development-process) . ### [Generating changelogs](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#id43) [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#generating-changelogs "Link to this heading") We generate changelogs based on fragments. When creating new features for existing modules and plugins or fixing bugs, create a changelog fragment describing the change. A changelog entry is not needed for new modules or plugins. Details for those items will be generated from the module documentation. To add changelog fragments to Collections in the Ansible community package, we recommend the [antsibull-changelog utility](https://github.com/ansible-community/antsibull-changelog/blob/main/docs/changelogs.rst) . To add changelog fragments for new features and bug fixes in `ansible-core`, see the [changelog examples and instructions](https://docs.ansible.com/projects/ansible/latest/community/development_process.html#changelogs-how-to) in the Community Guide. [Deprecation cycles](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#id44) [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#deprecation-cycles "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Sometimes we remove a feature, normally in favor of a reimplementation that we hope does a better job. To do this we have a deprecation cycle. First we mark a feature as ‘deprecated’. This is normally accompanied with warnings to the user as to why we deprecated it, what alternatives they should switch to and when (which version) we are scheduled to remove the feature permanently. ### [Ansible community package deprecation cycle](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#id45) [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#ansible-community-package-deprecation-cycle "Link to this heading") Since Ansible is a package of individual collections, the deprecation cycle depends on the collection maintainers. We recommend the collection maintainers deprecate a feature in one Ansible major version and do not remove that feature for one year, or at least until the next major Ansible version. For example, deprecate the feature in 3.1.0 and do not remove the feature until 5.0.0 or 4.0.0 at the earliest. Collections should use semantic versioning, such that the major collection version cannot be changed within an Ansible major version. Therefore, the removal should not happen before the next major Ansible community package release. This is up to each collection maintainer and cannot be guaranteed. ### [ansible-core deprecation cycle](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#id46) [](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#ansible-core-deprecation-cycle "Link to this heading") The deprecation cycle in `ansible-core` is normally across 4 feature releases (2.x. where the x marks a feature release). The feature is normally removed in the 4th release after we announce the deprecation. For example, something deprecated in 2.10 will be removed in 2.13. The tracking is tied to the number of releases, not the release numbering itself. Although this is the standard, there are times where a deprecation cycle for a feature or behavior may have a longer or shorter deprecation cycle based on use or urgency of removal. Unintended or undocumented functionality may be removed without a deprecation cycle. In this context, unintended functionality refers specifically to emergent features that occur outside the release roadmap. See also [Committers Guidelines](https://docs.ansible.com/projects/ansible/latest/community/committer_guidelines.html#community-committer-guidelines) Guidelines for Ansible Core contributors and maintainers [Testing Strategies](https://docs.ansible.com/projects/ansible/latest/reference_appendices/test_strategies.html#testing-strategies) Testing strategies [Ansible Community Guide](https://docs.ansible.com/projects/ansible/latest/community/index.html#ansible-community-guide) Community information and contributing [Communication](https://docs.ansible.com/projects/ansible/latest/community/communication.html#communication) Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide --- # Installation Guide — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * Installation Guide * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/installation_guide/index.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Installation Guide[](https://docs.ansible.com/projects/ansible/latest/installation_guide/index.html#installation-guide "Link to this heading") ================================================================================================================================================ Welcome to the Ansible Installation Guide! * [Installing Ansible](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html) * [Control node requirements](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#control-node-requirements) * [Managed node requirements](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#managed-node-requirements) * [Node requirement summary](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#node-requirement-summary) * [Selecting an Ansible package and version to install](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#selecting-an-ansible-package-and-version-to-install) * [Installing and upgrading Ansible with pipx](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#installing-and-upgrading-ansible-with-pipx) * [Installing and upgrading Ansible with pip](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#installing-and-upgrading-ansible-with-pip) * [Installing Ansible to containers](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#installing-ansible-to-containers) * [Installing for development](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#installing-for-development) * [Confirming your installation](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#confirming-your-installation) * [Adding Ansible command shell completion](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#adding-ansible-command-shell-completion) * [Installing Ansible on specific operating systems](https://docs.ansible.com/projects/ansible/latest/installation_guide/installation_distros.html) * [Requirements for adding new distributions](https://docs.ansible.com/projects/ansible/latest/installation_guide/installation_distros.html#requirements-for-adding-new-distributions) * [Installing Ansible on Fedora Linux](https://docs.ansible.com/projects/ansible/latest/installation_guide/installation_distros.html#installing-ansible-on-fedora-linux) * [Installing Ansible from EPEL](https://docs.ansible.com/projects/ansible/latest/installation_guide/installation_distros.html#installing-ansible-from-epel) * [Installing Ansible on OpenSUSE Tumbleweed/Leap](https://docs.ansible.com/projects/ansible/latest/installation_guide/installation_distros.html#installing-ansible-on-opensuse-tumbleweed-leap) * [Installing Ansible on Ubuntu](https://docs.ansible.com/projects/ansible/latest/installation_guide/installation_distros.html#installing-ansible-on-ubuntu) * [Installing Ansible on Debian](https://docs.ansible.com/projects/ansible/latest/installation_guide/installation_distros.html#installing-ansible-on-debian) * [Installing Ansible on Arch Linux](https://docs.ansible.com/projects/ansible/latest/installation_guide/installation_distros.html#installing-ansible-on-arch-linux) * [Installing Ansible on Windows](https://docs.ansible.com/projects/ansible/latest/installation_guide/installation_distros.html#installing-ansible-on-windows) * [Configuring Ansible](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_configuration.html) * [Configuration file](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_configuration.html#configuration-file) * [Environmental configuration](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_configuration.html#environmental-configuration) * [Command line options](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_configuration.html#command-line-options) --- # Galaxy User Guide — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * Galaxy User Guide * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/galaxy/user_guide.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Galaxy User Guide[](https://docs.ansible.com/projects/ansible/latest/galaxy/user_guide.html#galaxy-user-guide "Link to this heading") ======================================================================================================================================= _Ansible Galaxy_ refers to the [Galaxy](https://galaxy.ansible.com/) website, a free site for finding, downloading, and sharing community developed collections and roles. Use Galaxy to jump-start your automation project with great content from the Ansible community. Galaxy provides pre-packaged units of work such as [roles](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#playbooks-reuse-roles) , and [collections](https://docs.ansible.com/projects/ansible/latest/collections_guide/index.html#collections) . The collection format provides a comprehensive package of automation that may include multiple playbooks, roles, modules, and plugins. See the [Galaxy documentation](https://ansible.readthedocs.io/projects/galaxy-ng/en/latest/) for full details on Galaxy. [Finding collections on Galaxy](https://docs.ansible.com/projects/ansible/latest/galaxy/user_guide.html#id1) [](https://docs.ansible.com/projects/ansible/latest/galaxy/user_guide.html#finding-collections-on-galaxy "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- To find collections on Galaxy: 1. Click Collections > Collections in the left-hand navigation. 2. Type in your search term. You can filter by keyword, tags, and namespaces. Galaxy presents a list of collections that match your search criteria. See [Using Ansible collections](https://docs.ansible.com/projects/ansible/latest/collections_guide/index.html#collections) for complete details on installing and using collections. [Finding roles on Galaxy](https://docs.ansible.com/projects/ansible/latest/galaxy/user_guide.html#id2) [](https://docs.ansible.com/projects/ansible/latest/galaxy/user_guide.html#finding-roles-on-galaxy "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- To find standalone roles (that is roles that are not part of a collection): 1. Click Roles > Roles in the left-hand navigation. 2. Type in your search term. You can filter by keyword, tags, and namespaces. Galaxy presents a list of roles that match your search criteria. You can optionally search the Galaxy database by tags, platforms, author and multiple keywords using the `ansible-galaxy` CLI command. $ ansible-galaxy role search elasticsearch \--author geerlingguy The search command will return a list of the first 1000 results matching your search: Found 6 roles matching your search: Name Description ---- ----------- geerlingguy.elasticsearch Elasticsearch for Linux. geerlingguy.elasticsearch-curator Elasticsearch curator for Linux. geerlingguy.filebeat Filebeat for Linux. geerlingguy.fluentd Fluentd for Linux. geerlingguy.kibana Kibana for Linux. ### [Get more information about a role](https://docs.ansible.com/projects/ansible/latest/galaxy/user_guide.html#id3) [](https://docs.ansible.com/projects/ansible/latest/galaxy/user_guide.html#get-more-information-about-a-role "Link to this heading") Use the `info` command to view more detail about a specific role: $ ansible-galaxy role info username.role\_name This returns everything found in Galaxy for the role: Role: username.role\_name description: Installs and configures a thing, a distributed, highly available NoSQL thing. active: True commit: c01947b7bc89ebc0b8a2e298b87ab416aed9dd57 commit\_message: Adding travis commit\_url: https://github.com/username/repo\_name/commit/c01947b7bc89ebc0b8a2e298b87ab company: My Company, Inc. created: 2015-12-08T14:17:52.773Z download\_count: 1 forks\_count: 0 github\_branch: main github\_repo: repo\_name github\_user: username id: 6381 is\_valid: True issue\_tracker\_url: license: Apache min\_ansible\_version: 2.15 modified: YYYY-MM-DDTHH:MM:SS.000Z namespace: username open\_issues\_count: 0 path: /Users/username/projects/roles role\_type: ANS stargazers\_count: 0 travis\_status\_url: https://travis-ci.org/username/repo\_name.svg?branch=main [Installing roles from Galaxy](https://docs.ansible.com/projects/ansible/latest/galaxy/user_guide.html#id4) [](https://docs.ansible.com/projects/ansible/latest/galaxy/user_guide.html#installing-roles-from-galaxy "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The `ansible-galaxy` command comes bundled with Ansible, and you can use it to install roles from Galaxy or directly from a Git based SCM. You can also use it to create a new role, remove roles, or perform tasks on the Galaxy website. The command line tool by default communicates with the Galaxy website API using the server address _https://galaxy.ansible.com_. If you run your own internal Galaxy server and want to use it instead of the default one, pass the `--server` option followed by the address of this galaxy server. You can set this option permanently by setting the Galaxy server value in your `ansible.cfg` file. See [GALAXY\_SERVER](https://docs.ansible.com/projects/ansible/latest/reference_appendices/config.html#galaxy-server) for details on setting the value in _ansible.cfg_ . ### [Installing roles](https://docs.ansible.com/projects/ansible/latest/galaxy/user_guide.html#id5) [](https://docs.ansible.com/projects/ansible/latest/galaxy/user_guide.html#installing-roles "Link to this heading") Use the `ansible-galaxy` command to download roles from the [Galaxy website](https://galaxy.ansible.com/) $ ansible-galaxy role install namespace.role\_name #### Setting where to install roles[](https://docs.ansible.com/projects/ansible/latest/galaxy/user_guide.html#setting-where-to-install-roles "Link to this heading") By default, Ansible downloads roles to the first writable directory in the default list of paths `~/.ansible/roles:/usr/share/ansible/roles:/etc/ansible/roles`. This installs roles in the home directory of the user running `ansible-galaxy`. You can override this with one of the following options: * Set the environment variable [`ANSIBLE_ROLES_PATH`](https://docs.ansible.com/projects/ansible/latest/reference_appendices/config.html#envvar-ANSIBLE_ROLES_PATH) in your session. * Use the `--roles-path` option for the `ansible-galaxy` command. * Define `roles_path` in an `ansible.cfg` file. The following provides an example of using `--roles-path` to install the role into the current working directory: $ ansible-galaxy role install \--roles-path . geerlingguy.apache See also [Configuring Ansible](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_configuration.html#intro-configuration) All about configuration files ### [Installing a specific version of a role](https://docs.ansible.com/projects/ansible/latest/galaxy/user_guide.html#id6) [](https://docs.ansible.com/projects/ansible/latest/galaxy/user_guide.html#installing-a-specific-version-of-a-role "Link to this heading") When the Galaxy server imports a role, it imports any Git tags matching the [Semantic Version](https://semver.org/) format as versions. In turn, you can download a specific version of a role by specifying one of the imported tags. To see the available versions for a role: 1. Locate the role on the Galaxy search page. 2. Click on the name to view more details, including the available versions. To install a specific version of a role from Galaxy, append a comma and the value of a GitHub release tag. For example: $ ansible-galaxy role install geerlingguy.apache,3.2.0 It is also possible to point directly to the Git repository and specify a branch name or commit hash as the version. For example, the following will install a specific commit: $ ansible-galaxy role install git+https://github.com/geerlingguy/ansible-role-apache.git,0b7cd353c0250e87a26e0499e59e7fd265cc2f25 ### [Installing multiple roles from a file](https://docs.ansible.com/projects/ansible/latest/galaxy/user_guide.html#id7) [](https://docs.ansible.com/projects/ansible/latest/galaxy/user_guide.html#installing-multiple-roles-from-a-file "Link to this heading") You can install multiple roles by including the roles in a `requirements.yml` file. The format of the file is YAML, and the file extension must be either _.yml_ or _.yaml_. Use the following command to install roles included in `requirements.yml:` $ ansible-galaxy install \-r requirements.yml Again, the extension is important. If the _.yml_ extension is left off, the `ansible-galaxy` CLI assumes the file is in an older, now deprecated, “basic” format. Each role in the file will have one or more of the following attributes: > src > > The source of the role. Use the format _namespace.role\_name_, if downloading from Galaxy; otherwise, provide a URL pointing to a repository within a Git based SCM. See the examples below. This is a required attribute. > > scm > > Specify the SCM. As of this writing only _git_ or _hg_ are allowed. See the examples below. Defaults to _git_. > > version: > > The version of the role to download. Provide a release tag value, commit hash, or branch name. Defaults to the branch set as a default in the repository, otherwise defaults to the _master_. > > name: > > Download the role to a specific name. Defaults to the Galaxy name when downloading from Galaxy, otherwise it defaults to the name of the repository. Use the following example as a guide for specifying roles in _requirements.yml_: \# from galaxy \- name: yatesr.timezone \# from locally cloned Git repository (git+file:// requires full paths) \- src: git+file:///home/bennojoy/nginx \# from GitHub \- src: https://github.com/bennojoy/nginx \# from GitHub, overriding the name and specifying a specific tag \- name: nginx\_role src: https://github.com/bennojoy/nginx version: main \# from GitHub, specifying a specific commit hash \- src: https://github.com/bennojoy/nginx version: "ee8aa41" \# from a webserver, where the role is packaged in a tar.gz \- name: http-role-gz src: https://some.webserver.example.com/files/main.tar.gz \# from a webserver, where the role is packaged in a tar.bz2 \- name: http-role-bz2 src: https://some.webserver.example.com/files/main.tar.bz2 \# from a webserver, where the role is packaged in a tar.xz (Python 3.x only) \- name: http-role-xz src: https://some.webserver.example.com/files/main.tar.xz \# from Bitbucket \- src: git+https://bitbucket.org/willthames/git-ansible-galaxy version: v1.4 \# from Bitbucket, alternative syntax and caveats \- src: https://bitbucket.org/willthames/hg-ansible-galaxy scm: hg \# from GitLab or other git-based scm, using git+ssh \- src: git@gitlab.company.com:mygroup/ansible-core.git scm: git version: "0.1" \# quoted, so YAML doesn't parse this as a floating-point value Warning Embedding credentials into a SCM URL 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..pushInsteadOf](https://git-scm.com/docs/git-config#Documentation/git-config.txt-urlltbasegtpushInsteadOf) in Git config to prevent your credentials from being exposed in logs. ### [Installing roles and collections from the same requirements.yml file](https://docs.ansible.com/projects/ansible/latest/galaxy/user_guide.html#id8) [](https://docs.ansible.com/projects/ansible/latest/galaxy/user_guide.html#installing-roles-and-collections-from-the-same-requirements-yml-file "Link to this heading") You can install roles and collections from the same requirements files \--- roles: \# Install a role from Ansible Galaxy. \- name: geerlingguy.java version: "1.9.6" \# note that ranges are not supported for roles collections: \# Install a collection from Ansible Galaxy. \- name: community.general version: ">=7.0.0" source: https://galaxy.ansible.com ### [Installing multiple roles from multiple files](https://docs.ansible.com/projects/ansible/latest/galaxy/user_guide.html#id9) [](https://docs.ansible.com/projects/ansible/latest/galaxy/user_guide.html#installing-multiple-roles-from-multiple-files "Link to this heading") For large projects, the `include` directive in a `requirements.yml` file provides the ability to split a large file into multiple smaller files. For example, a project may have a `requirements.yml` file, and a `webserver.yml` file. Below are the contents of the `webserver.yml` file: \# from github - src: https://github.com/bennojoy/nginx \# from Bitbucket - src: git+https://bitbucket.org/willthames/git-ansible-galaxy version: v1.4 The following shows the contents of the `requirements.yml` file that now includes the `webserver.yml` file: \# from galaxy - name: yatesr.timezone - include: /webserver.yml To install all the roles from both files, pass the root file, in this case `requirements.yml` on the command line, as follows: $ ansible-galaxy role install \-r requirements.yml ### [Dependencies](https://docs.ansible.com/projects/ansible/latest/galaxy/user_guide.html#id10) [](https://docs.ansible.com/projects/ansible/latest/galaxy/user_guide.html#dependencies "Link to this heading") Roles can also be dependent on other roles, and when you install a role that has dependencies, those dependencies will automatically be installed to the `roles_path`. There are two ways to define the dependencies of a role: * using `meta/requirements.yml` * using `meta/main.yml` #### Using `meta/requirements.yml`[](https://docs.ansible.com/projects/ansible/latest/galaxy/user_guide.html#using-meta-requirements-yml "Link to this heading") New in version 2.10. You can create the file `meta/requirements.yml` and define dependencies in the same format used for `requirements.yml` described in the [Installing multiple roles from a file](https://docs.ansible.com/projects/ansible/latest/galaxy/user_guide.html#installing-multiple-roles-from-a-file) section. From there, you can import or include the specified roles in your tasks. #### Using `meta/main.yml`[](https://docs.ansible.com/projects/ansible/latest/galaxy/user_guide.html#using-meta-main-yml "Link to this heading") Alternatively, you can specify role dependencies in the `meta/main.yml` file by providing a list of roles under the `dependencies` section. If the source of a role is Galaxy, you can simply specify the role in the format `namespace.role_name`. You can also use the more complex format in `requirements.yml`, allowing you to provide `src`, `scm`, `version`, and `name`. Dependencies installed that way, depending on other factors described below, will also be executed **before** this role is executed during play execution. To better understand how dependencies are handled during play execution, see [Roles](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#playbooks-reuse-roles) . The following shows an example `meta/main.yml` file with dependent roles: \--- dependencies: \- geerlingguy.java galaxy\_info: author: geerlingguy description: Elasticsearch for Linux. company: "Midwestern Mac, LLC" license: "license (BSD, MIT)" min\_ansible\_version: 2.4 galaxy\_tags: \- web \- system \- monitoring \- logging \- lucene \- elk \- elasticsearch Tags are inherited _down_ the dependency chain. In order for tags to be applied to a role and all its dependencies, the tag should be applied to the role, not to all the tasks within a role. Roles listed as dependencies are subject to conditionals and tag filtering, and may not execute fully depending on what tags and conditionals are applied. If the source of a role is Galaxy, specify the role in the format _namespace.role\_name_: dependencies: \- geerlingguy.apache \- geerlingguy.ansible Alternately, you can specify the role dependencies in the complex form used in `requirements.yml` as follows: dependencies: \- name: geerlingguy.ansible \- name: composer src: git+https://github.com/geerlingguy/ansible-role-composer.git version: 775396299f2da1f519f0d8885022ca2d6ee80ee8 Note Galaxy expects all role dependencies to exist in Galaxy, and therefore dependencies to be specified in the `namespace.role_name` format. If you import a role with a dependency where the `src` value is a URL, the import process will fail. ### [List installed roles](https://docs.ansible.com/projects/ansible/latest/galaxy/user_guide.html#id11) [](https://docs.ansible.com/projects/ansible/latest/galaxy/user_guide.html#list-installed-roles "Link to this heading") Use `list` to show the name and version of each role installed in the _roles\_path_. $ ansible-galaxy role list \- namespace-1.foo, v2.7.2 \- namespace2.bar, v2.6.2 ### [Remove an installed role](https://docs.ansible.com/projects/ansible/latest/galaxy/user_guide.html#id12) [](https://docs.ansible.com/projects/ansible/latest/galaxy/user_guide.html#remove-an-installed-role "Link to this heading") Use `remove` to delete a role from _roles\_path_: $ ansible-galaxy role remove namespace.role\_name See also [Using Ansible collections](https://docs.ansible.com/projects/ansible/latest/collections_guide/index.html#collections) Shareable collections of modules, playbooks and roles [Roles](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#playbooks-reuse-roles) Reusable tasks, handlers, and other files in a known directory structure [Working with command line tools](https://docs.ansible.com/projects/ansible/latest/command_guide/command_line_tools.html#command-line-tools) Perform other related operations --- # Installing Ansible — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * [Installation Guide](https://docs.ansible.com/projects/ansible/latest/installation_guide/index.html) * Installing Ansible * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/installation_guide/intro_installation.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Installing Ansible[](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#installing-ansible "Link to this heading") ============================================================================================================================================================= Ansible is an agentless automation tool that you install on a single host (referred to as the control node). From the control node, Ansible can manage an entire fleet of machines and other devices (referred to as managed nodes) remotely with SSH, Powershell remoting, and numerous other transports, all from a simple command-line interface with no databases or daemons required. [Control node requirements](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#id7) [](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#control-node-requirements "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- For your _control_ node (the machine that runs Ansible), you can use nearly any UNIX-like machine with Python installed. This includes Red Hat, Debian, Ubuntu, macOS, BSDs, and Windows under a [Windows Subsystem for Linux (WSL) distribution](https://docs.microsoft.com/en-us/windows/wsl/about) . Windows without WSL is not natively supported as a control node; see [Matt Davis’ blog post](http://blog.rolpdog.com/2020/03/why-no-ansible-controller-for-windows.html) for more information. [Managed node requirements](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#id8) [](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#managed-node-requirements "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The _managed_ node (the machine that Ansible is managing) does not require Ansible to be installed, but requires Python to run Ansible-generated Python code. The managed node also needs a user account that can connect through SSH to the node with an interactive POSIX shell. Note There can be exceptions in module requirements. For example, network modules do not require Python on the managed device. See documentation for the modules you use. [Node requirement summary](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#id9) [](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#node-requirement-summary "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can find details about control and managed node requirements, including Python versions, for each Ansible version in the [ansible-core control node Python support](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#support-life) and [ansible-core support matrix](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#ansible-core-support-matrix) sections. [Selecting an Ansible package and version to install](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#id10) [](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#selecting-an-ansible-package-and-version-to-install "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ Ansible’s community packages are distributed in two ways: * `ansible-core`: a minimalist language and runtime package containing a set of [built-in modules and plugins](https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/index.html#plugins-in-ansible-builtin) . * `ansible`: a much larger “batteries included” package, which adds a community-curated selection of [Ansible Collections](https://docs.ansible.com/projects/ansible/latest/collections_guide/index.html#collections) for automating a wide variety of devices. Choose the package that fits your needs. The following instructions use `ansible` as a package name, but you can substitute `ansible-core` if you prefer to start with the minimal package and separately install only the Ansible Collections you require. The `ansible` or `ansible-core` packages may be available in your operating systems package manager, and you are free to install these packages with your preferred method. For more information, see the [Installing Ansible on specific operating systems](https://docs.ansible.com/projects/ansible/latest/installation_guide/installation_distros.html#installing-distros) guide. These installation instructions only cover the officially supported means of installing the python packages with `pip`. See the [Ansible package release status table](https://docs.ansible.com/projects/ansible/latest/reference_appendices/release_and_maintenance.html#ansible-changelogs) for the `ansible-core` version included in the package. [Installing and upgrading Ansible with pipx](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#id11) [](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#installing-and-upgrading-ansible-with-pipx "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ On some systems, it may not be possible to install Ansible with `pip`, due to decisions made by the operating system developers. In such cases, `pipx` is a widely available alternative. These instructions will not go over the steps to install `pipx`; if those instructions are needed, please continue to the [pipx installation instructions](https://pipx.pypa.io/stable/#install-pipx) for more information. ### [Installing Ansible](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#id12) [](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#pipx-install "Link to this heading") Use `pipx` in your environment to install the full Ansible package: $ pipx install \--include-deps ansible You can install the minimal `ansible-core` package: $ pipx install ansible-core Alternately, you can install a specific version of `ansible-core`: $ pipx install ansible-core\==2.12.3 ### [Upgrading Ansible](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#id13) [](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#upgrading-ansible "Link to this heading") To upgrade an existing Ansible installation to the latest released version: $ pipx upgrade \--include-injected ansible ### [Installing Extra Python Dependencies](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#id14) [](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#installing-extra-python-dependencies "Link to this heading") To install additional python dependencies that may be needed, with the example of installing the `argcomplete` python package as described below: $ pipx inject ansible argcomplete Include the `--include-apps` option to make apps in the additional python dependency available on your PATH. This allows you to execute commands for those apps from the shell. $ pipx inject \--include-apps ansible argcomplete If you need to install dependencies from a requirements file, for example when installing the Azure collection, you can use `runpip`. $ pipx runpip ansible install \-r ~/.ansible/collections/ansible\_collections/azure/azcollection/requirements.txt [Installing and upgrading Ansible with pip](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#id15) [](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#installing-and-upgrading-ansible-with-pip "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [Locating Python](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#id16) [](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#locating-python "Link to this heading") Locate and remember the path to the Python interpreter you wish to use to run Ansible. The following instructions refer to this Python as `python3`. For example, if you have determined that you want the Python at `/usr/bin/python3.9` to be the one that you will install Ansible under, specify that instead of `python3`. ### [Ensuring `pip` is available](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#id17) [](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#ensuring-pip-is-available "Link to this heading") To verify whether `pip` is already installed for your preferred Python: $ python3 \-m pip \-V If all is well, you should see something like the following: $ python3 \-m pip \-V pip 21.0.1 from /usr/lib/python3.9/site-packages/pip (python 3.9) If so, `pip` is available, and you can move on to the [next step](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#pip-install) . If you see an error like `No module named pip`, you will need to install `pip` under your chosen Python interpreter before proceeding. This may mean installing an additional OS package (for example, `python3-pip`), or installing the latest `pip` directly from the Python Packaging Authority by running the following: $ curl https://bootstrap.pypa.io/get-pip.py \-o get-pip.py $ python3 get-pip.py \--user You may need to perform some additional configuration before you are able to run Ansible. See the Python documentation on [installing to the user site](https://packaging.python.org/tutorials/installing-packages/#installing-to-the-user-site) for more information. ### [Installing Ansible](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#id18) [](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#pip-install "Link to this heading") Use `pip` in your selected Python environment to install the full Ansible package for the current user: $ python3 \-m pip install \--user ansible You can install the minimal `ansible-core` package for the current user: $ python3 \-m pip install \--user ansible-core Alternately, you can install a specific version of `ansible-core`: $ python3 \-m pip install \--user ansible-core\==2.12.3 ### [Upgrading Ansible](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#id19) [](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#pip-upgrade "Link to this heading") To upgrade an existing Ansible installation in this Python environment to the latest released version, simply add `--upgrade` to the command above: $ python3 \-m pip install \--upgrade \--user ansible [Installing Ansible to containers](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#id20) [](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#installing-ansible-to-containers "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Instead of installing Ansible content manually, you can simply build an execution environment container image or use one of the available community images as your control node. See [Getting started with Execution Environments](https://docs.ansible.com/projects/ansible/latest/getting_started_ee/index.html#getting-started-ee-index) for details. [Installing for development](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#id21) [](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#installing-for-development "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- If you are testing new features, fixing bugs, or otherwise working with the development team on changes to the core code, you can install and run the source from GitHub. Note You should only install and run the `devel` branch if you are modifying `ansible-core` or trying out features under development. This is a rapidly changing source of code and can become unstable at any point. For more information on getting involved in the Ansible project, see the [Ansible Community Guide](https://docs.ansible.com/projects/ansible/latest/community/index.html#ansible-community-guide) . For more information on creating Ansible modules and Collections, see the [Developer Guide](https://docs.ansible.com/projects/ansible/latest/dev_guide/index.html#developer-guide) . ### [Installing `devel` from GitHub with `pip`](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#id22) [](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#installing-devel-from-github-with-pip "Link to this heading") You can install the `devel` branch of `ansible-core` directly from GitHub with `pip`: $ python3 \-m pip install \--user https://github.com/ansible/ansible/archive/devel.tar.gz You can replace `devel` in the URL mentioned above, with any other branch or tag on GitHub to install older versions of Ansible, tagged alpha or beta versions, and release candidates. ### [Running the `devel` branch from a clone](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#id23) [](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#running-the-devel-branch-from-a-clone "Link to this heading") `ansible-core` is easy to run from source. You do not need `root` permissions to use it and there is no software to actually install. No daemons or database setup are required. 1. Clone the `ansible-core` repository $ git clone https://github.com/ansible/ansible.git $ cd ./ansible 2. Setup the Ansible environment * Using Bash $ source ./hacking/env-setup * Using Fish $ source ./hacking/env-setup.fish * To suppress spurious warnings/errors, use `-q` $ source ./hacking/env-setup \-q 3. Install Python dependencies $ python3 \-m pip install \--user \-r ./requirements.txt 4. Update the `devel` branch of `ansible-core` on your local machine Use pull-with-rebase so any local changes are replayed. $ git pull \--rebase [Confirming your installation](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#id24) [](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#confirming-your-installation "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can test that Ansible is installed correctly by checking the version: $ ansible \--version The version displayed by this command is for the associated `ansible-core` package that has been installed. To check the version of the `ansible` package that has been installed: $ ansible-community \--version [Adding Ansible command shell completion](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#id25) [](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#adding-ansible-command-shell-completion "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ You can add shell completion of the Ansible command line utilities by installing an optional dependency called `argcomplete`. It supports bash, and has limited support for zsh and tcsh. For more information about installation and configuration, see the [argcomplete documentation](https://kislyuk.github.io/argcomplete/) . ### [Installing `argcomplete`](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#id26) [](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#installing-argcomplete "Link to this heading") If you chose the `pipx` installation instructions: $ pipx inject \--include-apps ansible argcomplete If you chose the `pip` installation instructions: $ python3 \-m pip install \--user argcomplete ### [Configuring `argcomplete`](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#id27) [](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#configuring-argcomplete "Link to this heading") There are 2 ways to configure `argcomplete` to allow shell completion of the Ansible command line utilities: globally or per command. #### [Global configuration](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#id28) [](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#global-configuration "Link to this heading") Global completion requires bash 4.2. $ activate-global-python-argcomplete \--user This will write a bash completion file to a user location. Use `--dest` to change the location or `sudo` to set up the completion globally. #### [Per command configuration](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#id29) [](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#per-command-configuration "Link to this heading") If you do not have bash 4.2, you must register each script independently. $ eval $(register-python-argcomplete ansible) $ eval $(register-python-argcomplete ansible-config) $ eval $(register-python-argcomplete ansible-console) $ eval $(register-python-argcomplete ansible-doc) $ eval $(register-python-argcomplete ansible-galaxy) $ eval $(register-python-argcomplete ansible-inventory) $ eval $(register-python-argcomplete ansible-playbook) $ eval $(register-python-argcomplete ansible-pull) $ eval $(register-python-argcomplete ansible-vault) You should place the above commands into your shell’s profile file such as `~/.profile` or `~/.bash_profile`. #### [Using `argcomplete` with zsh or tcsh](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#id30) [](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_installation.html#using-argcomplete-with-zsh-or-tcsh "Link to this heading") See the [argcomplete documentation](https://kislyuk.github.io/argcomplete/) . See also [Introduction to ad hoc commands](https://docs.ansible.com/projects/ansible/latest/command_guide/intro_adhoc.html#intro-adhoc) Examples of basic commands [Working with playbooks](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks.html#working-with-playbooks) Learning ansible’s configuration management language [How do I handle the package dependencies required by Ansible package dependencies during Ansible installation ?](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#installation-faqs) Ansible Installation related to FAQs [Forum](https://docs.ansible.com/projects/ansible/latest/community/communication.html#ansible-forum) Join the Ansible community forum to get help and share insights [Real-time chat](https://docs.ansible.com/projects/ansible/latest/community/communication.html#communication-irc) How to join Ansible chat channels --- # How to build your inventory — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * [Building Ansible inventories](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/index.html) * How to build your inventory * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/inventory_guide/intro_inventory.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * How to build your inventory[](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#how-to-build-your-inventory "Link to this heading") ============================================================================================================================================================================= Ansible automates tasks on managed nodes or “hosts” in your infrastructure by using a list or group of lists known as inventory. Ansible composes its inventory from one or more ‘inventory sources’. While one of these sources can be the list of host names you pass at the command line, most Ansible users create inventory files. Your inventory defines the managed nodes you automate and the variables associated with those hosts. You can also specify groups. Groups allow you to reference multiple associated hosts to target for your automation or to define variables in bulk. Once you define your inventory, you use [patterns](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_patterns.html#intro-patterns) to select the hosts or groups you want Ansible to run against. The simplest inventory is a single file that contains a list of hosts and groups. The default location for this file is `/etc/ansible/hosts`. You can specify a different inventory source or sources at the command line by using the `-i ` option or by using the configuration system. Ansible [Inventory plugins](https://docs.ansible.com/projects/ansible-core/devel/plugins/inventory.html#inventory-plugins) supports a range of formats and sources, which makes your inventory flexible and customizable. As your inventory expands, you might need more than a single file to organize your hosts and groups. You have the following common options beyond the `/etc/ansible/hosts` file: * You can generate an inventory dynamically. For example, you can use an inventory plugin to list resources in one or more cloud providers or other sources. See [Working with dynamic inventory](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_dynamic_inventory.html#intro-dynamic-inventory) . * You can use multiple sources for inventory, including both dynamic inventory and static files. See [Passing multiple inventory sources](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#using-multiple-inventory-sources) . * You can create a directory with multiple inventory sources, static or dynamic. See [Organizing inventory in a directory](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#inventory-directory) . The following YAML snippets include an ellipsis (…) to indicate that the snippets are part of a larger YAML file. You can find out more about YAML syntax at [YAML Basics](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/YAMLSyntax.html#yaml-basics) . [Inventory basics: formats, hosts, and groups](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#id4) [](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#inventory-basics-formats-hosts-and-groups "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can create your inventory file in one of many formats, depending on the inventory plugins you have. The most common formats are INI and YAML because Ansible includes built-in support for them. This introduction focuses on these two formats, but many other formats and sources are possible. A basic INI `/etc/ansible/hosts` might look like this: mail.example.com \[webservers\] foo.example.com bar.example.com \[dbservers\] one.example.com two.example.com three.example.com The headings in brackets are group names. You can use group names to classify hosts and to decide which hosts you are controlling at what times and for what purpose. Group names should follow the same guidelines as [Creating valid variable names](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_variables.html#valid-variable-names) . Here’s the same basic inventory file in YAML format: ungrouped: hosts: mail.example.com: webservers: hosts: foo.example.com: bar.example.com: dbservers: hosts: one.example.com: two.example.com: three.example.com: ### [Default groups](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#id5) [](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#default-groups "Link to this heading") Even if you do not define any groups in your inventory, Ansible creates two default groups: `all` and `ungrouped`. The `all` group contains every host. The `ungrouped` group contains all hosts that do not belong to any other group. Every host always belongs to at least two groups (`all` and `ungrouped`, or `all` and another group). For example, in the basic inventory above, the host `mail.example.com` belongs to the `all` and `ungrouped` groups. The host `two.example.com` belongs to the `all` and `dbservers` groups. Although `all` and `ungrouped` are always present, they can be implicit and might not appear in group listings like `group_names`. ### [Hosts in multiple groups](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#id6) [](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#hosts-in-multiple-groups "Link to this heading") You can put a host in more than one group. For example, you can include a production web server in a data center in Atlanta in the `[prod]`, `[atlanta]`, and `[webservers]` groups. You can create groups that track the following criteria: * **What** - An application, stack, or microservice (for example, database servers, web servers, and so on). * **Where** - A datacenter or region, to talk to local DNS, storage, and so on (for example, east, west). * **When** - The development stage, to avoid testing on production resources (for example, prod, test). The following example extends the previous YAML inventory to include what, when, and where: ungrouped: hosts: mail.example.com: webservers: hosts: foo.example.com: bar.example.com: dbservers: hosts: one.example.com: two.example.com: three.example.com: east: hosts: foo.example.com: one.example.com: two.example.com: west: hosts: bar.example.com: three.example.com: prod: hosts: foo.example.com: one.example.com: two.example.com: test: hosts: bar.example.com: three.example.com: As the example shows, `one.example.com` exists in the `dbservers`, `east`, and `prod` groups. ### [Grouping groups: parent/child group relationships](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#id7) [](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#grouping-groups-parent-child-group-relationships "Link to this heading") You can create parent/child relationships among groups. Parent groups are also known as nested groups or groups of groups. For example, if all your production hosts are already in groups such as  `atlanta_prod` and `denver_prod`, you can create a `production` group that includes those smaller groups. This approach reduces maintenance because you add or remove hosts from the parent group by editing the child groups. To create parent/child relationships for groups, use one of the following methods: * In INI format, use the `:children` suffix. * In YAML format, use the `children:` entry. The following example shows the same inventory as above, simplified with parent groups for the `prod` and `test` groups: ungrouped: hosts: mail.example.com: webservers: hosts: foo.example.com: bar.example.com: dbservers: hosts: one.example.com: two.example.com: three.example.com: east: hosts: foo.example.com: one.example.com: two.example.com: west: hosts: bar.example.com: three.example.com: prod: children: east: test: children: west: Note the following properties of child groups: * Any host that is a member of a child group is automatically a member of the parent group. * A group can have multiple parents and children, but not circular relationships. * A host can be in multiple groups, but Ansible processes only **one** instance of the host at runtime. Ansible merges the data from multiple groups. * Hosts and groups are always ‘global’. If you define a host or group more than once under different ‘branches’ or ‘instances’, the host or group remains the same entity. Defining a host or group more than once either adds new information to it or overwrites any conflicting information with the latest definition. ### [Adding ranges of hosts](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#id8) [](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#adding-ranges-of-hosts "Link to this heading") Some plugins, like YAML and INI, support adding ranges of hosts. If you have many hosts with a similar pattern, you can add the hosts as a range rather than listing each hostname separately: In INI: \[webservers\] www\[01:50\].example.com In YAML: \# ... webservers: hosts: www\[01:50\].example.com: You can specify a stride (increments between sequence numbers) when you define a numeric range of hosts: In INI: \[webservers\] www\[01:50:2\].example.com In YAML: \# ... webservers: hosts: www\[01:50:2\].example.com: The example above matches the subdomains www01, www03, www05, …, www49, but not www00, www02, www50, and so on, because the stride (increment) is 2 units for each step. For numeric patterns, you can include or remove leading zeros as desired. Ranges are inclusive. You can also define alphabetic ranges: \[databases\] db-\[a:f\].example.com [Passing multiple inventory sources](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#id9) [](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#passing-multiple-inventory-sources "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can target multiple inventory sources (static files, directories, dynamic inventory scripts or anything supported by inventory plugins) at the same time. To do this, specify multiple inventory sources from the command line (see below) or by configuration, either by setting [`ANSIBLE_INVENTORY`](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/config.html#envvar-ANSIBLE_INVENTORY) or in `ansible.cfg` ([DEFAULT\_HOST\_LIST](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/config.html#default-host-list) ). This capability can be useful when you want to target normally separate environments, like staging and production, at the same time for a specific action. To target two inventory sources from the command line: ansible-playbook get\_logs.yml \-i staging \-i production [Organizing inventory in a directory](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#id10) [](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#organizing-inventory-in-a-directory "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ You can consolidate multiple inventory sources in a single directory. The simplest version of this approach is a directory with multiple files instead of a single inventory file. Maintaining a single file becomes difficult when the file gets too long. If you have multiple teams and multiple automation projects, creating one inventory file per team or project lets everyone easily find the hosts and groups that matter to them. You can also still use the files individually or in subsets, depending on how you configure or call Ansible. These files can use all formats or plugin configurations (for example, YAML or INI). In this case, your directory becomes your ‘single’ inventory source, and Ansible aggregates the multiple sources it finds in that directory. By default, Ansible ignores some directories and extensions, but you can change this behavior in the configuration ([INVENTORY\_IGNORE\_PATTERNS](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/config.html#inventory-ignore-patterns) and [INVENTORY\_IGNORE\_EXTS](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/config.html#inventory-ignore-exts) ). You can also combine multiple inventory source types in an inventory directory. This method can be useful for combining static and dynamic hosts and managing them as one inventory. The following inventory directory combines an inventory plugin source, a dynamic inventory script, and a file with static hosts: inventory/ openstack.yml # configure inventory plugin to get hosts from OpenStack cloud dynamic-inventory.py # add additional hosts with dynamic inventory script on-prem # add static hosts and groups parent-groups # add static hosts and groups You can target this inventory directory as follows: ansible-playbook example.yml \-i inventory You can also configure the inventory directory in your `ansible.cfg` file. See [Configuring Ansible](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_configuration.html#intro-configuration) for more details. Ansible reads and loads files from the top directory down in alphabetically sorted order. ### [Managing inventory load order](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#id11) [](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#managing-inventory-load-order "Link to this heading") Ansible loads inventory sources in the order you supply them. It defines hosts, groups, and variables as it encounters them in the source files, adding the `all` and `ungrouped` groups at the end if needed. Depending on the inventory plugin or plugins you use, you might need to rearrange the order of sources to ensure that parent/child-defined groups or hosts exist as the plugins expect. Otherwise, you might encounter a parsing error. For example, the YAML and INI inventory plugins discard empty groups (groups with no associated hosts) when they finish processing each source. If you define a variable multiple times, Ansible overwrites the previous value. The last definition wins. [Adding variables to inventory](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#id12) [](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#adding-variables-to-inventory "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ You can define variables that relate to a specific host or group in your inventory. A simple way to start is by adding variables directly to the hosts and groups in a YAML or INI inventory source. This guide documents how to add variables in the inventory source for simplicity. However, you can also use [Vars plugins](https://docs.ansible.com/projects/ansible-core/devel/plugins/vars.html#vars-plugins) to add variables from many other sources. By default, Ansible ships with the [host\_group\_vars](https://docs.ansible.com/projects/ansible-core/devel/collections/ansible/builtin/host_group_vars_vars.html#host-group-vars-vars) plugin, which allows you to define variables in separate host and group variable files. Using separate files is a more robust approach to describing your system policy than defining variables in the inventory source. See [Organizing host and group variables](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#splitting-out-vars) for guidelines on how to store variable values in individual files in the ‘host\_vars’ and ‘group\_vars’ directories. [Assigning a variable to one machine: host variables](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#id13) [](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#assigning-a-variable-to-one-machine-host-variables "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can easily assign a variable to a single host and then use that variable later in playbooks. You can do this directly in your inventory file. In INI: \[atlanta\] host1 http\_port=80 maxRequestsPerChild=808 host2 http\_port=303 maxRequestsPerChild=909 In YAML: atlanta: hosts: host1: http\_port: 80 maxRequestsPerChild: 808 host2: http\_port: 303 maxRequestsPerChild: 909 Unique values like non-standard SSH ports work well as host variables. You can add them to your Ansible inventory by adding the port number after the hostname with a colon: badwolf.example.com:5309 You can use host variables to define ‘Connection variables’. Connection variables configure `connection`, `shell`, and `become` plugins to enable task execution on the host. For example: \[targets\] localhost ansible\_connection=local other1.example.com ansible\_connection=ssh ansible\_user=myuser other2.example.com ansible\_connection=ssh ansible\_user=myotheruser ### [Inventory aliases](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#id14) [](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#inventory-aliases "Link to this heading") The `inventory_hostname` is the unique identifier for a host in Ansible. This identifier can be an IP address or a hostname, but it can also be just an ‘alias’ or short name for the host. In INI: jumper ansible\_port=5555 ansible\_host=192.0.2.50 In YAML: \# ... hosts: jumper: ansible\_port: 5555 ansible\_host: 192.0.2.50 In this example, running Ansible against the host alias “jumper” connects to 192.0.2.50 on port 5555. See [behavioral inventory parameters](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#behavioral-parameters) to further customize the connection to hosts. This feature is also useful for targeting the same host more than once, but remember that tasks can run in parallel: In INI: jumper1 ansible\_port=5555 ansible\_host=192.0.2.50 jumper2 ansible\_port=5555 ansible\_host=192.0.2.50 In YAML: \# ... hosts: jumper1: ansible\_port: 5555 ansible\_host: 192.0.2.50 jumper2: ansible\_port: 5555 ansible\_host: 192.0.2.50 [Defining variables in INI format](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#id15) [](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#defining-variables-in-ini-format "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ Ansible interprets values that you pass in the INI format by using the `key=value` syntax differently depending on where you declare them: * When you declare a value inline with the host, Ansible interprets the INI value as a Python literal structure (for example, a string, number, tuple, list, dict, boolean, or None). Host lines accept multiple `key=value` parameters per line. Therefore, you need a way to indicate that a space is part of a value rather than a separator. You can quote values that contain whitespace (using single or double quotes). See the [Python shlex parsing rules](https://docs.python.org/3/library/shlex.html#parsing-rules) for details. * When you declare a value in a `:vars` section, Ansible interprets the INI value as a string. For example, `var=FALSE` creates a string with the value ‘FALSE’. Unlike host lines, `:vars` sections accept only a single entry per line, so everything after the `=` becomes the value for the entry. If you need a variable from an INI inventory to have a certain type (for example, a string or a boolean), always specify the type with a filter in your task. Do not rely on types that you set in INI inventories when you consume variables. Consider using the YAML format for inventory sources to avoid confusion about the actual type of a variable. The YAML inventory plugin processes variable values consistently and correctly. [Assigning a variable to many machines: group variables](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#id16) [](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#assigning-a-variable-to-many-machines-group-variables "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- If all hosts in a group share a variable value, you can apply that variable to an entire group at once. In INI: \[atlanta\] host1 host2 \[atlanta:vars\] ntp\_server=ntp.atlanta.example.com proxy=proxy.atlanta.example.com In YAML: atlanta: hosts: host1: host2: vars: ntp\_server: ntp.atlanta.example.com proxy: proxy.atlanta.example.com Group variables are a convenient way to apply variables to multiple hosts at once. Before executing, however, Ansible always flattens variables, including inventory variables, to the host level. If a host is a member of multiple groups, Ansible reads variable values from all of those groups. If you assign different values to the same variable in different groups, Ansible chooses which value to use based on internal [rules for merging](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#how-we-merge) . ### [Inheriting variable values: group variables for groups of groups](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#id17) [](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#inheriting-variable-values-group-variables-for-groups-of-groups "Link to this heading") You can apply variables to parent groups (nested groups or groups of groups) as well as to child groups. The syntax is the same: `:vars` for INI format and `vars:` for YAML format: In INI: \[atlanta\] host1 host2 \[raleigh\] host2 host3 \[southeast:children\] atlanta raleigh \[southeast:vars\] some\_server=foo.southeast.example.com halon\_system\_timeout=30 self\_destruct\_countdown=60 escape\_pods=2 \[usa:children\] southeast northeast southwest northwest In YAML: usa: children: southeast: children: atlanta: hosts: host1: host2: raleigh: hosts: host2: host3: vars: some\_server: foo.southeast.example.com halon\_system\_timeout: 30 self\_destruct\_countdown: 60 escape\_pods: 2 northeast: northwest: southwest: A child group’s variables have higher precedence (they override) than a parent group’s variables. [Organizing host and group variables](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#id18) [](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#organizing-host-and-group-variables "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ Although you can define variables in the inventory source, you can also use [Vars plugins](https://docs.ansible.com/projects/ansible-core/devel/plugins/vars.html#vars-plugins) to define alternate sources for your variables. The default vars plugin that Ansible ships with, [host\_group\_vars](https://docs.ansible.com/projects/ansible-core/devel/collections/ansible/builtin/host_group_vars_vars.html#host-group-vars-vars) , lets you use separate host and group variable files. This method helps you organize your variable values more easily. You can also use lists and hash data in these files, which you cannot do in your main inventory file. For the `host_group_vars` plugin, your host and group variable files must use YAML syntax. Valid file extensions are ‘.yml’, ‘.yaml’, ‘.json’, or no file extension. See [YAML Syntax](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/YAMLSyntax.html#yaml-syntax) if you are new to YAML. The `host_group_vars` plugin loads host and group variable files by searching paths relative to the inventory source or the playbook file. If your inventory file at `/etc/ansible/hosts` contains a host named ‘foosball’ that belongs to the `raleigh` and `webservers` groups, that host will use variables from the YAML files in the following locations: /etc/ansible/group\_vars/raleigh \# can optionally end in '.yml', '.yaml', or '.json' /etc/ansible/group\_vars/webservers /etc/ansible/host\_vars/foosball For example, if you group hosts in your inventory by datacenter, and each datacenter uses its own NTP server and database server, you can create a file named `/etc/ansible/group_vars/raleigh` to store the variables for the `raleigh` group: \--- ntp\_server: acme.example.org database\_server: storage.example.org You can also create _directories_ named after your groups or hosts. Ansible reads all the files in these directories in lexicographical order. Here is an example with the ‘raleigh’ group: /etc/ansible/group\_vars/raleigh/db\_settings /etc/ansible/group\_vars/raleigh/cluster\_settings All hosts in the ‘raleigh’ group have the variables that you define in these files available to them. This method is very useful for keeping your variables organized when a single file gets too big, or when you want to use [Ansible Vault](https://docs.ansible.com/projects/ansible-core/devel/vault_guide/vault_using_encrypted_content.html#playbooks-vault) on some group variables. Ansible’s [host\_group\_vars](https://docs.ansible.com/projects/ansible-core/devel/collections/ansible/builtin/host_group_vars_vars.html#host-group-vars-vars) vars plugin can also add `group_vars/` and `host_vars/` directories to your playbook directory when you use `ansible-playbook`. However, not all Ansible commands have a playbook (for example, `ansible` or `ansible-console`). For those commands, you can use the `--playbook-dir` option to provide the directory on the command line. If you have sources for the vars plugins relative to both the playbook directory and the inventory directory, the variables that Ansible sources relative to the playbook override the variables that it sources relative to the inventory source. To track changes to your inventory and variable definitions, keep your inventory sources and their relative variable directories and files in a Git repository or other version control system. [How variables are merged](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#id19) [](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#how-variables-are-merged "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Note Ansible merges variables from different sources and applies precedence to some variables over others according to a set of rules. For example, variables that occur higher in an inventory can override variables that occur lower in the inventory. See [Variable precedence: where should I put a variable?](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_variables.html#ansible-variable-precedence) for more information. Before it runs a play, Ansible merges and flattens variables to the specific host. This process keeps Ansible focused on the Host and Task, so groups do not survive outside of inventory and host matching. By default, Ansible overwrites variables, including the ones that you define for a group or host (see [DEFAULT\_HASH\_BEHAVIOUR](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/config.html#default-hash-behaviour) ). The order/precedence for inventory entities is (from lowest to highest): The following list shows the order of precedence for inventory entities, from lowest to highest: * `all` group (because it is the ‘parent’ of all other groups) * parent group * child group * host By default, Ansible merges groups at the same parent/child level in alphabetical order. Variables from the last group that Ansible loads overwrite variables from the previous groups. For example, Ansible merges an `a_group` with a `b_group`, and matching variables from `b_group` overwrite the variables in `a_group`. You can fine-tune this merge behavior by setting the group variable `ansible_group_priority`. This variable overrides the alphabetical sorting for the merge order for groups of the same level (after Ansible resolves the parent/child order). The larger the number, the later Ansible merges the group, giving it higher priority. This variable defaults to `1` if you do not set it. For example: a\_group: vars: testvar: a ansible\_group\_priority: 10 b\_group: vars: testvar: b In this example, if both groups have the same priority, the result would normally be `testvar == b`. However, because we give `a_group` a higher priority, the result is `testvar == a`. You can set `ansible_group_priority` only in an inventory source, not in `group_vars/`. Ansible uses this variable when it loads the `group_vars/` directory. ### [Managing inventory variable load order](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#id20) [](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#managing-inventory-variable-load-order "Link to this heading") This section describes how to control variable precedence by managing the load order of inventory sources. You can pass sources in a specific order at the command line or use prefixes in the filenames of sources within a directory. When you use multiple inventory sources, remember that Ansible resolves any variable conflicts according to the rules described in [How variables are merged](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#how-we-merge) and [Variable precedence: where should I put a variable?](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_variables.html#ansible-variable-precedence) . You can control the merging order of variables in inventory sources to get the variable value you need. When you pass multiple inventory sources at the command line, Ansible merges variables in the order you pass those parameters. If the `[all:vars]` section in the staging inventory defines `myvar = 1` and the production inventory defines `myvar = 2`, then the following outcomes are true: * If you pass `-i staging -i production`, Ansible runs the playbook with `myvar = 2`. * If you pass `-i production -i staging`, Ansible runs the playbook with `myvar = 1`. When you put multiple inventory sources in a directory, Ansible merges the sources in alphabetical order according to their filenames. You can control the load order by adding prefixes to the files: inventory/ 01-openstack.yml # configure inventory plugin to get hosts from Openstack cloud 02-dynamic-inventory.py # add additional hosts with dynamic inventory script 03-static-inventory # add static hosts group\_vars/ all.yml # assign variables to all hosts If `01-openstack.yml` defines `myvar = 1` for the group `all`, `02-dynamic-inventory.py` defines `myvar = 2`, and `03-static-inventory` defines `myvar = 3`, Ansible runs the playbook with `myvar = 3`. For more details on inventory plugins and dynamic inventory scripts see [Inventory plugins](https://docs.ansible.com/projects/ansible-core/devel/plugins/inventory.html#inventory-plugins) and [Working with dynamic inventory](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_dynamic_inventory.html#intro-dynamic-inventory) . [Connecting to hosts: behavioral inventory parameters](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#id21) [](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#connecting-to-hosts-behavioral-inventory-parameters "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- As described above, you can set the following variables to control how Ansible interacts with remote hosts. Host connection: Note Ansible does not expose a channel to allow communication between the user and the ssh process to accept a password manually to decrypt an ssh key when using the ssh connection plugin (which is the default). The use of `ssh-agent` is highly recommended. ansible\_connection Specifies the connection type to the host. This can be the name of any Ansible connection plugin. SSH protocol types are `ssh` or `paramiko`. The default is `ssh`. General for all connections: ansible\_host Specifies the resolvable name or IP of the host to connect to, if it is different from the alias you wish to give to it. Never set it to depend on `inventory_hostname`. If you really need something like that, use `inventory_hostname_short` so it can work with delegation. ansible\_port The connection port number, if not the default (22 for ssh). ansible\_user The username to use when connecting (logging in) to the host. ansible\_password The password to use to authenticate to the host. (Never store this variable in plain text. Always use a vault. See [Keep vaulted variables safely visible](https://docs.ansible.com/projects/ansible-core/devel/tips_tricks/ansible_tips_tricks.html#tip-for-variables-and-vaults) .) Specific to the SSH connection plugin: ansible\_ssh\_private\_key\_file Private key file used by SSH. This is useful if you use multiple keys and you do not want to use SSH agent. ansible\_ssh\_common\_args Ansible always appends this setting to the default command line for **sftp**, **scp**, and **ssh**. This is useful for configuring a `ProxyCommand` for a certain host or group. ansible\_sftp\_extra\_args Ansible always appends this setting to the default **sftp** command line. ansible\_scp\_extra\_args Ansible always appends this setting to the default **scp** command line. ansible\_ssh\_extra\_args Ansible always appends this setting to the default **ssh** command line. ansible\_ssh\_pipelining Specifies whether to use SSH pipelining. This can override the `pipelining` setting in `ansible.cfg`. ansible\_ssh\_executable (added in version 2.2) This setting overrides the default behavior to use the system **ssh**. It can override the `ssh_executable` setting in the `ssh_connection` section of `ansible.cfg`. Privilege escalation (see [Ansible Privilege Escalation](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_privilege_escalation.html#become) for further details): ansible\_become Equivalent to `ansible_sudo` or `ansible_su`; allows you to force privilege escalation. ansible\_become\_method Allows you to set the privilege escalation method to a matching become plugin. ansible\_become\_user Equivalent to `ansible_sudo_user` or `ansible_su_user`; allows you to set the user you become through privilege escalation. ansible\_become\_password Equivalent to `ansible_sudo_password` or `ansible_su_password`; allows you to set the privilege escalation password. (Never store this variable in plain text. Always use a vault. See [Keep vaulted variables safely visible](https://docs.ansible.com/projects/ansible-core/devel/tips_tricks/ansible_tips_tricks.html#tip-for-variables-and-vaults) .) ansible\_become\_exe Equivalent to `ansible_sudo_exe` or `ansible_su_exe`; allows you to set the executable for the escalation method you selected. ansible\_become\_flags Equivalent to `ansible_sudo_flags` or `ansible_su_flags`; allows you to set the flags passed to the selected escalation method. You can also set this globally in `ansible.cfg` in the `become_flags` option under `privilege_escalation`. Remote host environment parameters: ansible\_shell\_type Specifies the shell type of the target system. You should not use this setting unless you have set the [ansible\_shell\_executable](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#ansible-shell-executable) to a non-Bourne (sh) compatible shell.  By default, Ansible formats commands using `sh`\-style syntax.  If you set this to `csh` or `fish`, commands that Ansible executes on target systems follow those shell’s syntax instead. ansible\_python\_interpreter Specifies the target host Python path. This is useful for systems with more than one Python or for systems where Python is not located at **/usr/bin/python**, such as \*BSD, or where **/usr/bin/python** is not a 2.X series Python.  We do not use the **/usr/bin/env** mechanism because that requires the remote user’s path to be set correctly and also assumes the **python** executable is named python, where the executable might be named something like **python2.6**. ansible\_\*\_interpreter Works for any language, such as Ruby or Perl, and works just like [ansible\_python\_interpreter](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#ansible-python-interpreter) . This variable replaces the shebang of modules that will run on that host. New in version 2.1. ansible\_shell\_executable This setting sets the shell the Ansible control node will use on the target machine. It overrides `executable` in `ansible.cfg`, which defaults to **/bin/sh**.  You should only change this value if it is not possible to use **/bin/sh** (in other words, if **/bin/sh** is not installed on the target machine or cannot be run from sudo.). Examples from an Ansible-INI host file: some\_host ansible\_port=2222 ansible\_user=manager aws\_host ansible\_ssh\_private\_key\_file=/home/example/.ssh/aws.pem freebsd\_host ansible\_python\_interpreter=/usr/local/bin/python ruby\_module\_host ansible\_ruby\_interpreter=/usr/bin/ruby.1.9.3 ### [Non-SSH connection types](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#id22) [](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#non-ssh-connection-types "Link to this heading") As stated in the previous section, Ansible executes playbooks over SSH by default, but it is not limited to this connection type. You can change the connection type with the host-specific parameter `ansible_connection=`. For a full list of available plugins and examples, see [Plugin list](https://docs.ansible.com/projects/ansible-core/devel/plugins/connection.html#connection-plugin-list) . [Inventory setup examples](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#id23) [](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#inventory-setup-examples "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- See also [Sample Ansible setup](https://docs.ansible.com/projects/ansible-core/devel/tips_tricks/sample_setup.html#sample-setup) , which shows inventory along with playbooks and other Ansible artifacts. ### [Example: One inventory per environment](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#id24) [](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#example-one-inventory-per-environment "Link to this heading") If you need to manage multiple environments, consider defining only the hosts of a single environment in each inventory. This way, it is harder to, for example, accidentally change the state of nodes inside the “test” environment when you wanted to update some “staging” servers. For the example mentioned above, you could have an `inventory_test` file: \[dbservers\] db01.test.example.com db02.test.example.com \[appservers\] app01.test.example.com app02.test.example.com app03.test.example.com That file only includes hosts that are part of the “test” environment. You can define the “staging” machines in another file called `inventory_staging`: \[dbservers\] db01.staging.example.com db02.staging.example.com \[appservers\] app01.staging.example.com app02.staging.example.com app03.staging.example.com To apply a playbook called `site.yml` to all the app servers in the test environment, use the following command: ansible-playbook \-i inventory\_test \-l appservers site.yml ### [Example: Group by function](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#id25) [](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#example-group-by-function "Link to this heading") In the previous section, you already saw an example of using groups to cluster hosts that have the same function. This approach allows you, for example, to define firewall rules inside a playbook or role that affect only database servers: \- hosts: dbservers tasks: \- name: Allow access from 10.0.0.1 ansible.builtin.iptables: chain: INPUT jump: ACCEPT source: 10.0.0.1 ### [Example: Group by location](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#id26) [](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#example-group-by-location "Link to this heading") Other tasks might focus on where a certain host is located. Let’s say that `db01.test.example.com` and `app01.test.example.com` are located in DC1, while `db02.test.example.com` is in DC2: \[dc1\] db01.test.example.com app01.test.example.com \[dc2\] db02.test.example.com In practice, you might end up mixing all these setups. For example, you might need to update all nodes in a specific data center on one day, while on another day, you might need to update all the application servers no matter their location. See also [Inventory plugins](https://docs.ansible.com/projects/ansible-core/devel/plugins/inventory.html#inventory-plugins) Pulling inventory from dynamic or static sources [Working with dynamic inventory](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_dynamic_inventory.html#intro-dynamic-inventory) Pulling inventory from dynamic sources, such as cloud providers [Introduction to ad hoc commands](https://docs.ansible.com/projects/ansible-core/devel/command_guide/intro_adhoc.html#intro-adhoc) Examples of basic commands [Working with playbooks](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks.html#working-with-playbooks) Learning Ansible’s configuration, deployment, and orchestration language. [Communication](https://docs.ansible.com/projects/ansible-core/devel/community/communication.html#communication) Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide --- # Ansible Collections Contributor Guide — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * Ansible Collections Contributor Guide * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/community/contributions_collections.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Ansible Collections Contributor Guide[](https://docs.ansible.com/projects/ansible/latest/community/contributions_collections.html#ansible-collections-contributor-guide "Link to this heading") ================================================================================================================================================================================================= * [The Ansible Collections Development Cycle](https://docs.ansible.com/projects/ansible/latest/community/collection_development_process.html) * [Macro development: roadmaps, releases, and projects](https://docs.ansible.com/projects/ansible/latest/community/collection_development_process.html#macro-development-roadmaps-releases-and-projects) * [Micro development: the lifecycle of a PR](https://docs.ansible.com/projects/ansible/latest/community/collection_development_process.html#micro-development-the-lifecycle-of-a-pr) * [Making your PR merge-worthy](https://docs.ansible.com/projects/ansible/latest/community/collection_development_process.html#making-your-pr-merge-worthy) * [Requesting changes to a collection](https://docs.ansible.com/projects/ansible/latest/community/reporting_collections.html) * [Reporting a bug](https://docs.ansible.com/projects/ansible/latest/community/reporting_collections.html#reporting-a-bug) * [Requesting a feature](https://docs.ansible.com/projects/ansible/latest/community/reporting_collections.html#requesting-a-feature) * [Creating your first collection pull request](https://docs.ansible.com/projects/ansible/latest/community/create_pr_quick_start.html) * [Prepare your environment](https://docs.ansible.com/projects/ansible/latest/community/create_pr_quick_start.html#prepare-your-environment) * [Change the code](https://docs.ansible.com/projects/ansible/latest/community/create_pr_quick_start.html#change-the-code) * [Fix the bug](https://docs.ansible.com/projects/ansible/latest/community/create_pr_quick_start.html#fix-the-bug) * [Test your changes](https://docs.ansible.com/projects/ansible/latest/community/create_pr_quick_start.html#test-your-changes) * [Submit a pull request](https://docs.ansible.com/projects/ansible/latest/community/create_pr_quick_start.html#submit-a-pull-request) * [Testing Collection Contributions](https://docs.ansible.com/projects/ansible/latest/community/collection_contributors/test_index.html) * [How to test a collection PR](https://docs.ansible.com/projects/ansible/latest/community/collection_contributors/collection_test_pr_locally.html) * [Add unit tests to a collection](https://docs.ansible.com/projects/ansible/latest/community/collection_contributors/collection_unit_tests.html) * [Adding integration tests to a collection](https://docs.ansible.com/projects/ansible/latest/community/collection_contributors/collection_integration_tests.html) * [Review checklist for collection PRs](https://docs.ansible.com/projects/ansible/latest/community/collection_contributors/collection_reviewing.html) * [Reviewing bug reports](https://docs.ansible.com/projects/ansible/latest/community/collection_contributors/collection_reviewing.html#reviewing-bug-reports) * [Reviewing suggested changes](https://docs.ansible.com/projects/ansible/latest/community/collection_contributors/collection_reviewing.html#reviewing-suggested-changes) * [Review tests in the PR](https://docs.ansible.com/projects/ansible/latest/community/collection_contributors/collection_reviewing.html#review-tests-in-the-pr) * [Review for merge commits and breaking changes](https://docs.ansible.com/projects/ansible/latest/community/collection_contributors/collection_reviewing.html#review-for-merge-commits-and-breaking-changes) * [Ansible community package collections requirements](https://docs.ansible.com/projects/ansible/latest/community/collection_contributors/collection_requirements.html) * [Overview](https://docs.ansible.com/projects/ansible/latest/community/collection_contributors/collection_requirements.html#overview) * [Feedback and communications](https://docs.ansible.com/projects/ansible/latest/community/collection_contributors/collection_requirements.html#feedback-and-communications) * [Keeping informed](https://docs.ansible.com/projects/ansible/latest/community/collection_contributors/collection_requirements.html#keeping-informed) * [Communication and Working Groups](https://docs.ansible.com/projects/ansible/latest/community/collection_contributors/collection_requirements.html#communication-and-working-groups) * [Collection infrastructure](https://docs.ansible.com/projects/ansible/latest/community/collection_contributors/collection_requirements.html#collection-infrastructure) * [Python Compatibility](https://docs.ansible.com/projects/ansible/latest/community/collection_contributors/collection_requirements.html#python-compatibility) * [Standards for developing module and plugin utilities](https://docs.ansible.com/projects/ansible/latest/community/collection_contributors/collection_requirements.html#standards-for-developing-module-and-plugin-utilities) * [Repository structure requirements](https://docs.ansible.com/projects/ansible/latest/community/collection_contributors/collection_requirements.html#repository-structure-requirements) * [Contributor Workflow](https://docs.ansible.com/projects/ansible/latest/community/collection_contributors/collection_requirements.html#contributor-workflow) * [Naming](https://docs.ansible.com/projects/ansible/latest/community/collection_contributors/collection_requirements.html#naming) * [Collection licensing requirements](https://docs.ansible.com/projects/ansible/latest/community/collection_contributors/collection_requirements.html#collection-licensing-requirements) * [Contributor License Agreements](https://docs.ansible.com/projects/ansible/latest/community/collection_contributors/collection_requirements.html#contributor-license-agreements) * [Repository management](https://docs.ansible.com/projects/ansible/latest/community/collection_contributors/collection_requirements.html#repository-management) * [CI Testing](https://docs.ansible.com/projects/ansible/latest/community/collection_contributors/collection_requirements.html#ci-testing) * [When moving modules between collections](https://docs.ansible.com/projects/ansible/latest/community/collection_contributors/collection_requirements.html#when-moving-modules-between-collections) * [Development conventions](https://docs.ansible.com/projects/ansible/latest/community/collection_contributors/collection_requirements.html#development-conventions) * [Collection Dependencies](https://docs.ansible.com/projects/ansible/latest/community/collection_contributors/collection_requirements.html#collection-dependencies) * [Other requirements](https://docs.ansible.com/projects/ansible/latest/community/collection_contributors/collection_requirements.html#other-requirements) * [Guidelines for collection maintainers](https://docs.ansible.com/projects/ansible/latest/community/maintainers.html) * [Maintainer responsibilities](https://docs.ansible.com/projects/ansible/latest/community/maintainers_guidelines.html) * [Expanding the collection community](https://docs.ansible.com/projects/ansible/latest/community/maintainers_guidelines.html#expanding-the-collection-community) * [Maintaining good collection documentation](https://docs.ansible.com/projects/ansible/latest/community/maintainers_guidelines.html#maintaining-good-collection-documentation) * [Ansible Collection Maintenance and Workflow](https://docs.ansible.com/projects/ansible/latest/community/maintainers_workflow.html) * [Stepping down as a collection maintainer](https://docs.ansible.com/projects/ansible/latest/community/maintainers_workflow.html#stepping-down-as-a-collection-maintainer) * [Releasing collections](https://docs.ansible.com/projects/ansible/latest/community/collection_contributors/collection_releasing.html) * [Contributing to Ansible-maintained Collections](https://docs.ansible.com/projects/ansible/latest/community/contributing_maintained_collections.html) * [Ansible-maintained collections](https://docs.ansible.com/projects/ansible/latest/community/contributing_maintained_collections.html#ansible-maintained-collections) * [Deciding where your contribution belongs](https://docs.ansible.com/projects/ansible/latest/community/contributing_maintained_collections.html#deciding-where-your-contribution-belongs) * [Requirements to merge your PR](https://docs.ansible.com/projects/ansible/latest/community/contributing_maintained_collections.html#requirements-to-merge-your-pr) * [Ansible Community Steering Committee](https://docs.ansible.com/projects/ansible/latest/community/steering/steering_index.html) * [Steering Committee mission and responsibilities](https://docs.ansible.com/projects/ansible/latest/community/steering/community_steering_committee.html) * [Steering Committee membership guidelines](https://docs.ansible.com/projects/ansible/latest/community/steering/steering_committee_membership.html) * [Steering Committee past members](https://docs.ansible.com/projects/ansible/latest/community/steering/steering_committee_past_members.html) * [Community topics workflow](https://docs.ansible.com/projects/ansible/latest/community/steering/community_topics_workflow.html) * [Contributing to the Ansible Documentation](https://docs.ansible.com/projects/ansible/latest/community/documentation_contributions.html) * [Editing docs directly on GitHub](https://docs.ansible.com/projects/ansible/latest/community/documentation_contributions.html#editing-docs-directly-on-github) * [Reviewing or solving open issues](https://docs.ansible.com/projects/ansible/latest/community/documentation_contributions.html#reviewing-or-solving-open-issues) * [Reviewing open PRs](https://docs.ansible.com/projects/ansible/latest/community/documentation_contributions.html#reviewing-open-prs) * [Opening a new issue and/or PR](https://docs.ansible.com/projects/ansible/latest/community/documentation_contributions.html#opening-a-new-issue-and-or-pr) * [Verifying your documentation PR](https://docs.ansible.com/projects/ansible/latest/community/documentation_contributions.html#verifying-your-documentation-pr) * [Joining the documentation working group](https://docs.ansible.com/projects/ansible/latest/community/documentation_contributions.html#joining-the-documentation-working-group) * [Other Tools and Programs](https://docs.ansible.com/projects/ansible/latest/community/other_tools_and_programs.html) * [Popular editors](https://docs.ansible.com/projects/ansible/latest/community/other_tools_and_programs.html#popular-editors) * [Tools for validating playbooks](https://docs.ansible.com/projects/ansible/latest/community/other_tools_and_programs.html#tools-for-validating-playbooks) * [Collection development tools](https://docs.ansible.com/projects/ansible/latest/community/other_tools_and_programs.html#collection-development-tools) * [Other tools](https://docs.ansible.com/projects/ansible/latest/community/other_tools_and_programs.html#other-tools) If you have a specific Ansible interest or expertise (for example, VMware, Linode, and so on), consider joining a [working group](https://docs.ansible.com/projects/ansible/latest/community/communication.html#working-group-list) . Working with the Ansible collection repositories[](https://docs.ansible.com/projects/ansible/latest/community/contributions_collections.html#working-with-the-ansible-collection-repositories "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * How can I find [editors, linters, and other tools](https://docs.ansible.com/projects/ansible/latest/community/other_tools_and_programs.html#other-tools-and-programs) that will support my Ansible development efforts? * Where can I find guidance on [coding in Ansible](https://docs.ansible.com/projects/ansible/latest/dev_guide/index.html#developer-guide) ? * How do I [create a collection](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_in_groups.html#developing-modules-in-groups) ? * How do I [rebase my PR](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_rebasing.html#rebase-guide) ? * How do I learn about Ansible’s [testing (CI) process](https://docs.ansible.com/projects/ansible/latest/dev_guide/testing.html#developing-testing) ? * How do I [deprecate a module](https://docs.ansible.com/projects/ansible/latest/dev_guide/module_lifecycle.html#deprecating-modules) ? * See [Collection developer tutorials](https://www.ansible.com/products/ansible-community-training) for a quick introduction on how to develop and test your collection contributions. --- # Introduction to modules — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * [Using Ansible modules and plugins](https://docs.ansible.com/projects/ansible/latest/module_plugin_guide/index.html) * Introduction to modules * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/module_plugin_guide/modules_intro.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Introduction to modules[](https://docs.ansible.com/projects/ansible/latest/module_plugin_guide/modules_intro.html#introduction-to-modules "Link to this heading") =================================================================================================================================================================== Modules (also referred to as “task plugins” or “library plugins”) are discrete units of code that can be used from the command line or in a playbook task. Ansible executes each module, usually on the remote managed node, and collects return values. In Ansible 2.10 and later, most modules are hosted in collections. You can execute modules from the command line. ansible webservers -m service -a "name=httpd state=started" ansible webservers -m ping ansible webservers -m command -a "/sbin/reboot -t now" Each module supports arguments. Nearly all modules take `key=value` arguments, space delimited. Some modules take no arguments, and the command/shell modules simply take the string of the command you want to run. From playbooks, Ansible modules are executed in a very similar way. \- name: reboot the servers command: /sbin/reboot -t now Another way to pass arguments to a module is using YAML syntax, also called ‘complex args’. \- name: restart webserver service: name: httpd state: restarted All modules return JSON format data. This means modules can be written in any programming language. Modules should be idempotent, and should avoid making any changes if they detect that the current state matches the desired final state. When used in an Ansible playbook, modules can trigger ‘change events’ in the form of notifying [handlers](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_handlers.html#handlers) to run additional tasks. You can access the documentation for each module from the command line with the ansible-doc tool. ansible-doc yum For a list of all available modules, see the [Collection docs](https://docs.ansible.com/projects/ansible/latest/collections/index.html#list-of-collections) , or run the following at a command prompt. ansible-doc -l Boolean variables[](https://docs.ansible.com/projects/ansible/latest/module_plugin_guide/modules_intro.html#boolean-variables "Link to this heading") ======================================================================================================================================================= Ansible accepts a broad range of values for `bool` in module arguments: `true/false`, `1/0`, `yes/no`, `True/False` and so on. The matching of valid strings is case insensitive. While documentation examples focus on `true/false` to be compatible with `ansible-lint` default settings, you can use any of the following: | Valid values | Description | | --- | --- | | `True` , `'true'` , `'t'` , `'yes'` , `'y'` , `'on'` , `'1'` , `1` , `1.0` | Truthy values | | `False` , `'false'` , `'f'` , `'no'` , `'n'` , `'off'` , `'0'` , `0` , `0.0` | Falsy values | See also [Introduction to ad hoc commands](https://docs.ansible.com/projects/ansible/latest/command_guide/intro_adhoc.html#intro-adhoc) Examples of using modules in /usr/bin/ansible [Working with playbooks](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks.html#working-with-playbooks) Examples of using modules with /usr/bin/ansible-playbook [Should you develop a module?](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules.html#developing-modules) How to write your own modules [Python API](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_api.html#developing-api) Examples of using modules with the Python API [Communication](https://docs.ansible.com/projects/ansible/latest/community/communication.html#communication) Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide [Indexes of all modules and plugins](https://docs.ansible.com/projects/ansible/latest/collections/all_plugins.html#all-modules-and-plugins) All modules and plugins available --- # Ansible architecture — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * [Developer Guide](https://docs.ansible.com/projects/ansible/latest/dev_guide/index.html) * Ansible architecture * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/dev_guide/overview_architecture.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Ansible architecture[](https://docs.ansible.com/projects/ansible/latest/dev_guide/overview_architecture.html#ansible-architecture "Link to this heading") =========================================================================================================================================================== Ansible is a radically simple IT automation engine that automates cloud provisioning, configuration management, application deployment, intra-service orchestration, and many other IT needs. 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. It uses no agents and no additional custom security infrastructure, so it is easy to deploy - and most importantly, it uses a very simple language (YAML, in the form of Ansible Playbooks) that allows you to describe your automation jobs in a way that approaches plain English. In this section, we’ll give you a really quick overview of how Ansible works so you can see how the pieces fit together. [Modules](https://docs.ansible.com/projects/ansible/latest/dev_guide/overview_architecture.html#id1) [](https://docs.ansible.com/projects/ansible/latest/dev_guide/overview_architecture.html#modules "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- 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. You can [write your own modules](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_general.html#developing-modules-general) , though you should first consider [whether you should](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules.html#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). [Module utilities](https://docs.ansible.com/projects/ansible/latest/dev_guide/overview_architecture.html#id2) [](https://docs.ansible.com/projects/ansible/latest/dev_guide/overview_architecture.html#module-utilities "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- 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 [write your own module utilities](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_module_utilities.html#developing-module-utilities) as well. Module utilities may only be written in Python or in PowerShell. [Plugins](https://docs.ansible.com/projects/ansible/latest/dev_guide/overview_architecture.html#id3) [](https://docs.ansible.com/projects/ansible/latest/dev_guide/overview_architecture.html#plugins "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- [Plugins](https://docs.ansible.com/projects/ansible/latest/plugins/plugins.html#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 [write your own](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_plugins.html#developing-plugins) . For example, you can write an [inventory plugin](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_inventory.html#developing-inventory) to connect to any datasource that returns JSON. Plugins must be written in Python. [Inventory](https://docs.ansible.com/projects/ansible/latest/dev_guide/overview_architecture.html#id4) [](https://docs.ansible.com/projects/ansible/latest/dev_guide/overview_architecture.html#inventory "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- 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. 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. 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. Here’s what a plain text inventory file looks like: \[webservers\] www1.example.com www2.example.com \[dbservers\] db0.example.com db1.example.com 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. Or, as already mentioned, use a dynamic inventory to pull your inventory from data sources like EC2, Rackspace, or OpenStack. [Playbooks](https://docs.ansible.com/projects/ansible/latest/dev_guide/overview_architecture.html#id5) [](https://docs.ansible.com/projects/ansible/latest/dev_guide/overview_architecture.html#playbooks "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- 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. 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. Here’s what a simple playbook looks like: \--- \- hosts: webservers serial: 5 \# update 5 machines at a time roles: \- common \- webapp \- hosts: content\_servers roles: \- common \- content [The Ansible search path](https://docs.ansible.com/projects/ansible/latest/dev_guide/overview_architecture.html#id6) [](https://docs.ansible.com/projects/ansible/latest/dev_guide/overview_architecture.html#the-ansible-search-path "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- 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. 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: 1. 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: /path/to/modules /path/to/module\_utils /path/to/plugins 2. 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: /path/to/subdir/modules /path/to/subdir/module\_utils /path/to/subdir/plugins 3. Subdirectories of a role directory referenced by a playbook. If `play.yml` runs `myrole`, Ansible appends these directories if they exist: /path/to/roles/myrole/modules /path/to/roles/myrole/module\_utils /path/to/roles/myrole/plugins 4. Directories specified as default paths in `ansible.cfg` or by the related environment variables, including the paths for the various plugin types. See [Ansible Configuration Settings](https://docs.ansible.com/projects/ansible/latest/reference_appendices/config.html#ansible-configuration-settings) for more information. Sample `ansible.cfg` fields: DEFAULT\_MODULE\_PATH DEFAULT\_MODULE\_UTILS\_PATH DEFAULT\_CACHE\_PLUGIN\_PATH DEFAULT\_FILTER\_PLUGIN\_PATH Sample environment variables: ANSIBLE\_LIBRARY ANSIBLE\_MODULE\_UTILS ANSIBLE\_CACHE\_PLUGINS ANSIBLE\_FILTER\_PLUGINS 5. The standard directories that ship as part of the Ansible distribution. Caution 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`. 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. --- # Adding modules and plugins locally — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * [Developer Guide](https://docs.ansible.com/projects/ansible/latest/dev_guide/index.html) * Adding modules and plugins locally * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/dev_guide/developing_locally.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Adding modules and plugins locally[](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_locally.html#adding-modules-and-plugins-locally "Link to this heading") ==================================================================================================================================================================================== You can extend Ansible by adding custom modules or plugins. You can create them from scratch 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 plugins and modules by including them in a collection, then publishing the collection on Ansible Galaxy. If you are using a local module or plugin but Ansible cannot find it, this page is all you need. If you want to create a plugin or a module, see [Developing plugins](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_plugins.html#developing-plugins) , [Developing modules](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_general.html#developing-modules-general) and [Developing collections](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_collections.html#developing-collections) . Extending Ansible with local modules and plugins offers shortcuts such as: * You can copy other people’s modules and plugins. * When writing a new module, you can choose any programming language you like. * You do not have to clone any repositories. * You do not have to open a pull request. * You do not have to add tests (though we recommend that you do!). [Modules and plugins: what is the difference?](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_locally.html#id1) [](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_locally.html#modules-and-plugins-what-is-the-difference "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- If you are looking to add functionality to Ansible, you might wonder whether you need a module or a plugin. Here is a quick overview to help you understand what you need: * [Plugins](https://docs.ansible.com/projects/ansible/latest/plugins/plugins.html#working-with-plugins) extend Ansible’s core functionality. Most plugin types 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. * Modules are a type of plugin that execute automation tasks on a ‘target’ (usually a remote system). Modules work as standalone scripts that Ansible executes in their own process outside of the control node. Modules interface with Ansible mostly with JSON, accepting arguments and returning information by printing a JSON string to stdout before exiting. Unlike the other plugins (which must be written in Python), modules can be written in any language; although Ansible provides modules in Python and Powershell only. [Adding modules and plugins in collections](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_locally.html#id2) [](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_locally.html#adding-modules-and-plugins-in-collections "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can add modules and plugins by [creating a collection](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_collections.html#developing-collections) . With a collection, you can use custom modules and plugins in any playbook or role. You can share your collection easily at any time through Ansible Galaxy. The rest of this page describes other methods of using local, standalone modules or plugins. [Adding a module or plugin outside of a collection](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_locally.html#id3) [](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_locally.html#adding-a-module-or-plugin-outside-of-a-collection "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can configure Ansible to load standalone local modules or plugins in specific locations and make them available to all playbooks and roles (using configured paths). Alternatively, you can make a non-collection local module or plugin available only to certain playbooks or roles (with adjacent paths). ### [Adding standalone local modules for all playbooks and roles](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_locally.html#id4) [](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_locally.html#adding-standalone-local-modules-for-all-playbooks-and-roles "Link to this heading") To load standalone local modules automatically and make them available to all playbooks and roles, use the [DEFAULT\_MODULE\_PATH](https://docs.ansible.com/projects/ansible/latest/reference_appendices/config.html#default-module-path) configuration setting or the `ANSIBLE_LIBRARY` environment variable. The configuration setting and environment variable take a colon-separated list, similar to `$PATH`. You have two options: * Add your standalone local module to one of the default configured locations. See the [DEFAULT\_MODULE\_PATH](https://docs.ansible.com/projects/ansible/latest/reference_appendices/config.html#default-module-path) configuration setting for details. Default locations may change without notice. * Add the location of your standalone local module to an environment variable or configuration: * the `ANSIBLE_LIBRARY` environment variable * the [DEFAULT\_MODULE\_PATH](https://docs.ansible.com/projects/ansible/latest/reference_appendices/config.html#default-module-path) configuration setting To view your current configuration settings for modules: ansible-config dump |grep DEFAULT\_MODULE\_PATH After you save your module file in one of these locations, Ansible loads it and you can use it in any local task, playbook, or role. To confirm that `my_local_module` is available: * type `ansible localhost -m my_local_module` to see the output for that module, or * type `ansible-doc -t module my_local_module` to see the documentation for that module Note This applies to all plugin types but requires specific configuration and/or adjacent directories for each plugin type, see below. Note The `ansible-doc` command can parse module documentation from modules written in Python or an adjacent YAML file. If you have a module written in a programming language other than Python, you should write the documentation in a Python or YAML file adjacent to the module file. [Adjacent YAML documentation files](https://docs.ansible.com/projects/ansible/latest/dev_guide/sidecar.html#adjacent-yaml-doc) ### [Adding standalone local modules for selected playbooks or a single role](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_locally.html#id5) [](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_locally.html#adding-standalone-local-modules-for-selected-playbooks-or-a-single-role "Link to this heading") Ansible automatically loads all executable files from certain directories adjacent to your playbook or role as modules. Standalone modules in these locations are available only to the specific playbook, playbooks, or role in the parent directory. * To use a standalone module only in a selected playbook or playbooks, store the module in a subdirectory called `library` in the directory that contains the playbook or playbooks. * To use a standalone module only in a single role, store the module in a subdirectory called `library` within that role. Note This applies to all plugin types but requires specific configuration and/or adjacent directories for each plugin type, see below. Warning Roles contained in collections cannot contain any modules or other plugins. All plugins in a collection must live in the collection `plugins` directory tree. All plugins in that tree are accessible to all roles in the collection. If you are developing new modules, we recommend distributing them in [collections](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_collections.html#developing-collections) , not in roles. [Adding a non-module plugin locally outside of a collection](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_locally.html#id6) [](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_locally.html#adding-a-non-module-plugin-locally-outside-of-a-collection "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can configure Ansible to load standalone local plugins in a specified location or locations and make them available to all playbooks and roles. Alternatively, you can make a standalone local plugin available only to specific playbooks or roles. Note Although modules are plugins, the naming patterns for directory names and environment variables that apply to other plugin types do not apply to modules. See [Adding a module or plugin outside of a collection](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_locally.html#local-modules) . ### [Adding local non-module plugins for all playbooks and roles](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_locally.html#id7) [](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_locally.html#adding-local-non-module-plugins-for-all-playbooks-and-roles "Link to this heading") To load standalone local plugins automatically and make them available to all playbooks and roles, use the configuration setting or environment variable for the type of plugin you are adding. These configuration settings and environment variables take a colon-separated list, similar to `$PATH`. You have two options: * Add your local plugin to one of the default configured locations. See [configuration settings](https://docs.ansible.com/projects/ansible/latest/reference_appendices/config.html#ansible-configuration-settings) for details on the correct configuration setting for the plugin type. Default locations may change without notice. * Add the location of your local plugin to an environment variable or configuration: * the relevant `ANSIBLE_plugin_type_PLUGINS` environment variable - for example, `$ANSIBLE_INVENTORY_PLUGINS` or `$ANSIBLE_VARS_PLUGINS` * the relevant `plugin_type_PATH` configuration setting, most of which begin with `DEFAULT_` - for example, `DEFAULT_CALLBACK_PLUGIN_PATH` or `DEFAULT_FILTER_PLUGIN_PATH` or `BECOME_PLUGIN_PATH` To view your current configuration settings for non-module plugins: ansible-config dump |grep plugin\_type\_PATH After your plugin file is added to one of these locations, Ansible loads it and you can use it in any local module, task, playbook, or role. For more information on environment variables and configuration settings, see [Ansible Configuration Settings](https://docs.ansible.com/projects/ansible/latest/reference_appendices/config.html#ansible-configuration-settings) . To confirm that `plugins/plugin_type/my_local_plugin` is available: * type `ansible-doc -t my_local_lookup_plugin` to see the documentation for that plugin - for example, `ansible-doc -t lookup my_local_lookup_plugin` The `ansible-doc` command works for most plugin types, but not for action, filter, or test plugins. See [ansible-doc](https://docs.ansible.com/projects/ansible/latest/cli/ansible-doc.html#ansible-doc) for more details. ### [Adding standalone local plugins for selected playbooks or a single role](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_locally.html#id8) [](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_locally.html#adding-standalone-local-plugins-for-selected-playbooks-or-a-single-role "Link to this heading") Ansible automatically loads all plugins from certain directories adjacent to your playbook or role, loading each type of plugin separately from a directory named for the type of plugin. Standalone plugins in these locations are available only to the specific playbook, playbooks, or role in the parent directory. * To use a standalone plugin only 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. These directories must use the `_plugins` suffix. For a full list of plugin types, see [Working with plugins](https://docs.ansible.com/projects/ansible/latest/plugins/plugins.html#working-with-plugins) . * To use a standalone plugin only 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. These directories must use the `_plugins` suffix. For a full list of plugin types, see [Working with plugins](https://docs.ansible.com/projects/ansible/latest/plugins/plugins.html#working-with-plugins) . Warning Roles contained in collections cannot contain any plugins. All plugins in a collection must live in the collection `plugins` directory tree. All plugins in that tree are accessible to all roles in the collection. If you are developing new plugins, we recommend distributing them in [collections](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_collections.html#developing-collections) , not in roles. Warning Some plugin types are needed early during Ansible execution, such as callbacks, inventory, and cache. These plugin types cannot be loaded dynamically and must exist in configured paths or be referenced by FQCN in configuration. [Using `ansible.legacy` to access custom versions of an `ansible.builtin` module](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_locally.html#id9) [](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_locally.html#using-ansible-legacy-to-access-custom-versions-of-an-ansible-builtin-module "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- If you need to override one of the `ansible.builtin` modules and are using FQCN, you need to use `ansible.legacy` as part of the fully-qualified collection name (FQCN). For example, if you had your own `copy` module, you would access it as `ansible.legacy.copy`. See [Using ansible.legacy to access local custom modules from collections-based roles](https://docs.ansible.com/projects/ansible/latest/dev_guide/migrating_roles.html#using-ansible-legacy) for details on how to use custom modules with roles within a collection. --- # Config file reference - antsibull-nox – Antsibull Nox Helper [Skip to content](https://docs.ansible.com/projects/antsibull-nox/config-file/#config-file-reference) Config file reference[¶](https://docs.ansible.com/projects/antsibull-nox/config-file/#config-file-reference "Permanent link") ============================================================================================================================== This document assumes some basic familiarity with the [TOML file format](https://toml.io/en/) . You might also want to read [Getting Started](https://docs.ansible.com/projects/antsibull-nox/getting-started/) first if you haven't already done so. Basic config file structure[¶](https://docs.ansible.com/projects/antsibull-nox/config-file/#basic-config-file-structure "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------ The configuration must be named `antsibull-nox.toml`. A basic `antsibull-nox.toml` looks as follows: `[](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-1) # Comments start with a '#', similar to YAML or Python. [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-2) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-3) [collection] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-4) # Use ansible-test's config file (tests/config.yml) to determine which [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-5) # Python versions to use when generating test matrixes. [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-6) min_python_version = "ansible-test-config" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-7) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-8) [collection_sources] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-9) # This section tells antsibull-nox how to install collections. [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-10) # We want to install community.internal_test_tools, community.general, and community.crypto [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-11) # from Git and not from Galaxy. [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-12) "community.internal_test_tools" = "git+https://github.com/ansible-collections/community.internal_test_tools.git,main" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-13) "community.general" = "git+https://github.com/ansible-collections/community.general.git,main" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-14) "community.crypto" = "git+https://github.com/ansible-collections/community.crypto.git,main" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-15) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-16) [collection_sources_per_ansible.'2.16'] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-17) # This section tells antsibull-nox how to install collections for ansible-core 2.16. [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-18) # (Note that we have to quote the ansible-core version in the section name!) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-19) # [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-20) # If a collection is not mentioned here, the above generic section will be used. [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-21) # (And if it cannot be found there, antsibull-nox will simply get it from ansible-galaxy's default source.) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-22) # [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-23) # We want to install community.crypto from its stable-2 branch from Git [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-24) # (the main branch only works with ansible-core 2.17+). [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-25) "community.crypto" = "git+https://github.com/ansible-collections/community.crypto.git,stable-2" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-26) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-27) [sessions] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-28) # The sub-sections of 'sessions' configure sessions to add. [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-29) # An empty session configures a session with all its default values. [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-30) # Omitting a session means that the session is not added. [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-31) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-32) [sessions.lint] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-33) # The lint session has several settings specified: [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-34) extra_code_files = ["update-docs-fragments.py"] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-35) isort_config = "tests/nox-config-isort.cfg" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-36) run_black_modules = false # modules still support Python 2 [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-37) black_config = "tests/nox-config-black.toml" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-38) flake8_config = "tests/nox-config-flake8.ini" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-39) pylint_rcfile = "tests/nox-config-pylint.rc" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-40) pylint_modules_rcfile = "tests/nox-config-pylint-py2.rc" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-41) yamllint_config = "tests/nox-config-yamllint.yml" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-42) yamllint_config_plugins = "tests/nox-config-yamllint-plugins.yml" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-43) yamllint_config_plugins_examples = "tests/nox-config-yamllint-plugins-examples.yml" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-44) mypy_config = "tests/nox-config-mypy.ini" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-45) mypy_extra_deps = [ [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-46) "dnspython", [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-47) "types-lxml", [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-48) "types-mock", [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-49) "types-PyYAML", [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-50) ] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-51) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-52) [sessions.docs_check] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-53) # The docs check session is added with almost all settings [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-54) # set to their defaults, except one: [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-55) validate_collection_refs="all" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-56) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-57) [sessions.license_check] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-58) # The license check session is added with default settings. [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-59) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-0-60) # ...` Make sure that your `noxfile.py` contains the `antsibull_nox.load_antsibull_nox_toml()` function call. Otherwise `antsibull-nox.toml` will be ignored. General collection configuration[¶](https://docs.ansible.com/projects/antsibull-nox/config-file/#general-collection-configuration "Permanent link") ---------------------------------------------------------------------------------------------------------------------------------------------------- The `[collection]` section allows to do some general configuration. Right now the following settings are supported: * `min_python_version: "default" | "controller" | "ansible-test-config" | Version` (default: `default`). When generating test matrixes with Python versions, this option will be used as a lower limit. Right now this is only used for the `[sessions.ansible_test_integration_w_default_container]` section. When set to `"ansible-test-config"`, `tests/config.yml` in the collection is loaded and interpreted as in [ansible-test's example config.yml file](https://github.com/ansible/ansible/blob/devel/test/lib/ansible_test/config/config.yml) . Note If a specifier set is applied, it is checked against Python versions of the form `x.y`. Setup collection installation[¶](https://docs.ansible.com/projects/antsibull-nox/config-file/#setup-collection-installation "Permanent link") ---------------------------------------------------------------------------------------------------------------------------------------------- By default, antsibull-nox installs collection dependencies that are needed by using `ansible-galaxy collection download` to download them to a cache directory inside Nox's cache directory, which is usually `.nox` inside the directory which contains `noxfile.py`. If you prefer collections to be cloned from Git repositories instead, you have to tell antsibull-nox how to download collections. The section `[collection_sources]` allows to configure this: `[](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-1-1) [collection_sources] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-1-2) # We want to install community.internal_test_tools and community.general [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-1-3) # from Git and not from Galaxy. [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-1-4) "community.internal_test_tools" = "git+https://github.com/ansible-collections/community.internal_test_tools.git,main" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-1-5) "community.general" = "git+https://github.com/ansible-collections/community.general.git,main" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-1-6) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-1-7) # community.dns should be installed from Galaxy: [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-1-8) "community.dns" = "community.dns" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-1-9) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-1-10) # We want to limit community.crypto to < 3.0.0: [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-1-11) "community.dns" = "community.dns:<3.0.0"` The syntax used is explained in [the Ansible documentation on installation of collections from Git repositories](https://docs.ansible.com/ansible-core/devel/collections_guide/collections_installing.html#installing-a-collection-from-a-git-repository-at-the-command-line) and [the Ansible documentation on installation of older versions of a collection](https://docs.ansible.com/ansible-core/devel/collections_guide/collections_installing.html#installing-an-older-version-of-a-collection) . ### Specific collection sources per ansible-core version[¶](https://docs.ansible.com/projects/antsibull-nox/config-file/#specific-collection-sources-per-ansible-core-version "Permanent link") Sometimes it is necessary to use different sources for different ansible-core versions. For example, your collection might support ansible-core 2.16+. For testing, you need a collection that you want to install from Git. Unfortunately, the `main` branch only works with ansible-core 2.17+, so you need to use another branch for ansible-core 2.16. In the following example, community.crypto is such a collection. Its `main` branch needs ansible-core 2.17+, but its `stable-2` branch also supports ansible-core 2.16 and before. You can tell antsibull-nox to use the `stable-2` branch with ansible-core 2.16 by adding a `[collection_sources_per_ansible.'2.16']` section (note the quotes!). `[](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-2-1) [collection_sources] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-2-2) # This section tells antsibull-nox how to install collections. [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-2-3) # We want to install community.internal_test_tools, community.general, and community.crypto [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-2-4) # from Git and not from Galaxy. [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-2-5) "community.internal_test_tools" = "git+https://github.com/ansible-collections/community.internal_test_tools.git,main" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-2-6) "community.general" = "git+https://github.com/ansible-collections/community.general.git,main" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-2-7) "community.crypto" = "git+https://github.com/ansible-collections/community.crypto.git,main" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-2-8) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-2-9) [collection_sources_per_ansible.'2.16'] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-2-10) # This section tells antsibull-nox how to install collections for ansible-core 2.16. [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-2-11) # (Note that we have to quote the ansible-core version in the section name!) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-2-12) # [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-2-13) # If a collection is not mentioned here, the above generic section will be used. [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-2-14) # (And if it cannot be found there, antsibull-nox will simply get it from ansible-galaxy's default source.) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-2-15) # [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-2-16) # We want to install community.crypto from its stable-2 branch from Git [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-2-17) # (the main branch only works with ansible-core 2.17+). [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-2-18) "community.crypto" = "git+https://github.com/ansible-collections/community.crypto.git,stable-2"` Version Control System configuration[¶](https://docs.ansible.com/projects/antsibull-nox/config-file/#version-control-system-configuration "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------------------------ For features such as [Change Detection](https://docs.ansible.com/projects/antsibull-nox/change-detection/) , some information on the Version Control System (VCS) system needs to be known. This can be configured in `[vcs]`. The following options are available: * `vcs: "git"` (**required**): The VCS used. Currently only `git` is supported. If you are interested in support for other VCS, please [create an issue](https://github.com/ansible-community/antsibull-nox/issues/new) . * `development_branch: str` (**required**): The name of the main development branch. This is usually `"main"`. * `stable_branches: list[str]` (default: `[]`): A list of branches considered stable, like for releasing from them for older versions. Wildcards can be used, see [Python's fnmatch module](https://docs.python.org/3/library/fnmatch.html) for available wildcards. Package names[¶](https://docs.ansible.com/projects/antsibull-nox/config-file/#package-names "Permanent link") -------------------------------------------------------------------------------------------------------------- For many sessions, the package names of tools that are used / installed can be configured. These options usually end with `_package`. These options are all annotated as `PackageType` in the configuration reference below. Some options ending with `_extra_deps` are using `list[str | SinglePackageType]`. There, `SinglePackageType` is one single element of a `PackageType` list. Package names may be simple strings, a special dictionary to install an editable dependency, a requirements file, or a constraints file, or a list of strings or such dictionaries to provide multiple of these. Using the `ruff_package` config option as an example, the following examples show the valid formats for specifying package names throughout the configuration: `[](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-3-1) # Simple package name [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-3-2) ruff_package = "ruff" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-3-3) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-3-4) # More verbose syntax for package name [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-3-5) ruff_package = {type = "package", name = "ruff"} [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-3-6) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-3-7) # Editable package (path relative to noxfile.py) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-3-8) # Package will be installed without editable mode when ALLOW_EDITABLE is disabled. [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-3-9) ruff_package = {type = "editable", name = "./path-to-editable-package"} [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-3-10) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-3-11) # Requirements file [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-3-12) ruff_package = {type = "requirements", file = "requirements/ruff.txt"} [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-3-13) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-3-14) # Constraints file [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-3-15) # (Note that by itself, this doesn't make any sense.) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-3-16) ruff_package = {type = "constraints", file = "requirements/ruff-constraints.txt"} [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-3-17) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-3-18) # A package together with a requirements file and a constraints file [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-3-19) ruff_package = [ [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-3-20) "ruff", [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-3-21) {type = "requirements", file = "requirements/ruff-extra.txt"}, [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-3-22) {type = "constraints", file = "requirements/ruff-constraints.txt"}, [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-3-23) ]` Note Whether editable mode is allowed can be configured with the `ALLOW_EDITABLE` environment variable. Set it to `1` or `true` (ignoring case) to allow editable installs. If not set, the default is `true` unless `nox` is run in a CI system, in which case the default is `false`. Note CI is currently detected by checking for the `CI` environment variable. If your CI system is not supported, you can simply set `CI=true` before running `nox` in CI. Basic linting sessions[¶](https://docs.ansible.com/projects/antsibull-nox/config-file/#basic-linting-sessions "Permanent link") -------------------------------------------------------------------------------------------------------------------------------- The basic linting session, `lint`, comes with three sessions it depends on: * `formatters`: runs `isort` and `black` to sort imports and format the code. During a regular run, the formatting is directly applied. In CI, the sorting order and formatting is checked, and the tests fail if it is not as expected. * `codeqa`: runs `ruff check`, `flake8`, and `pylint`. * `yamllint`: runs `yamllint` on all `.yml` and `.yaml` files, on the documentation included in Ansible modules and plugins, and on YAML code included in extra docs. * `typing`: runs `mypy`. These sessions can be added with the `[sessions.lint]` section in `antsibull-nox.toml`. Which of the linters should be run can be configured (the extra sessions are not added if they are empty), and there are plenty of configuration settings for the indiviual formatters/linters. ### Global settings:[¶](https://docs.ansible.com/projects/antsibull-nox/config-file/#global-settings "Permanent link") * `default: bool` (default `true`): Whether the `lint` session should be made default. This means that when a user just runs `nox` without specifying sessions, this session will run. * `code_files: "default" | list[str]` (default `"default"`): The code files the linters and formatters will operate on. If set to `"default"`, `plugins/`, `tests/unit/`, and `noxfile.py` will be used and the files and directories from `extra_code_files` will be added (for mypy and pylint, `noxfile.py` will be skipped). When specifying this option, the default set of files will be overridden by the list specified. For example, you can specify `["."]` to process all Python files in the collection. You can use [glob patterns](https://docs.python.org/3/library/pathlib.html#pathlib-pattern-language) . For example, `"tests/integration/targets/*/*_plugins"` considers all local plugins defined in integration test roles. * `extra_code_files: list[str]` (default `[]`): An extra list of files to run the formatters and linters on. By default the formatters and linters run on code files in `plugins/`, `tests/unit/`, and on `noxfile.py`. If you have other scripts in your collection that should be checked, you can add them with this option. Note If `code_files` has been specified, `extra_code_files` cannot be used. * `module_files: "default" | list[str]` (default `"default"`): The code files the linters and formatters will treat as module files. These can be processed with different linter/formatter configurations. If set to `"default"`, `plugins/modules/`, `plugins/module_utils/`, `tests/unit/plugins/modules/`, and `tests/unit/plugins/module_utils/` will be used. You can use [glob patterns](https://docs.python.org/3/library/pathlib.html#pathlib-pattern-language) . For example, `"tests/integration/targets/*/library"` considers all local modules defined in integration test roles. * `ruff_config: str | os.PathLike | None` (default `None`): Specifies a config file for `ruff`. Use a path relative to `noxfile.py`. This config file applies to all `ruff` checks but can be overridden for specific `ruff` invocations. Note that antsibull-nox does not currently supply a default config file, but this might change in the future. * `ruff_modules_config: str | os.PathLike | None` (default `None`): Specifies a config file for `ruff` that is used for modules and module utils. (The `module_files` option allows to configure which files are treated this way.) If not specified but `ruff_config` is specified, `ruff_config` will be used for these files. Use a path relative to `noxfile.py`. Note that antsibull-nox does not currently supply a default config file, but this might change in the future. * `ruff_package: PackageType` (default `"ruff"`): The package to install for `ruff`. This config file applies to all `ruff` checks but can be overridden for specific `ruff` invocations. You can specify a value here to add restrictions to the `ruff` version, or to pin the version, or to install the package from a local repository. ### `isort` (part of the `formatters` session)[¶](https://docs.ansible.com/projects/antsibull-nox/config-file/#isort-part-of-the-formatters-session "Permanent link") * `run_isort: bool` (default `true`): Whether to run `isort`. * `isort_config: str | os.PathLike | None` (default `None`): Specifies a config file for `isort`. Use a path relative to `noxfile.py`. Note that antsibull-nox does not currently supply a default config file, but this might change in the future. * `isort_modules_config: str | os.PathLike | None` (default `None`): Specifies a config file for `isort` that is used for modules and module utils. (The `module_files` option allows to configure which files are treated this way.) If not specified but `isort_config` is specified, `isort_config` will be used for these files. Use a path relative to `noxfile.py`. Note that antsibull-nox does not currently supply a default config file, but this might change in the future. * `isort_package: PackageType` (default `"isort"`): The package to install for `isort` in this session. You can specify a value here to add restrictions to the `isort` version, or to pin the version, or to install the package from a local repository. ### `black` (part of the `formatters` session)[¶](https://docs.ansible.com/projects/antsibull-nox/config-file/#black-part-of-the-formatters-session "Permanent link") * `run_black: bool` (default `true`): Whether to run `black`. * `run_black_modules: bool | None` (default `true`): Whether to run `black` also for module utils, modules, and related unit tests. If your collection supports Python 2.7 for modules, and for example needs to use the `u` prefix for Unicode strings, you can use this to avoid reformatting of that code (which for example removes the `u` prefix). * `black_config: str | os.PathLike | None` (default `None`): Specifies a config file for `black`. Use a path relative to `noxfile.py`. Note that antsibull-nox does not currently supply a default config file, but this might change in the future. * `black_modules_config: str | os.PathLike | None` (default `None`): Specifies a config file for `black` that is used for modules and module utils. (The `module_files` option allows to configure which files are treated this way.) If not specified but `black_config` is specified, `black_config` will be used for these files. Use a path relative to `noxfile.py`. Note that antsibull-nox does not currently supply a default config file, but this might change in the future. * `black_package: PackageType` (default `"black"`): The package to install for `black` in this session. You can specify a value here to add restrictions to the `black` version, or to pin the version, or to install the package from a local repository. ### `ruff format` (part of the `formatters` session)[¶](https://docs.ansible.com/projects/antsibull-nox/config-file/#ruff-format-part-of-the-formatters-session "Permanent link") * `run_ruff_format: bool` (default `false`): Whether to run `ruff format`. * `ruff_format_config: str | os.PathLike | None` (default `None`): Specifies a config file for `ruff format`. Use a path relative to `noxfile.py`. Falls back to `ruff_config` if set to `None`. Note that antsibull-nox does not currently supply a default config file, but this might change in the future. * `ruff_format_modules_config: str | os.PathLike | None` (default `None`): Specifies a config file for `ruff format` that is used for modules and module utils. (The `module_files` option allows to configure which files are treated this way.) Use a path relative to `noxfile.py`. Falls back to `ruff_modules_config` and then to `ruff_format_config` if set to `None`. Note that antsibull-nox does not currently supply a default config file, but this might change in the future. * `ruff_format_package: PackageType | None` (default `None`): The package to install for `ruff` in this session. Falls back to `ruff_package` if set to `None`. You can specify a value here to add restrictions to the `ruff` version, or to pin the version, or to install the package from a local repository. ### `ruff check --fix` (part of the `formatters` session)[¶](https://docs.ansible.com/projects/antsibull-nox/config-file/#ruff-check-fix-part-of-the-formatters-session "Permanent link") * `run_ruff_autofix: bool` (default `false`): Whether to run `ruff check --fix`. * `ruff_autofix_config: str | os.PathLike | None` (default `None`): Specifies a config file for `ruff check --fix`. Use a path relative to `noxfile.py`. Falls back to `ruff_config` if set to `None`. Note that antsibull-nox does not currently supply a default config file, but this might change in the future. * `ruff_autofix_modules_config: str | os.PathLike | None` (default `None`): Specifies a config file for `ruff check --fix` that is used for modules and module utils. (The `module_files` option allows to configure which files are treated this way.) Use a path relative to `noxfile.py`. Falls back to `ruff_modules_config` and then to `ruff_autofix_config` if set to `None`. Note that antsibull-nox does not currently supply a default config file, but this might change in the future. * `ruff_autofix_package: PackageType | None` (default `None`): The package to install for `ruff` in this session. Falls back to `ruff_package` if set to `None`. You can specify a value here to add restrictions to the `ruff` version, or to pin the version, or to install the package from a local repository. * `ruff_autofix_select: list[str]` (default `[]`): Selects which rules to fix. Will be passed with `--select`. An empty list passes no `--select` option and runs all available fixers. ### `ruff check` (part of the `codeqa` session)[¶](https://docs.ansible.com/projects/antsibull-nox/config-file/#ruff-check-part-of-the-codeqa-session "Permanent link") * `run_ruff_check: bool` (default `false`): Whether to run `ruff check`. * `ruff_check_config: str | os.PathLike | None` (default `None`): Specifies a config file for `ruff check`. Use a path relative to `noxfile.py`. Falls back to `ruff_config` if set to `None`. Note that antsibull-nox does not currently supply a default config file, but this might change in the future. * `ruff_check_modules_config: str | os.PathLike | None` (default `None`): Specifies a config file for `ruff check` that is used for modules and module utils. (The `module_files` option allows to configure which files are treated this way.) Use a path relative to `noxfile.py`. Falls back to `ruff_modules_config` and then to `ruff_check_config` if set to `None`. Note that antsibull-nox does not currently supply a default config file, but this might change in the future. * `ruff_check_package: PackageType | None` (default `None`): The package to install for `ruff` in this session. Falls back to `ruff_package` if set to `None`. You can specify a value here to add restrictions to the `ruff` version, or to pin the version, or to install the package from a local repository. ### `flake8` (part of the `codeqa` session)[¶](https://docs.ansible.com/projects/antsibull-nox/config-file/#flake8-part-of-the-codeqa-session "Permanent link") * `run_flake8: bool` (default `true`): Whether to run `flake8`. * `flake8_config: str | os.PathLike | None` (default `None`): Specifies a config file for `flake8`. Use a path relative to `noxfile.py`. Note that antsibull-nox does not currently supply a default config file, but this might change in the future. * `flake8_modules_config: str | os.PathLike | None` (default `None`): Specifies a config file for `flake8` that is used for modules and module utils. (The `module_files` option allows to configure which files are treated this way.) If not specified but `flake8_config` is specified, `flake8_config` will be used for these files. Use a path relative to `noxfile.py`. Note that antsibull-nox does not currently supply a default config file, but this might change in the future. * `flake8_package: PackageType` (default `"flake8"`): The package to install for `flake8` in this session. You can specify a value here to add restrictions to the `flake8` version, or to pin the version, or to install the package from a local repository. ### `pylint` (part of the `codeqa` session)[¶](https://docs.ansible.com/projects/antsibull-nox/config-file/#pylint-part-of-the-codeqa-session "Permanent link") * `run_pylint: bool` (default `true`): Whether to run `pylint`. * `pylint_rcfile: str | os.PathLike | None` (default `None`): Specifies a config file for `pylint`. Use a path relative to `noxfile.py`. Note that antsibull-nox does not currently supply a default config file, but this might change in the future. * `pylint_modules_rcfile: str | os.PathLike | None` (default `None`): Specifies a config file for `pylint` for modules, module utils, and the associated unit tests. (The `module_files` option allows to configure which files are treated this way.) If not specified but `pylint_rcfile` is specified, `pylint_rcfile` will be used for these files. Use a path relative to `noxfile.py`. Note that antsibull-nox does not currently supply a default config file, but this might change in the future. * `pylint_package: PackageType` (default `"pylint"`): The package to install for `pylint` in this session. You can specify a value here to add restrictions to the `pylint` version, or to pin the version, or to install the package from a local repository. * `pylint_ansible_core_package: PackageType` (default `"ansible-core"`): The package to install for `ansible-core` in this session. You can specify a value here to add restrictions to the `ansible-core` version, or to pin the version, or to install the package from a local repository. * `pylint_extra_deps: list[str | SinglePackageType]` (default `[]`): Specify further packages to install in this session. Note that currently, strings are shell splitted. This behavoir is deprecated and will be disallowed in a future release. Split these arguments up into multiple list elements, and/or use package type dictionaries like `{type = "requirements", file = "requirements/pylint-extra-deps.txt"}` depending on what you are trying to achieve. ### `yamllint` (part of the `yamllint` session)[¶](https://docs.ansible.com/projects/antsibull-nox/config-file/#yamllint-part-of-the-yamllint-session "Permanent link") * `run_yamllint: bool` (default `true`): Whether to run `yamllint`. * `yamllint_config: str | os.PathLike | None` (default `None`): Specifies a config file for `yamllint`. Use a path relative to `noxfile.py`. Note that antsibull-nox does not currently supply a default config file, but this might change in the future. * `yamllint_config_plugins: str | os.PathLike | None` (default `None`): Specifies a config file for `yamllint` for YAML content embedded in plugins. Use a path relative to `noxfile.py`. If not provided, the same config will be used as for standalone YAML files (`yamllint_config`). * `yamllint_config_plugins_examples: str | os.PathLike | None` (default `None`): Specifies a config file for `yamllint` for YAML examples embedded in plugins and sidecar docs. Use a path relative to `noxfile.py`. If not provided, the same config will be used as for YAML content embedded in plugins (`yamllint_config_plugins`), which falls back to the config used for standalone YAML files (`yamllint_config`). * `yamllint_config_extra_docs: str | os.PathLike | None` (default `None`): Specifies a config file for `yamllint` for YAML code in extra documentation (`docs/docsite/rst/` directory) Use a path relative to `noxfile.py`. If not provided, the same config will be used as for YAML examples embedded in plugins (`yamllint_config_plugins_examples`), which falls back to the `yamllint_config_plugins` and `yamllint_config`. * `yamllint_package: PackageType` (default `"yamllint"`): The package to install for `yamllint` in this session. You can specify a value here to add restrictions to the `yamllint` version, or to pin the version, or to install the package from a local repository. * `yamllint_antsibull_docutils_package: PackageType` (default `"antsibull-docutils"`): The package to install for `antsibull-docutils` in this session. You can specify a value here to add restrictions to the `antsibull-docutils` version, or to pin the version, or to install the package from a local repository. ### `mypy` (part of the `typing` session)[¶](https://docs.ansible.com/projects/antsibull-nox/config-file/#mypy-part-of-the-typing-session "Permanent link") * `run_mypy: bool` (default `true`): Whether to run `mypy`. * `mypy_config: str | os.PathLike | None` (default `None`): Specifies a config file for `mypy`. Use a path relative to `noxfile.py`. Note that antsibull-nox does not currently supply a default config file, but this might change in the future. * `mypy_modules_config: str | os.PathLike | None` (default `None`): Specifies a config file for `mypy` that is used for modules and module utils. (The `module_files` option allows to configure which files are treated this way.) If not specified but `mypy_config` is specified, `mypy_config` will be used for these files. Use a path relative to `noxfile.py`. Note that antsibull-nox does not currently supply a default config file, but this might change in the future. * `mypy_package: PackageType` (default `"mypy"`): The package to install for `mypy` in this session. You can specify a value here to add restrictions to the `mypy` version, or to pin the version, or to install the package from a local repository. * `mypy_ansible_core_package: PackageType` (default `"ansible-core"`): The package to install for `ansible-core` in this session. You can specify a value here to add restrictions to the `ansible-core` version, or to pin the version, or to install the package from a local repository. * `mypy_extra_deps: list[str | SinglePackageType]` (default `[]`): Specify further packages to install in this session. This can be used for typing stubs like `types-PyYAML`, `types-mock`, and so on. Note that currently, strings are shell splitted. This behavoir is deprecated and will be disallowed in a future release. Split these arguments up into multiple list elements, and/or use package type dictionaries like `{type = "requirements", file = "requirements/mypy-extra-deps.txt"}` depending on what you are trying to achieve. ### `antsibull-nox-config` (part of `lint` session)[¶](https://docs.ansible.com/projects/antsibull-nox/config-file/#antsibull-nox-config-part-of-lint-session "Permanent link") * `run_antsibullnox_config_lint: bool` (default: `true`): Lints the antsibull-nox configuration. ### Example code[¶](https://docs.ansible.com/projects/antsibull-nox/config-file/#example-code "Permanent link") This example is from `community.dns`, which uses explicit config files for the formatters and linters, and does not format modules and module utils since it relies on the `u` string prefix: It also uses a different `pylint` config for modules and module utils, to be able to have stricter rules for the remaining code, which is Python 3 only. `[](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-4-1) [sessions.lint] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-4-2) extra_code_files = ["update-docs-fragments.py"] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-4-3) isort_config = "tests/nox-config-isort.cfg" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-4-4) run_black_modules = false # modules still support Python 2 [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-4-5) black_config = "tests/nox-config-black.toml" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-4-6) flake8_config = "tests/nox-config-flake8.ini" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-4-7) pylint_rcfile = "tests/nox-config-pylint.rc" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-4-8) pylint_modules_rcfile = "tests/nox-config-pylint-py2.rc" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-4-9) yamllint_config = "tests/nox-config-yamllint.yml" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-4-10) yamllint_config_plugins = "tests/nox-config-yamllint-plugins.yml" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-4-11) yamllint_config_plugins_examples = "tests/nox-config-yamllint-plugins-examples.yml" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-4-12) mypy_config = "tests/nox-config-mypy.ini" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-4-13) mypy_extra_deps = [ [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-4-14) "dnspython", [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-4-15) "types-lxml", [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-4-16) "types-mock", [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-4-17) "types-PyYAML", [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-4-18) ]` Collection documentation check[¶](https://docs.ansible.com/projects/antsibull-nox/config-file/#collection-documentation-check "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------------ The collection documentation check uses antsibull-docs' `antsibull-docs lint-collection-docs` command to validate various documentation-related things: * extra documentation (`docs/docsite/extra-docs.yml`, RST files in `docs/docsite/rst/`); * links for docsite (`docs/docsite/links.yml`); * documentation of modules, plugins, and roles. The latter validation of modules and plugins is more strict and validates more (and for modules, also different) aspects than the `validate-modules` test of `ansible-test sanity`. Also `validate-modules` currently does not validate test and filter plugins, and role argument specs are not validated by it either. The test is added with the `[sessions.docs_check]` section in `antsibull-nox.toml`, and the session is called `docs-check`. The function has the following configuration settings: * `default: bool` (default `true`): Whether the `docs-check` session should be made default. This means that when a user just runs `nox` without specifying sessions, this session will run. * `antsibull_docs_package: PackageType` (default `"antsibull-docs"`): The package to install for `antsibull-docs` in this session. You can specify a value here to add restrictions to the `antsibull-docs` version, or to pin the version, or to install the package from a local repository. * `ansible_core_package: PackageType` (default `"ansible-core"`): The package to install for `ansible-core` in this session. You can specify a value here to add restrictions to the `ansible-core` version, or to pin the version, or to install the package from a local repository. * `validate_collection_refs: "self" | "dependent" | "all" | None` (default `None`): This configures whether references to content (modules/plugins/roles, their options, and return values) in module, plugins, and roles documentation should be validated. * If set to `self`, only references to the own collection will be checked. * If set to `dependent`, only references to the own collection and collections it (transitively) depends on will be checked. * If set to `all`, all references will be checked. Use `extra_collections` to specify other collections that are referenced and that are not dependencies. Refer to the [documentation of antsibull-docs](https://ansible.readthedocs.io/projects/antsibull-docs/collection-docs/) for more information. * `extra_collections: list[str]` (default `[]`): Ensure that further collections will be added to the search path. This is important when setting `validate_collection_refs="all"`. The following options are for a separate test that is run first. It allows to apply certain restrictions to code blocks and literal blocks. * `codeblocks_restrict_types: list[str] | None` (default `None`): If set to a list, only code blocks with these languages are allowed. To accept languages differing by case, set `codeblocks_restrict_type_exact_case` to `false` See `codeblocks_restrict_type_exact_case` below * `codeblocks_restrict_type_exact_case: bool` (default `true`): Whether the code block languages must be exactly as in `codeblocks_restrict_types` (if set to `true`) or can differ by case (if set to `false`). * `codeblocks_allow_without_type: bool` (default `true`): Whether code blocks without language are allowed. * `codeblocks_allow_literal_blocks: bool` (default `true`): Whether literal blocks (`::`) are allowed. * `antsibull_docutils_package: PackageType` (default `"antsibull-docutils"`): The package to install for `antsibull-docutils` in this session. You can specify a value here to add restrictions to the `antsibull-docutils` version, or to pin the version, or to install the package from a local repository. Note that this package is only explicitly installed when certain tests are activated. ### Example code[¶](https://docs.ansible.com/projects/antsibull-nox/config-file/#example-code_1 "Permanent link") This example is from `community.dns`: `[](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-5-1) [sessions.docs_check] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-5-2) validate_collection_refs="all" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-5-3) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-5-4) codeblocks_restrict_types = [ [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-5-5) "yaml", [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-5-6) "yaml+jinja", [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-5-7) ] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-5-8) codeblocks_restrict_type_exact_case = true [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-5-9) codeblocks_allow_without_type = false [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-5-10) codeblocks_allow_literal_blocks = false` REUSE and license checks[¶](https://docs.ansible.com/projects/antsibull-nox/config-file/#reuse-and-license-checks "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------ If the collection conforms to the [REUSE specification](https://reuse.software/) , you can add a `license-check` session to verify conformance. The session is added with the `[sessions.license_check]` section in `antsibull-nox.toml`, and the session is called `license-check`. It accepts the following options: * `default: bool` (default `true`): Whether the `license-check` session should be made default. This means that when a user just runs `nox` without specifying sessions, this session will run. * `run_reuse: bool` (default `true`): Whether to run `reuse lint`. * `reuse_package: PackageType` (default `"reuse"`): The package to install for `reuse` in this session. You can specify a value here to add restrictions to the `reuse` version, or to pin the version, or to install the package from a local repository. * `run_license_check: bool` (default `true`): Whether a custom check script should be run that validates the following conditions: 1. All Python code in `plugins/` except module utils, modules, and docs fragments must be `GPL-3.0-or-later` licensed. 2. Every non-empty file has an allowed license. (This is similar to what `reuse lint` checks.) * `license_check_extra_ignore_paths: list[str]` (default `[]`): Specify more paths that are ignored. You can use [glob patterns](https://docs.python.org/3/library/glob.html) . ### Example code[¶](https://docs.ansible.com/projects/antsibull-nox/config-file/#example-code_2 "Permanent link") This example is from `community.dns`: `[](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-6-1) [sessions.license_check]` Extra checks: action groups, unwanted files, trailing whitespace, unwanted characters/regular expressions[¶](https://docs.ansible.com/projects/antsibull-nox/config-file/#extra-checks-action-groups-unwanted-files-trailing-whitespace-unwanted-charactersregular-expressions "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The extra checks session `extra-checks` runs various extra checks. Right now it can run the following checks: * No unwanted files: This check makes sure that no unwanted files are in `plugins/`. Which file extensions are wanted and which are not can be configured. * Action groups: This check makes sure that the modules you want are part of an action group, and that all modules in an action group use the corresponding docs fragment. * No trailing whitespace: This check flags all trailing whitespace. * Avoid characters: This check allows to flag specific characters / regular expressions in files. For example, you can use this to flag tab characters, Windows newlines, curly quotes, and so on. The session is added with the `[sessions.extra_checks]` section in `antsibull-nox.toml`. It can be configured as follows: * `default: bool` (default `true`): Whether the `license-check` session should be made default. This means that when a user just runs `nox` without specifying sessions, this session will run. * No unwanted files: * `run_no_unwanted_files: bool` (default `true`): Whether the check should be run. * `no_unwanted_files_module_extensions: list[str]` (default `[".cs", ".ps1", ".psm1", ".py"]`): Which file extensions to accept in `plugins/modules/`. * `no_unwanted_files_other_extensions: list[str]` (default `[".py", ".pyi"]`): Which file extensions to accept in `plugins/` outside `plugins/modules/`. Note that YAML files can also be accepted, see the `no_unwanted_files_yaml_extensions` and `no_unwanted_files_yaml_directories` options. * `no_unwanted_files_yaml_extensions: list[str]` (default `[".yml", ".yaml"]`): Which file extensions to accept for YAML files. This is only used in directories specified by `no_unwanted_files_yaml_directories`. * `no_unwanted_files_skip_paths: list[str]` (default `[]`): Which files to ignore. * `no_unwanted_files_skip_directories: list[str]` (default `[]`): Which directories to ignore. * `no_unwanted_files_yaml_directories: list[str]` (default `["plugins/test/", "plugins/filter/"]`): In which directories YAML files should be accepted. * `no_unwanted_files_allow_symlinks: bool` (default `false`): Whether symbolic links should be accepted. * Action groups: * `run_action_groups: bool` (default `false`): Whether the check should be run. * `action_groups_config: list[antsibull_nox.ActionGroup]` (default `[]`): The action groups to check for. The test makes sure that exactly these groups exist. Every group is an object. It should be defined in a new section `[[sessions.extra_checks.action_groups_config]]`. (See [Array of Tables](https://toml.io/en/v1.0.0#array-of-tables) in the TOML Specification.) Groups have the following properties: * `name: str` (**required**): The name of the action group. Must be equal to the name used in `meta/runtime.yml`. * `pattern: str` (**required**): A [Python regular expression](https://docs.python.org/3/library/re.html) matching modules that usually are part of this action group. Every module that is part of this action group must match this regular expression, otherwise the test will fail. If a module matching this regular expression is not part of the action group, it must be explicitly listed in `exclusions` (see below). * `doc_fragment: str` (**required**): The name of the documentation fragment that must be included exactly for all modules that are part of this action group. * `exclusions: list[str]` (default `[]`): This must list all modules whose names match `pattern`, but that are not part of the action group. * No trailing whitespace: * `run_no_trailing_whitespace: bool` (default `false`): Whether the check should be run. * `no_trailing_whitespace_skip_paths: list[str]` (default `[]`): Which files to ignore. * `no_trailing_whitespace_skip_directories: list[str]` (default `[]`): Which directories to ignore. * Avoid characters: * `run_avoid_characters: bool` (default `false`): Whether the check should be run. * `avoid_character_group: list[AvoidCharacterGroup]` (default `[]`): List of groups of regular expressions with optional names and file selectors. Every group is an object. It should be defined in a new section `[[sessions.extra_checks.avoid_character_group]]`. (See [Array of Tables](https://toml.io/en/v1.0.0#array-of-tables) in the TOML Specification.) Groups have the following properties: * `name: str` (**optional**): User-friendly name to show instead of the regular expression. * `regex: str` (**required**): A [Python regular expression](https://docs.python.org/3/library/re.html) to flag when being found. * `match_extensions: list[str] | None` (default `None`): If specified, will only match files whose filename ends with a string from this list. * `match_paths: list[str] | None` (default `None`): If specified, will only match files whose paths are part of this list. * `match_directories: list[str] | None` (default `None`): If specified, will only match files which are in a directory or subdirectory of a path in this list. * `skip_extensions: list[str]` (default `[]`): If specified, will not match files whose filename ends with a string from this list. * `skip_paths: list[str]` (default `[]`): If specified, will only match files whose paths are not part of this list. * `skip_directories: list[str]` (default `[]`): If specified, will not match files which are in a directory or subdirectory of a path in this list. ### Example code[¶](https://docs.ansible.com/projects/antsibull-nox/config-file/#example-code_3 "Permanent link") This example is from `community.dns`. The collection contains a data file, `plugins/public_suffix_list.dat`, that does not match any known extension. Since this file is vendored without modifications, and the collection conforms to the REUSE specifiation, license information is added in another file `plugins/public_suffix_list.dat.license`. The collection has two action groups, one for Hetzner DNS modules, and one for Hosttech DNS modules. `[](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-7-1) [sessions.extra_checks] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-7-2) run_no_unwanted_files = true [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-7-3) no_unwanted_files_module_extensions = [".py"] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-7-4) no_unwanted_files_skip_paths = [ [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-7-5) "plugins/public_suffix_list.dat", [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-7-6) "plugins/public_suffix_list.dat.license", [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-7-7) ] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-7-8) no_unwanted_files_yaml_extensions = [".yml"] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-7-9) run_action_groups = true [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-7-10) run_no_trailing_whitespace = true [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-7-11) run_avoid_characters = true [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-7-12) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-7-13) [[sessions.extra_checks.action_groups_config]] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-7-14) name = "hetzner" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-7-15) pattern = "^hetzner_.*$" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-7-16) exclusions = [] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-7-17) doc_fragment = "community.dns.attributes.actiongroup_hetzner" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-7-18) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-7-19) [[sessions.extra_checks.action_groups_config]] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-7-20) name = "hosttech" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-7-21) pattern = "^hosttech_.*$" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-7-22) exclusions = [] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-7-23) doc_fragment = "community.dns.attributes.actiongroup_hosttech" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-7-24) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-7-25) [[sessions.extra_checks.avoid_character_group]] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-7-26) name = "tab" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-7-27) # Note that we have to escape the backslash for TOML. [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-7-28) # The actual regular expression is '\x09', [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-7-29) # which matches the Unicode character code 9. [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-7-30) regex = "\\x09"` Collection build and Galaxy import test[¶](https://docs.ansible.com/projects/antsibull-nox/config-file/#collection-build-and-galaxy-import-test "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------------------------------ The build and import test check whether a collection can be built with `ansible-galaxy collection build`, and whether the resulting artefact can be imported by the Galaxy importer. The `build-import-check` session is added with the `[sessions.build_import_check]` section in `antsibull-nox.toml`. It accepts the following options: * `default: bool` (default `true`): Whether the `build-import-check` session should be made default. This means that when a user just runs `nox` without specifying sessions, this session will run. * `ansible_core_package: PackageType` (default `"ansible-core"`): The package to install for `ansible-core` in this session. You can specify a value here to add restrictions to the `ansible-core` version, or to pin the version, or to install the package from a local repository. * `run_galaxy_importer: bool` (default `true`): Whether the Galaxy importer should be run on the built collection artefact. * `galaxy_importer_package: PackageType` (default `"galaxy-importer"`): The package to install for `galaxy-importer` in this session. You can specify a value here to add restrictions to the `galaxy-importer` version, or to pin the version, or to install the package from a local repository. * `galaxy_importer_config_path: str | None` (default `None`): Specifies a path to a [Galaxy importer configuration file](https://github.com/ansible/galaxy-importer#configuration) . This allows to configure which aspects to check. Which settings are enabled depends on the Galaxy server the collection should be imported to. [Ansible Automation Hub](https://www.redhat.com/en/technologies/management/ansible/automation-hub) is using different settings than [Ansible Galaxy](https://galaxy.ansible.com/) , for example. * `galaxy_importer_always_show_logs : bool` (default `False`): Whether to always show the Galaxy importer logs. By default they are only shown when nox is run with verbosity enabled (`-v`) or when run in a CI system that supports collapsible groups, like GitHub Actions. In the latter case, the output is always shown in a collapsible group. ### Example code[¶](https://docs.ansible.com/projects/antsibull-nox/config-file/#example-code_4 "Permanent link") This example is from `community.dns`: `[](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-8-1) [sessions.build_import_check] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-8-2) run_galaxy_importer = true` Run ansible-test[¶](https://docs.ansible.com/projects/antsibull-nox/config-file/#run-ansible-test "Permanent link") -------------------------------------------------------------------------------------------------------------------- antsibull-nox provides several ways to run ansible-core's testing tool `ansible-test` directly from nox. It knows which Python versions every ansible-core release supports and picks an installed version of Python for every ansible-test session if possible, or picks the highest supported Python version for the ansible-core release is no installed Python is found. ### Add all sanity test sessions[¶](https://docs.ansible.com/projects/antsibull-nox/config-file/#add-all-sanity-test-sessions "Permanent link") The `ansible-test sanity` sessions are added with the `[sessions.ansible_test_sanity]` section in `antsibull-nox.toml`. Sessions are added for all supported ansible-core versions. Sanity tests will always be run using ansible-test's `default` container. The function supports the following parameters: * `default: bool` (default `false`): Whether the sessions should be made default. This means that when a user just runs `nox` without specifying sessions, these sessions will run. * `include_devel: bool` (default `false`): Whether ansible-core's `devel` branch should also be used. This is the development version of ansible-core and can break at any moment. This can be very helpful to prepare your collection against breaking changes in upcoming ansible-core versions early on. You should only run against it if you are ready for this. * `include_milestone: bool` (default `false`): Whether ansible-core's `milestone` branch should also be used. Note that the milestone branch is from the latest development version, but is updated only once for every ansible-core development phase at specific dates published in advance. * `add_devel_like_branches: list[DevelLikeBranch]` (default `[]`): Add a list of optional repositories and branches for ansible-core that will be treated similar to `devel`. This can be used for testing ansible-core features or bugfixes that are still under development. Please note that branches are usually deleted upon merging, so you have to remove them again from your `noxfile.py` to avoid CI breaking. This option can be specified as follows: `[](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-9-1) [sessions.ansible_test_sanity] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-9-2) add_devel_like_branches = [ [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-9-3) # To add the Data Tagging PR (https://github.com/ansible/ansible/pull/84621) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-9-4) # to CI, we can either use the special GitHub reference refs/pull/84621/head [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-9-5) # to refer to the PR's HEAD: [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-9-6) { branch = "refs/pull/84621/head" }, [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-9-7) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-9-8) # We can also just specify a branch as a string: [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-9-9) "refs/pull/84621/head", [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-9-10) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-9-11) # Alternatively, we can specify a GitHub repository and a branch in that [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-9-12) # repository. The Data Tagging PR is based on a branch in nitzmahone's fork [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-9-13) # of ansible/ansible: [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-9-14) { repository = "nitzmahone/ansible", branch = "data_tagging_219" }, [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-9-15) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-9-16) # We can also provide a two-element list with repository name and branch: [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-9-17) ["nitzmahone/ansible", "data_tagging_219"], [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-9-18) ]` * `min_version: Version | None` (default `None`): If specified, will only consider ansible-core versions with that version or higher. This can be a string of the form `"x.y"`, specifying a minor ansible-core x.y release. * `max_version: Version | None` (default `None`): If specified, will only consider ansible-core versions with that version or lower. This can be a string of the form `"x.y"`, specifying a minor ansible-core x.y release. * `except_versions: list[AnsibleCoreVersion]` (default `[]`): If specified, will ignore ansible-core versions in this list. The list elements can be strings of the form `"devel"`, `"milestone"`, and `"x.y"` where `x` and `y` are integers that specify a minor ansible-core x.y release. * `skip_tests: list[str]` (default `[]`): A list of tests to skip. * `allow_disabled: bool` (default `false`): Also run tests that are disabled by default. Corresponds to `ansible-test sanity`'s `--allow-disabled` option. Beware that these tests are disabled by default for a reason. * `enable_optional_errors: bool` (default `false`): Enable optional errors. Corresponds to `ansible-test sanity`'s `--enable-optional-errors` option. Beware that these errors are disabled by default for a reason. #### Example code[¶](https://docs.ansible.com/projects/antsibull-nox/config-file/#example-code_5 "Permanent link") This example is from `community.dns`. It runs all sanity tests for all supported ansible-core versions, including ansible-core's development branch. `[](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-10-1) [sessions.ansible_test_sanity] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-10-2) include_devel = true` ### Add all unit test sessions[¶](https://docs.ansible.com/projects/antsibull-nox/config-file/#add-all-unit-test-sessions "Permanent link") The `ansible-test unit` sessions are added with the `[sessions.ansible_test_units]` section in `antsibull-nox.toml`. Unit tests will always be run for all supported Python versions of the ansible-core version, using ansible-test's `default` container. The function supports the following parameters: * `default: bool` (default `false`): Whether the sessions should be made default. This means that when a user just runs `nox` without specifying sessions, these sessions will run. * `include_devel: bool` (default `false`): Whether ansible-core's `devel` branch should also be used. This is the development version of ansible-core and can break at any moment. This can be very helpful to prepare your collection against breaking changes in upcoming ansible-core versions early on. You should only run against it if you are ready for this. * `include_milestone: bool` (default `false`): Whether ansible-core's `milestone` branch should also be used. Note that the milestone branch is from the latest development version, but is updated only once for every ansible-core development phase at specific dates published in advance. * `add_devel_like_branches: list[DevelLikeBranch]` (default `[]`): Add a list of optional repositories and branches for ansible-core that will be treated similar to `devel`. This can be used for testing ansible-core features or bugfixes that are still under development. Please note that branches are usually deleted upon merging, so you have to remove them again from your `noxfile.py` to avoid CI breaking. This option can be specified as follows: `[](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-11-1) [sessions.ansible_test_units] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-11-2) add_devel_like_branches = [ [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-11-3) # To add the Data Tagging PR (https://github.com/ansible/ansible/pull/84621) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-11-4) # to CI, we can either use the special GitHub reference refs/pull/84621/head [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-11-5) # to refer to the PR's HEAD: [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-11-6) { branch = "refs/pull/84621/head" }, [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-11-7) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-11-8) # We can also just specify a branch as a string: [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-11-9) "refs/pull/84621/head", [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-11-10) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-11-11) # Alternatively, we can specify a GitHub repository and a branch in that [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-11-12) # repository. The Data Tagging PR is based on a branch in nitzmahone's fork [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-11-13) # of ansible/ansible: [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-11-14) { repository = "nitzmahone/ansible", branch = "data_tagging_219" }, [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-11-15) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-11-16) # We can also provide a two-element list with repository name and branch: [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-11-17) ["nitzmahone/ansible", "data_tagging_219"], [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-11-18) ]` * `min_version: Version | None` (default `None`): If specified, will only consider ansible-core versions with that version or higher. This can be a string of the form `"x.y"`, specifying a minor ansible-core x.y release. * `max_version: Version | None` (default `None`): If specified, will only consider ansible-core versions with that version or lower. This can be a string of the form `"x.y"`, specifying a minor ansible-core x.y release. * `except_versions: list[AnsibleCoreVersion]` (default `[]`): If specified, will ignore ansible-core versions in this list. The list elements can be strings of the form `"devel"`, `"milestone"`, and `"x.y"` where `x` and `y` are integers that specify a minor ansible-core x.y release. #### Example code[¶](https://docs.ansible.com/projects/antsibull-nox/config-file/#example-code_6 "Permanent link") This example is from `community.dns`. It runs all unit tests for all supported ansible-core versions, including ansible-core's development branch. `[](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-12-1) [sessions.ansible_test_units] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-12-2) include_devel = true` ### Add integration test sessions with the `default` container[¶](https://docs.ansible.com/projects/antsibull-nox/config-file/#add-integration-test-sessions-with-the-default-container "Permanent link") The `ansible-test integration --docker default` sessions are added with the `[sessions.ansible_test_integration_w_default_container]` section in `antsibull-nox.toml`. Sessions are added for all supported ansible-core versions. The tests will all be run using ansible-test's `default` container. It is possible to restrict the Python versions used to run the tests per ansible-core version. By default, `min_python_version` in the `[collection]` section is used to restrict the Python versions. * `default: bool` (default `false`): Whether the sessions should be made default. This means that when a user just runs `nox` without specifying sessions, these sessions will run. * `include_devel: bool` (default `false`): Whether ansible-core's `devel` branch should also be used. This is the development version of ansible-core and can break at any moment. This can be very helpful to prepare your collection against breaking changes in upcoming ansible-core versions early on. You should only run against it if you are ready for this. * `include_milestone: bool` (default `false`): Whether ansible-core's `milestone` branch should also be used. Note that the milestone branch is from the latest development version, but is updated only once for every ansible-core development phase at specific dates published in advance. * `add_devel_like_branches: list[DevelLikeBranch]` (default `[]`): Add a list of optional repositories and branches for ansible-core that will be treated similar to `devel`. This can be used for testing ansible-core features or bugfixes that are still under development. Please note that branches are usually deleted upon merging, so you have to remove them again from your `noxfile.py` to avoid CI breaking. This option can be specified as follows: `[](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-13-1) [sessions.ansible_test_integration_w_default_container] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-13-2) add_devel_like_branches = [ [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-13-3) # To add the Data Tagging PR (https://github.com/ansible/ansible/pull/84621) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-13-4) # to CI, we can either use the special GitHub reference refs/pull/84621/head [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-13-5) # to refer to the PR's HEAD: [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-13-6) { branch = "refs/pull/84621/head" }, [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-13-7) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-13-8) # We can also just specify a branch as a string: [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-13-9) "refs/pull/84621/head", [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-13-10) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-13-11) # Alternatively, we can specify a GitHub repository and a branch in that [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-13-12) # repository. The Data Tagging PR is based on a branch in nitzmahone's fork [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-13-13) # of ansible/ansible: [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-13-14) { repository = "nitzmahone/ansible", branch = "data_tagging_219" }, [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-13-15) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-13-16) # We can also provide a two-element list with repository name and branch: [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-13-17) ["nitzmahone/ansible", "data_tagging_219"], [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-13-18) ]` * `min_version: Version | None` (default `None`): If specified, will only consider ansible-core versions with that version or higher. This can be a string of the form `"x.y"`, specifying a minor ansible-core x.y release. * `max_version: Version | None` (default `None`): If specified, will only consider ansible-core versions with that version or lower. This can be a string of the form `"x.y"`, specifying a minor ansible-core x.y release. * `except_versions: list[AnsibleCoreVersion]` (default `[]`): If specified, will ignore ansible-core versions in this list. The list elements can be strings of the form `"devel"`, `"milestone"`, and `"x.y"` where `x` and `y` are integers that specify a minor ansible-core x.y release. * `core_python_versions: dict[AnsibleCoreVersion | str, list[Version]]` (default `{}`): Restrict the number of Python versions per ansible-core release. An empty list means that the ansible-core version will be skipped completely. If no restrictions are provided, all Python versions supported by this version of ansible-core are used; see `controller_python_versions_only` below for more details. Note that this setting is a new section `[sessions.ansible_test_integration_w_default_container.core_python_versions]`. The keys can be strings `"devel"`, `"milestone"`, and `"x.y"`, where ansible-core x.y is a minor ansible-core release; if `add_devel_like_branches`, the branch names appearing in `add_devel_like_branches` can also be specified. The values can be strings `"x.y"`, where Python x.y is a minor Python release. If this is set, `min_python_version` is ignored. * `controller_python_versions_only: bool` (default `false`): For ansible-core versions where `core_python_versions` does not provide a list of Python versions, usually all Python versions supported on the remote side are used. If this is set to `true`, only all Python versions uspported on the controller side are used. When set to `true`, this behaves the same as when `min_python_version` is set to `"controller"`, or when `min_python_version` is set to `"ansible-test-config"` and `tests/config.yml` has `modules.python_requires` set to `"controller"`. * `ansible_vars_from_env_vars: dict[str, str]` (default `{}`): If given, will create an integration test config file which for every `key=value` pair, contains an Ansible variable `key` with the value of the environment variable `value`. If the environment variable is not defined, the Ansible variable will not be defined either. If the same variable is defined in `ansible_vars`, the value defined in `ansible_vars` will be used. * `ansible_vars: dict[str, AnsibleValue]` (default `{}`): If given, will create an integration test config file which for every `key=value` pair. If the value is a string, number, or boolean, the value will be taken literally. If the value is a dictionary, it must be one of the following `type` entries: * `value`: specify a literal value. The dictionary can have the following fields: * `value: Any` (**required**): The value to store in the variable. * `value_template: str | None` (default `None`): If set, show this value insead of the real value in templates (see further below). * `env_var`: specify the name of an environment variable, whose value will be taken. The dictionary can have the following fields: * `name: str` (**required**): The name of the environment variable to use. * `fallback: Any` (default `""`): The value to store in the variable if the environment variable is not set. Will be ignored if `unset_if_not_set=true`. * `unset_if_not_set: bool` (default: `false`): Whether to not define the Ansible variable in case the environment variable is not set. * `value_template: str | None` (default `None`): If set, show this value insead of the real value in templates (see further below). #### Example code[¶](https://docs.ansible.com/projects/antsibull-nox/config-file/#example-code_7 "Permanent link") This example is from `community.dns`. `[](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-14-1) [sessions.ansible_test_integration_w_default_container] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-14-2) include_devel = true [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-14-3) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-14-4) [sessions.ansible_test_integration_w_default_container.core_python_versions] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-14-5) "2.14" = ["2.7", "3.5", "3.9"] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-14-6) "2.15" = ["3.7"] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-14-7) "2.16" = ["2.7", "3.6", "3.11"] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-14-8) "2.17" = ["3.7", "3.12"] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-14-9) "2.18" = ["3.8", "3.13"]` The following example is from `felixfontein.acme`. `[](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-15-1) [sessions.ansible_test_integration_w_default_container] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-15-2) include_devel = true [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-15-3) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-15-4) [sessions.ansible_test_integration_w_default_container.ansible_vars_from_env_vars] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-15-5) "github_token" = "GITHUB_TOKEN"` It passes the `GITHUB_TOKEN` environment variable on as `github_token`. This allows to download files from other GitHub repositories while avoiding strict rate limiting: `[](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-16-1) - name: Download SOPS test GPG key [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-16-2) ansible.builtin.get_url: [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-16-3) headers: [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-16-4) Authorization: "{{ ('Bearer ' ~ github_token) if github_token is defined and github_token else '' }}" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-16-5) url: https://raw.githubusercontent.com/getsops/sops/master/pgp/sops_functional_tests_key.asc [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-16-6) dest: "{{ _tempfile.path }}"` ### Add integration test sessions by explicitly listing all sessions[¶](https://docs.ansible.com/projects/antsibull-nox/config-file/#add-integration-test-sessions-by-explicitly-listing-all-sessions "Permanent link") The `ansible-test integration --docker` and `ansible-test integration --remote` sessions are added with the `[sessions.ansible_test_integration]` section in `antsibull-nox.toml`. You explicitly have to list all sessions in `antsibull-nox.toml`. * `default: bool` (default `false`): Whether the sessions should be made default. This means that when a user just runs `nox` without specifying sessions, these sessions will run. * `ansible_vars: dict[str, AnsibleValue]` (default `{}`): If given, will create an integration test config file which for every `key=value` pair. If the value is a string, number, or boolean, the value will be taken literally. If the value is a dictionary, it must be one of the following `type` entries: Note that this can also be specified in individual sessions. Variables defined there with the same name override the values defined here. * `value`: specify a literal value. The dictionary can have the following fields: * `value: Any` (**required**): The value to store in the variable. * `env_var`: specify the name of an environment variable, whose value will be taken. The dictionary can have the following fields: * `name: str` (**required**): The name of the environment variable to use. * `fallback: Any` (default `""`): The value to store in the variable if the environment variable is not set. Will be ignored if `unset_if_not_set=true`. * `unset_if_not_set: bool` (default: `false`): Whether to not define the Ansible variable in case the environment variable is not set. * `session_name_template: str` (default: `"ansible-test-integration-{target_dash}{ansible_core}{dash_docker_short}{dash_remote}{dash_python_version}"`) The template to use for the session name. Formatting will be done with Python's `str.format()`. See below for the available variables. This can also be overriden for specific sessions. * `display_name_template: str` (default: `"Ⓐ{ansible_core}{plus_py_python_version}{plus_docker_short}{plus_remote}"`) The template to use for the session's display name that is used in CI systems. Formatting will be done with Python's `str.format()`. See below for the available variables. This can also be overriden for specific sessions. * `description_template: str` (default: `"Run integration tests with ansible-core {ansible_core}, {docker_short}{remote}"`) The template to use for the session's description. Formatting will be done with Python's `str.format()`. See below for the available variables. This can also be overriden for specific sessions. * `tags: list[str]` (default: `[]`): A list of tags to add to all sessions. These tags can be used when filtering sessions for CI matrix generation. * `sessions: list[SessionAnsibleTestIntegrationSession]` (default: `[]`) Defines session templates for ansible-test integration test sessions. Every session template is an object and will result in one or more sessions. It should be defined in a new section `[[sessions.ansible_test_integration.sessions]]`. (See [Array of Tables](https://toml.io/en/v1.0.0#array-of-tables) in the TOML Specification.) Session templates have two kind of properties. The first kind specifies one or more sessions by providing one or multiple values for a parameter. If multiple parameters are provided, one session is created for every possible combination of these parameters. These properties are the following: * `ansible_core: AnsibleCoreVersion | list[AnsibleCoreVersion]` (**required**) The ansible-core version to use. * `docker: str | list[str] | None` (default: `None`) The Docker image to run the tests in. Exactly one of `docker` and `remote` must be provided. * `remote: str | list[str] | None` (default: `None`) The remote VM to run the tests in. Note that ansible-test's `--remote` feature uses Ansible's CI infrastructure and requires an account. Exactly one of `docker` and `remote` must be provided. * `python_version: Version | list[Version] | None` (default: `None`) The Python version to run the tests with. This should only be provided when using the `default` Docker image, or when using custom Docker images that ansible-test does not know, or when a Docker image or remote VM offers more than one possible Python version to use. * `target: str | list[str] | None` (default: `None`) The target to run. This can be a string like `shippable/posix/group3/` (as used by the ansible/ansible CI), `azp/posix/1/` (as used in the community.general CI), or `gha/main/` (as used in the community.sops CI). Note that a trailing slash indicates a _group_ of targets. Targets are associated to tests in the `aliases` file. * `gha_container: str | list[str] | None` (default: `None`) The `gha-container` variable. This is not used directly, but passed on through the `matrix-generator` session to the shared GitHub Actions workflow, for example. When the shared workflow is used, you can for example use `ubuntu-24.04-arm` to run tests in an ARM VM instead of the default `ubuntu-latest` x86 VM. The other properties allow to define common things for all sessions generated from this template. * `devel_like_branch: DevelLikeBranch | None` (default: `None`) This can only be used if `ansible_core == "devel"`. In that case, it allows to specify another branch from potentially another repository than `github.com/ansible/ansible` to use. This can be used for testing ansible-core features or bugfixes that are still under development. Please note that branches are usually deleted upon merging, so you have to remove them again from your `noxfile.py` to avoid CI breaking. `[](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-17-1) # To add the Data Tagging PR (https://github.com/ansible/ansible/pull/84621) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-17-2) # to CI, we can either use the special GitHub reference refs/pull/84621/head [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-17-3) # to refer to the PR's HEAD: [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-17-4) devel_like_branch = { branch = "refs/pull/84621/head" } [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-17-5) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-17-6) # We can also just specify a branch as a string: [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-17-7) devel_like_branch = "refs/pull/84621/head" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-17-8) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-17-9) # Alternatively, we can specify a GitHub repository and a branch in that [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-17-10) # repository. The Data Tagging PR is based on a branch in nitzmahone's fork [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-17-11) # of ansible/ansible: [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-17-12) devel_like_branch = { repository = "nitzmahone/ansible", branch = "data_tagging_219" } [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-17-13) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-17-14) # We can also provide a two-element list with repository name and branch: [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-17-15) devel_like_branch = ["nitzmahone/ansible", "data_tagging_219"]` * `ansible_vars: dict[str, AnsibleValueField]` (default: `{} If given, will create an integration test config file which for every`key=value`pair. A key here will override a key of the same name in`\[sessions.ansible\_test\_integration.ansible\_vars\]`. See the documentation of`\[sessions.ansible\_test\_integration.ansible\_vars\]\` for how to use this. * `session_name_template: str | None` (default: `None`) If given, will overwrite `[sessions.ansible_test_integration.session_name_template]`. * `display_name_template: str | None` (default: `None`) If given, will overwrite `[sessions.ansible_test_integration.display_name_template]`. * `description_template: str | None` (default: `None`) If given, will overwrite `[sessions.ansible_test_integration.description_template]`. * `tags: list[str]` (default: `[]`): A list of tags to add to all sessions for this session template. These tags can be used when filtering sessions for CI matrix generation. * `groups: list[SessionAnsibleTestIntegrationGroup]` (default: `[]`) Defines groups of session templates for ansible-test integration test sessions. Groups can be used to group similar templates together by sharing some definitions. They also allow to create a dedicated meta session that will run all sessions created from this group. Every group is an object and will result in one or more sessions. It should be defined in a new section `[[sessions.ansible_test_integration.groups]]`. (See [Array of Tables](https://toml.io/en/v1.0.0#array-of-tables) in the TOML Specification.) Groups have the following properties: * `session_name: str | None` (default: `None`) If specified, a meta session will be created that allows to run all sessions defined within this group. * `description: str | None` (default: `None`) If `session_name` is specified, will provide the description for the meta session. If `description` is not specified, a generic description will be used. * `docker: str | list[str] | None` (default: `None`) Allows to provide one or more Docker images. This can be overridden in each session template. * `remote: str | list[str] | None` (default: `None`) Allows to provide one or more remote VM name. This can be overridden in each session template. * `python_version: Version | list[Version] | None` (default: `None`) Allows to provide one or more Python versions. This can be overridden in each session template. * `target: str | list[str] | None` (default: `None`) Allows to provide one or more target names. This can be overridden in each session template. * `gha_container: str | list[str] | None` (default: `None`) Allows to provide one or more GHA container names. This can be overridden in each session template. * `ansible_vars: dict[str, AnsibleValueField]` (default: `{}`) Allows to provide Ansible variables. This will override `[sessions.ansible_test_integration.ansible_vars]`, and will be overridden by `[sessions.ansible_test_integration.groups.sessions.ansible_vars]`. * `sessions: list[SessionAnsibleTestIntegrationSession]` (default: `[]`) A list of session templates. Uses the exact same format as `[sessions.ansible_test_integration.sessions]`. * `session_name_template: str | None` (default: `None`) Allows to provide a session name template that overrides the global one `[sessions.ansible_test_integration.session_name_template]`. This can be overridden in each session template. * `display_name_template: str | None` (default: `None`) Allows to provide a session's display name template that overrides the global one `[sessions.ansible_test_integration.display_name_template]`. This can be overridden in each session template. * `description_template: str | None` (default: `None`) Allows to provide a session's description template that overrides the global one `[sessions.ansible_test_integration.description_template]`. This can be overridden in each session template. * `tags: list[str]` (default: `[]`): A list of tags to add to all sessions for this group template. These tags can be used when filtering sessions for CI matrix generation. #### Templating[¶](https://docs.ansible.com/projects/antsibull-nox/config-file/#templating "Permanent link") The session name, display name, and description of a session are templated with Python's `str.format()`. A list of variables that can be used is generated from a base list of variables: * `ansible_core`: The ansible-core version. * `docker`: The Docker image name, or empty if not provided. * `docker_short`: A shortened Docker image name, or empty if not provided. The prefixes `"quay.io/ansible-community/test-image:"` and `"localhost/test-image:"` will be removed from Docker images. * `remote`: The remote VM name, or empty if not provided. * `python_version`: The Python version, or empty if not provided. * `py_python_version`: The Python version prefixed by `"py"`, or empty if not provided. * `target`: The target, or empty if not provided. * `target_dashized`: The target with `/` replaced by `-`, and trailing `-` removed. Empty if no target is provided. * `gha_container`: The value of `gha_container`, or empty if not provided. * `gha_arm`: `"ARM"` if `gha_container` references to an ARM image. * `gha_arm_lower`: `arm` if `gha_container` references to an ARM image. Additionally, every variable defined for the session that is explicitly provided, or that has `template_value` set, is made available under the variable's name. For a variable name `var` listed above, the following variables are also defined: * `var_dash`: The content of `var` followed by a dash (`-`) if `var` is not empty, or an empty string otherwise. * `dash_var`: The content of `var` preceeded by a dash (`-`) if `var` is not empty, or an empty string otherwise. * `var_plus`: The content of `var` followed by a plus sign (`+`) if `var` is not empty, or an empty string otherwise. * `plus_var`: The content of `var` preceeded by a plus sign (`+`) if `var` is not empty, or an empty string otherwise. * `var_comma`: The content of `var` followed by a comma and space (`,`) if `var` is not empty, or an empty string otherwise. * `comma_var`: The content of `var` preceeded by a comma and space (`,`) if `var` is not empty, or an empty string otherwise. #### Example code[¶](https://docs.ansible.com/projects/antsibull-nox/config-file/#example-code_8 "Permanent link") This example is a subset of the sessions defined for `community.sops`. `[](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-1) [sessions.ansible_test_integration] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-2) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-3) [sessions.ansible_test_integration.ansible_vars] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-4) github_token = { type = "env", name = "GITHUB_TOKEN", unset_if_not_set = true } [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-5) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-6) [[sessions.ansible_test_integration.groups]] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-7) session_name = "ansible-test-integration-main" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-8) description = "Meta-session for all ansible-test-integration-main-* sessions." [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-9) session_name_template = "ansible-test-integration-main-{ansible_core}{dash_docker_short}{dash_override_sops_version}{dash_gha_arm_lower}" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-10) display_name_template = "main+Ⓐ{ansible_core}+SOPS-{override_sops_version}{plus_docker_short}{plus_py_python_version}{plus_gha_arm}" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-11) description_template = "Run main integration tests with ansible-core {ansible_core}, {docker_short}, SOPS {override_sops_version}{comma_gha_arm}" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-12) target = "gha/main/" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-13) gha_container = "ubuntu-latest" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-14) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-15) [[sessions.ansible_test_integration.groups.sessions]] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-16) ansible_core = "devel" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-17) docker = ["ubuntu2204", "ubuntu2404", "fedora42"] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-18) ansible_vars = { override_sops_version = "3.5.0" } [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-19) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-20) [[sessions.ansible_test_integration.groups.sessions]] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-21) ansible_core = "2.15" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-22) docker = "ubuntu2004" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-23) ansible_vars = { override_sops_version = "3.10.0" } [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-24) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-25) [[sessions.ansible_test_integration.groups.sessions]] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-26) ansible_core = "2.15" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-27) docker = "quay.io/ansible-community/test-image:debian-bullseye" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-28) python_version = "3.9" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-29) ansible_vars = { override_sops_version = "latest" } [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-30) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-31) [[sessions.ansible_test_integration.groups.sessions]] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-32) ansible_core = "devel" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-33) docker = "ubuntu2404" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-34) gha_container = "ubuntu-24.04-arm" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-35) ansible_vars = { override_sops_version = "latest" } [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-36) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-37) [[sessions.ansible_test_integration.groups]] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-38) session_name = "ansible-test-integration-install-1" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-39) description = "Meta-session for all ansible-test-integration-install-1-* sessions." [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-40) session_name_template = "ansible-test-integration-install-1-{ansible_core}{dash_docker_short}{dash_gha_arm_lower}" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-41) display_name_template = "install-1+Ⓐ{ansible_core}{plus_docker_short}{plus_py_python_version}{plus_gha_arm}" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-42) description_template = "Run install role integration tests (specific SOPS version) with ansible-core {ansible_core}, {docker_short}{comma_gha_arm}" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-43) target = "gha/install/1/" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-44) gha_container = "ubuntu-latest" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-45) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-46) [[sessions.ansible_test_integration.groups.sessions]] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-47) ansible_core = "2.17" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-48) docker = ["ubuntu2204", "fedora39"] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-49) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-50) [[sessions.ansible_test_integration.groups.sessions]] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-51) ansible_core = "devel" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-52) docker = "ubuntu2404" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-53) gha_container = "ubuntu-24.04-arm" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-54) ansible_vars = { github_latest_detection = "auto" } [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-55) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-56) [[sessions.ansible_test_integration.groups]] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-57) session_name = "ansible-test-integration-install-2" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-58) description = "Meta-session for all ansible-test-integration-install-2-* sessions." [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-59) session_name_template = "ansible-test-integration-install-2-{ansible_core}{dash_docker_short}{dash_gha_arm_lower}" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-60) display_name_template = "install-2+Ⓐ{ansible_core}{plus_docker_short}{plus_py_python_version}{plus_gha_arm}" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-61) description_template = "Run install role integration tests (localhost vs. remote host) with ansible-core {ansible_core}, {docker_short}{comma_gha_arm}" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-62) target = "gha/install/2/" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-63) gha_container = "ubuntu-latest" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-64) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-65) [[sessions.ansible_test_integration.groups.sessions]] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-66) ansible_core = "devel" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-67) docker = "ubuntu2204" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-68) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-69) [[sessions.ansible_test_integration.groups.sessions]] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-70) ansible_core = "devel" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-71) docker = "ubuntu2204" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-72) gha_container = "ubuntu-24.04-arm" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-73) ansible_vars = { github_latest_detection = "auto" } [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-74) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-75) [[sessions.ansible_test_integration.groups]] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-76) session_name = "ansible-test-integration-install-3" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-77) description = "Meta-session for all ansible-test-integration-install-3-* sessions." [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-78) session_name_template = "ansible-test-integration-install-3-{ansible_core}{dash_docker_short}{dash_gha_arm_lower}" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-79) display_name_template = "install-3+Ⓐ{ansible_core}{plus_docker_short}{plus_py_python_version}{plus_gha_arm}" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-80) description_template = "Run install role integration tests (latest SOPS version) with ansible-core {ansible_core}, {docker_short}{comma_gha_arm}" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-81) target = "gha/install/3/" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-82) gha_container = "ubuntu-latest" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-83) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-84) [[sessions.ansible_test_integration.groups.sessions]] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-85) ansible_core = "devel" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-86) docker = "quay.io/ansible-community/test-image:archlinux" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-87) python_version = "3.13" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-88) ansible_vars = { github_latest_detection = "auto" } [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-89) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-90) [[sessions.ansible_test_integration.groups.sessions]] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-91) ansible_core = "devel" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-92) docker = "ubuntu2204" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-93) ansible_vars = { github_latest_detection = "api" } [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-94) [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-95) [[sessions.ansible_test_integration.groups.sessions]] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-96) ansible_core = "devel" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-97) docker = "ubuntu2404" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-18-98) ansible_vars = { github_latest_detection = "latest-release" }` Run ansible-lint[¶](https://docs.ansible.com/projects/antsibull-nox/config-file/#run-ansible-lint "Permanent link") -------------------------------------------------------------------------------------------------------------------- The [ansible-lint](https://ansible.readthedocs.io/projects/lint/) session is added with the `[sessions.ansible_lint]` section in `antsibull-nox.toml`. The added session is called `ansible-lint`. The section can contain the following configurations: * `default: bool` (default `true`): Whether the `ansible-lint` session should be made default. This means that when a user just runs `nox` without specifying sessions, this session will run. * `ansible_lint_package: PackageType` (default `"ansible-lint"`): The package to install for `ansible-lint` in this session. You can specify a value here to add restrictions to the `ansible-lint` version, or to pin the version, or to install the package from a local repository. * `additional_requirements_files: list[str]` (default `[]`): Additional list of `requirements.yml` files for collections to install before running `ansible-lint --offline`. Note that antsibull-nox knows about [the locations ansible-lint looks for `requirements.yml` in](https://github.com/ansible/ansible-lint/blob/main/src/ansiblelint/rules/syntax_check.md#syntax-checkunknown-module) and already makes sure that collections from these requirement files are present. * `strict: bool` (default `false`): Whether the `--strict` parameter should be passed to ansible-lint. This treats warnings as errors. It is a good idea to add `[](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-19-1) exclude_paths: [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-19-2) - .nox/` to your ansible-lint configuration file. Otherwise ansible-lint might try to lint collection dependencies that antsibull-nox installed. ### Example code[¶](https://docs.ansible.com/projects/antsibull-nox/config-file/#example-code_9 "Permanent link") This example is from `felixfontein.acme`. It simply runs `ansible-lint`. `[](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-20-1) [sessions.ansible_lint]` Execution environment check[¶](https://docs.ansible.com/projects/antsibull-nox/config-file/#execution-environment-check "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------------ antsibull-nox allows you to test your collection against an execution environment (EE). The `ee-check` meta session is added with the `[sessions.ee_check]` section or `[[sessions.ee_check.execution_environments]]` sections (one for every EE) in `antsibull-nox.toml`. The `[sessions.ee_check]` section is optional and accepts the following options: * `default: bool` (default `false`): Whether the `ee-check` session should be made default. This means that when a user just runs `nox` without specifying sessions, this session will run. * `ansible_builder_package: PackageType` (default `"ansible-builder"`): The package to install for `ansible-builder` in this session. You can specify a value here to add restrictions to the `ansible-builder` version, or to pin the version, or to install the package from a local repository. * `ansible_core_package: PackageType | None` (default `None`): The package to install for `ansible-core` in this session. Note that `ansible-core` is a dependency of `ansible-runner`, so if not specified explicitly here it will still be installed. You can specify a value here to add restrictions to the `ansible-core` version, or to pin the version, or to install the package from a local repository. * `ansible_navigator_package: PackageType` (default `"ansible-navigator"`): The package to install for `ansible-navigator` in this session. You can specify a value here to add restrictions to the `ansible-navigator` version, or to pin the version, or to install the package from a local repository. * `execution_environments: list[ExecutionEnvironmentConfig]` (**required**): List of execution environment configs. The configurations come with information on how to build the execution environment (EE) and in which ways to test them. Every execution environment config is an object and will result in its own session. (The `ee-check` meta session executes all these sessions.) It should be defined in a new section `[[sessions.ee_check.execution_environments]]`. (See [Array of Tables](https://toml.io/en/v1.0.0#array-of-tables) in the TOML Specification.) Every execution environment config has the following properties: * `name: str` (**required**): Specifies a unique name for the `ee-check` session. * `description: str | None` (default `None`): Adds a description for the `ee-check` session. * `version: 3` (default `3`): Configures the schema version for the EE definition. * `base_image_name: str` (default `"registry.fedoraproject.org/fedora-toolbox:latest"`): Specifies the base image to use when building the EE. We strongly recommend to always provide the base image explicitly (here or through `config`), and not to rely on this default. * `ansible_core_source: "package_pip" | "package_system"` (default `"package_pip"`): Configures the source for installing the `ansible-core` package. when the `ansible_core_package` option is used. * `ansible_core_package: PackageType | None` (default `None`): Specifies the name of the `ansible-core` package. * `ansible_runner_source: "package_pip" | "package_system"` (default `"package_pip"`): Configures the source for installing the `ansible-runner` package when the `ansible_runner_package` option is used. * `ansible_runner_package: PackageType | None` (default `None`): Specifies the name of the `ansible-runner` package. * `system_packages: list[str]` (default `"[]"`): Specifies a list of system packages to build into the EE. * `python_packages: list[str]` (default `"[]"`): Specifies a list of Python packages to build into the EE. * `python_interpreter_package: PackageType | None`(default `None`): Defines the Python system package name for the EE. * `python_path: str | None`(default `None`): Specifies the path to the Python interpreter. * `config: dict[str, Any]` (default `{}`): Allows explicit configuration of an EE definition. If `config` is used, the other options to specify values in the EE definition can still be used, but every value can only come from one source. If this is violated, an error will be produced. Warning The key `dependencies.galaxy` will always be overridden. Note antsibull-nox does not check the EE definition syntax. * `test_playbooks: list[str]` (**required**): Specifies a list of playbooks that test the collection against the EE. * `runtime_environment: dict[str, str]` (default `{}`): Specify environment variables that will be set when the playbooks are executed. This will be passed through `--set-environment-variable` to `ansible-navigator`. * `runtime_container_options: list[str]` (default `[]`): Specify additional options to pass to the container runtime (Podman or Docker) when the playbooks are executed. This will be passed through `--container-options` to `ansible-navigator`. * `runtime_extra_vars: dict[str, str]` (default `{}`): Specify extra variables that will be set when the playbooks are executed. This will be passed through `-e` to `ansible-navigator`. For more information about these options, see the [Execution environment definition](https://ansible.readthedocs.io/projects/builder/en/latest/definition/) documentation for Ansible Builder. Note A container engine (Docker or Podman) needs to be installed for this session. Information on which container engine is chosen by antsibull-nox can be found [on the troubleshooting page](https://docs.ansible.com/projects/antsibull-nox/troubleshooting/) . ### Example TOML definition[¶](https://docs.ansible.com/projects/antsibull-nox/config-file/#example-toml-definition "Permanent link") The following example shows a minimal EE check definition: `[](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-21-1) [[sessions.ee_check.execution_environments]] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-21-2) name = "minimal_ee" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-21-3) test_playbooks = ["tests/ee/all.yml"] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-21-4) base_image_name = "registry.fedoraproject.org/fedora-toolbox:latest" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-21-5) ansible_core_package = "ansible-core" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-21-6) ansible_runner_package = "ansible-runner"` Note While the `base_image_name` option is optional, we strongly recommend to provide it explicitly, or alternatively provide the appropriate base image in `config`. Note The `ansible_core_package` and `ansible_runner_package` options are necessary as the default base image `registry.fedoraproject.org/fedora-toolbox:latest` of antsibull-nox does not contain ansible-core and ansible-runner. ansible-builder will refuse to create the EE without both of these packages present. The following example shows a full EE check definition: `[](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-22-1) [[sessions.ee_check.execution_environments]] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-22-2) name = "fedora-toolbox" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-22-3) description = "Testing EE builds with the fedora toolbox" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-22-4) test_playbooks = ["tests/ee/all.yml"] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-22-5) base_image_name = "registry.fedoraproject.org/fedora-toolbox:latest" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-22-6) ansible_core_package = "ansible-core" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-22-7) ansible_core_source = "package_pip" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-22-8) ansible_runner_package = "ansible-runner" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-22-9) ansible_runner_source = "package_pip" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-22-10) system_packages = ["git", "curl"] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-22-11) python_packages = ["jinja2", "pyyaml", "requests"] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-22-12) python_interpreter_package = "python3" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-22-13) python_path = "/usr/bin/python3"` The following example shows an explicit configuration of an EE: `[](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-23-1) [[sessions.ee_check.execution_environments]] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-23-2) name = "fedora-toolbox" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-23-3) description = "Testing EE builds with the fedora toolbox" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-23-4) test_playbooks = ["tests/ee/all.yml"] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-23-5) config.images.base_image.name = "registry.fedoraproject.org/fedora-toolbox:latest" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-23-6) config.dependencies.ansible_core.package_pip = "ansible-core" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-23-7) config.dependencies.ansible_runner.package_pip = "ansible-runner" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-23-8) config.dependencies.system = [ [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-23-9) "git", [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-23-10) "curl", [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-23-11) ] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-23-12) config.dependencies.python = [ [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-23-13) "jinja2", [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-23-14) "pyyaml", [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-23-15) "requests", [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-23-16) ] [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-23-17) config.dependencies.python_interpreter.package_system = "python3" [](https://docs.ansible.com/projects/antsibull-nox/config-file/#__codelineno-23-18) config.dependencies.python_interpreter.python_path = "/usr/bin/python3"` --- # Glossary — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * Glossary * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/reference_appendices/glossary.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Glossary[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#glossary "Link to this heading") ================================================================================================================================= The following is a list (and re-explanation) of term definitions used elsewhere in the Ansible documentation. Consult the documentation home page for the full documentation and to see the terms in context, but this should be a good resource to check your knowledge of Ansible’s components and understand how they fit together. It is something you might wish to read for review or when a term comes up on the [Ansible Forum](https://docs.ansible.com/projects/ansible/latest/community/communication.html#ansible-forum) . Action[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Action "Link to this term") An action is a part of a task that specifies which of the modules to run and which arguments to pass to that module. Each task can have only one action, but it may also have other parameters. Ad Hoc[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Ad-Hoc "Link to this term") Refers to running Ansible to perform some quick command, using **/usr/bin/ansible**, rather than the [orchestration](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Orchestration) language, which is **/usr/bin/ansible-playbook**. An example of an ad hoc command might be rebooting 50 machines in your infrastructure. Anything you can do ad hoc can be accomplished by writing a [playbook](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Playbooks) and playbooks can also glue several other operations together. Ansible (the package)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Ansible-the-package "Link to this term") A software package (Python, deb, rpm, and so on) that contains ansible-core and a select group of collections. Playbooks that worked with Ansible 2.9 should still work with the Ansible 2.10 package. See the `ansible-.build` file in the release-specific directory at [ansible-build-data](https://github.com/ansible-community/ansible-build-data) for a list of collections included in Ansible, as well as the included `ansible-core` version. ansible-base[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-ansible-base "Link to this term") Used only for 2.10. The installable package (RPM/Python/Deb package) generated from the [ansible/ansible repository](https://github.com/ansible/ansible) . See `ansible-core`. ansible-core[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-ansible-core "Link to this term") Name used starting with 2.11. The installable package (RPM/Python/Deb package) generated from the [ansible/ansible repository](https://github.com/ansible/ansible) . Contains the command-line tools and the code for basic features and functions, such as copying module code to managed nodes. The `ansible-core` package includes a few modules and plugins and allows you to add others by installing collections. Ansible Galaxy[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Ansible-Galaxy "Link to this term") An [online distribution server](https://galaxy.ansible.com/ui/) for finding and sharing Ansible community content, sometimes referred to as community Galaxy. Also, the command-line utility that lets users install individual Ansible Collections, for example `ansible-galaxy collection install community.crypto`. Async[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Async "Link to this term") Refers to a task that is configured to run in the background rather than waiting for completion. If you have a long process that would run longer than the SSH timeout, it would make sense to launch that task in async mode. Async modes can poll for completion every so many seconds or can be configured to “fire and forget”, in which case Ansible will not even check on the task again; it will just kick it off and proceed to future steps. Async modes work with both **/usr/bin/ansible** and **/usr/bin/ansible-playbook**. Callback Plugin[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Callback-Plugin "Link to this term") Refers to some user-written code that can intercept results from Ansible and do something with them. Some supplied examples in the GitHub project perform custom logging, send email, or even play sound effects. Check Mode[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Check-Mode "Link to this term") Refers to running Ansible with the `--check` option, which does not make any changes on the remote systems, but only outputs the changes that might occur if the command ran without this flag. This is analogous to so-called “dry run” modes in other systems, though the user should be warned that this does not take into account unexpected command failures or cascade effects (which is true of similar modes in other systems). Use this to get an idea of what might happen, but do not substitute it for a good staging environment. Collection[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Collection "Link to this term") A packaging format for bundling and distributing Ansible content, including plugins, roles, modules, and more. Collections release independent of other collections or `ansible-core` so features can be available sooner to users. Some collections are packaged with Ansible (version 2.10 or later). You can install other collections (or other versions of collections) with `ansible-galaxy collection install `. Collection name[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Collection-name "Link to this term") The second part of a Fully Qualified Collection Name. The collection name divides the collection namespace and usually reflects the function of the collection content. For example, the `cisco` namespace might contain `cisco.ios`, `cisco.aci`, and `cisco.nxos`, with content for managing the different network devices maintained by Cisco. community.general (collection)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-community.general-collection "Link to this term") A special collection managed by the Ansible Community Team containing all the modules and plugins which shipped in Ansible 2.9 that do not have their own dedicated Collection. See [community.general](https://galaxy.ansible.com/community/general) on Galaxy. community.network (collection)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-community.network-collection "Link to this term") Similar to `community.general`, focusing on network content. [community.network](https://galaxy.ansible.com/community/network) on Galaxy. Connection Plugin[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Connection-Plugin "Link to this term") By default, Ansible talks to remote machines through pluggable libraries. Ansible uses native OpenSSH ([SSH (Native)](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-SSH-Native) ) or a Python implementation called [paramiko](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-paramiko) . OpenSSH is preferred if you are using a recent version, and also enables some features like Kerberos and jump hosts. This is covered in the [getting started section](https://docs.ansible.com/projects/ansible/2.9/user_guide/intro_getting_started.html#remote-connection-information "(in Ansible v2.9)") . There are also other connection types like `accelerate` mode, which must be bootstrapped over one of the SSH-based connection types but is very fast, and local mode, which acts on the local system. Users can also write their own connection plugins. Conditionals[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Conditionals "Link to this term") A conditional is an expression that evaluates to true or false that decides whether a given task is executed on a given machine or not. Ansible’s conditionals are powered by the ‘when’ statement, which are discussed in the [Working with playbooks](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks.html#working-with-playbooks) . Declarative[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Declarative "Link to this term") An approach to achieving a task that uses a description of the final state rather than a description of the sequence of steps necessary to achieve that state. For a real world example, a declarative specification of a task would be: “put me in California”. Depending on your current location, the sequence of steps to get you to California may vary, and if you are already in California, nothing at all needs to be done. Ansible’s Resources are declarative; it figures out the steps needed to achieve the final state. It also lets you know whether or not any steps needed to be taken to get to the final state. Diff Mode[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Diff-Mode "Link to this term") A `--diff` flag can be passed to Ansible to show what changed on modules that support it. You can combine it with `--check` to get a good ‘dry run’. File diffs are normally in unified diff format. Distribution server[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Distribution-server "Link to this term") A server, such as Ansible Galaxy or Red Hat Automation Hub where you can distribute your collections and allow others to access these collections. See [Distributing collections](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_collections_distributing.html#distributing-collections) for a list of distribution server types. Some Ansible features are only available on certain distribution servers. Executor[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Executor "Link to this term") A core software component of Ansible that is the power behind **/usr/bin/ansible** directly – and corresponds to the invocation of each task in a [playbook](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Playbooks) . The Executor is something Ansible developers may talk about, but it is not really user land vocabulary. Facts[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Facts "Link to this term") Facts are simply things that are discovered about remote nodes. While they can be used in [playbooks](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Playbooks) and templates just like variables, facts are things that are inferred, rather than set. Facts are automatically discovered by Ansible when running plays by executing the internal [setup module](https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/setup_module.html#setup-module) on the remote nodes. You never have to call the setup module explicitly, it just runs, but it can be disabled to save time if it is not needed or you can tell ansible to collect only a subset of the full facts through the `gather_subset:` option. For the convenience of users who are switching from other configuration management systems, the fact module will also pull in facts from the **ohai** and **facter** tools if they are installed. These are fact libraries from Chef and Puppet, respectively. (These may also be disabled through `gather_subset:`) Filter Plugin[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Filter-Plugin "Link to this term") A filter plugin is something that most users will never need to understand. These allow for the creation of new [Jinja2](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Jinja2) filters, which are more or less only of use to people who know what Jinja2 filters are. If you need them, you can learn how to write them in the [API docs section](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_plugins.html#developing-filter-plugins) . Forks[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Forks "Link to this term") Ansible talks to remote nodes in parallel and the level of parallelism can be set either by passing `--forks` or editing the default in a configuration file. The default is a very conservative five (5) forks, though if you have a lot of RAM, you can easily set this to a value like 50 for increased parallelism. Fully Qualified Collection Name (FQCN)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Fully-Qualified-Collection-Name-FQCN "Link to this term") The full definition of a module, plugin, or role hosted within a collection, in the form . Allows a Playbook to refer to a specific module or plugin from a specific source in an unambiguous manner, for example, `community.grafana.grafana_dashboard`. The FQCN is required when you want to specify the exact source of a plugin. For example, if multiple collections contain a module plugin called `user`, the FQCN specifies which one to use for a given task. When you have multiple collections installed, the FQCN is always the explicit and authoritative indicator of which collection to search for the correct plugin for each task. Gather Facts (Boolean)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Gather-Facts-Boolean "Link to this term") [Facts](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Facts) are mentioned above. Sometimes when running a multi-play [playbook](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Playbooks) , it is desirable to have some plays that don’t bother with fact computation if they aren’t going to need to utilize any of these values. Setting `gather_facts: False` on a playbook allows this implicit fact gathering to be skipped. Globbing[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Globbing "Link to this term") Globbing is a way to select several hosts based on wildcards, rather than the name of the host specifically, or the name of the group they are in. For example, it is possible to select `ww*` to match all hosts starting with `www`. This concept is pulled directly from **Func**, one of Michael DeHaan’s (an Ansible Founder) earlier projects. In addition to basic globbing, various set operations are also possible, such as ‘hosts in this group and not in another group’, and so on. Group[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Group "Link to this term") A group consists of several hosts assigned to a pool that can be conveniently targeted together, as well as given variables that they share in common. Group Vars[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Group-Vars "Link to this term") The `group_vars/` files are files that live in a directory alongside an inventory file, with an optional file name named after each group. This is a convenient place to put variables that are provided to a given group, especially complex data structures, so that these variables do not have to be embedded in the [inventory](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Inventory) file or [playbook](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Playbooks) . Handlers[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Handlers "Link to this term") Handlers are just like regular tasks in an Ansible [playbook](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Playbooks) (see [Tasks](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Tasks) ) but are only run if the Task contains a `notify` keyword and also indicates that it changed something. For example, if a config file is changed, then the task referencing the config file templating operation may notify a service restart handler. This means services can be bounced only if they need to be restarted. Handlers can be used for things other than service restarts, but service restarts are the most common usage. Host[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Host "Link to this term") A host is simply a remote machine that Ansible manages. They can have individual variables assigned to them, and can also be organized in groups. All hosts have a name they can be reached at (which is either an IP address or a domain name) and, optionally, a port number, if they are not to be accessed on the default SSH port. Host Specifier[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Host-Specifier "Link to this term") Each [Play](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Plays) in Ansible maps a series of [tasks](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Tasks) (which define the role, purpose, or orders of a system) to a set of systems. This `hosts:` keyword in each play is often called the hosts specifier. It may select one system, many systems, one or more groups, or even some hosts that are in one group and explicitly not in another. Host Vars[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Host-Vars "Link to this term") Just like [Group Vars](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Group-Vars) , a directory alongside the inventory file named `host_vars/` can contain a file named after each hostname in the inventory file, in [YAML](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-YAML) format. This provides a convenient place to assign variables to the host without having to embed them in the [inventory](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Inventory) file. The Host Vars file can also be used to define complex data structures that can’t be represented in the inventory file. Idempotency[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Idempotency "Link to this term") An operation is idempotent if the result of performing it once is exactly the same as the result of performing it repeatedly without any intervening actions. Includes[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Includes "Link to this term") The idea that [playbook](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Playbooks) files (which are nothing more than lists of [plays](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Plays) ) can include other lists of plays, and task lists can externalize lists of [tasks](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Tasks) in other files, and similarly with [handlers](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Handlers) . Includes can be parameterized, which means that the loaded file can pass variables. For example, an included play for setting up a WordPress blog may take a parameter called `user` and that play could be included more than once to create a blog for both `alice` and `bob`. Inventory[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Inventory "Link to this term") A file (by default, Ansible uses a simple INI format) that describes [Hosts](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Host) and [Groups](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Group) in Ansible. Inventory can also be provided through an [Inventory Script](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Inventory-Script) (sometimes called an “External Inventory Script”). Inventory Script[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Inventory-Script "Link to this term") A very simple program (or a complicated one) that looks up [hosts](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Host) , [group](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Group) membership for hosts, and variable information from an external resource – whether that be a SQL database, a CMDB solution, or something like LDAP. This concept was adapted from Puppet (where it is called an “External Nodes Classifier”) and works more or less exactly the same way. Jinja2[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Jinja2 "Link to this term") Jinja2 is the preferred templating language of Ansible’s template module. It is a very simple Python template language that is generally readable and easy to write. JSON[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-JSON "Link to this term") Ansible uses JSON for return data from remote modules. This allows modules to be written in any language, not just Python. Keyword[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Keyword "Link to this term") The main expressions that make up Ansible, which apply to playbook objects (Play, Block, Role and Task). For example ‘vars:’ is a keyword that lets you define variables in the scope of the playbook object it is applied to. Lazy Evaluation[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Lazy-Evaluation "Link to this term") In general, Ansible evaluates any variables in [playbook](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Playbooks) content at the last possible second, which means that if you define a data structure that data structure itself can define variable values within it, and everything “just works” as you would expect. This also means variable strings can include other variables inside of those strings. Library[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Library "Link to this term") A collection of modules made available to **/usr/bin/ansible** or an Ansible [playbook](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Playbooks) . Limit Groups[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Limit-Groups "Link to this term") By passing `--limit somegroup` to **ansible** or **ansible-playbook**, the commands can be limited to a subset of [hosts](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Host) . For example, this can be used to run a [playbook](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Playbooks) that normally targets an entire set of servers to one particular server. Local Action[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Local-Action "Link to this term") This keyword is an alias for `delegate_to: localhost`. Used when you want to redirect an action from the remote to execute on the control node itself. Local Connection[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Local-Connection "Link to this term") By using `connection: local` in a [playbook](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Playbooks) , or passing `-c local` to **/usr/bin/ansible**, this indicates that we are executing a local fork instead of executing on the remote machine. You probably want `local_action` or `delegate_to: localhost` instead as this ONLY changes the connection and no other context for execution. Lookup Plugin[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Lookup-Plugin "Link to this term") A lookup plugin is a way to get data into Ansible from the outside world. Lookup plugins are an extension of Jinja2 and can be accessed in templates, for example, `{{ lookup('file','/path/to/file') }}`. These are how such things as `with_items`, are implemented. There are also lookup plugins like `file` which loads data from a file and ones for querying environment variables, DNS text records, or key value stores. Loops[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Loops "Link to this term") Generally, Ansible is not a programming language. It prefers to be more declarative, though various constructs like `loop` allow a particular task to be repeated for multiple items in a list. Certain modules, like [yum](https://docs.ansible.com/projects/ansible/2.9/modules/yum_module.html#yum-module "(in Ansible v2.9)") and [apt](https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/apt_module.html#apt-module) , actually take lists directly, and can install all packages given in those lists within a single transaction, dramatically speeding up total time to configuration, so they can be used without loops. Modules[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Modules "Link to this term") Modules are the units of work that Ansible ships out to remote machines. Modules are kicked off by either **/usr/bin/ansible** or **/usr/bin/ansible-playbook** (where multiple tasks use several different modules in conjunction). Modules can be implemented in any language, including Perl, Bash, or Ruby – but can take advantage of some useful communal library code if written in Python. Modules just have to return [JSON](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-JSON) . Once modules are executed on remote machines, they are removed, so no long running daemons are used. Ansible refers to the collection of available modules as a [library](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Library) . Multi-Tier[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Multi-Tier "Link to this term") The concept that IT systems are not managed one system at a time, but by interactions between multiple systems and groups of systems in well defined orders. For example, a web server may need to be updated before a database server and pieces on the web server may need to be updated after _THAT_ database server and various load balancers and monitoring servers may need to be contacted. Ansible models entire IT topologies and workflows rather than looking at configuration from a “one system at a time” perspective. Namespace[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Namespace "Link to this term") The first part of a fully qualified collection name, the namespace usually reflects a functional content category. Example: in `cisco.ios.ios_config`, `cisco` is the namespace. Namespaces are reserved and distributed by Red Hat at Red Hat’s discretion. Many, but not all, namespaces will correspond with vendor names. See [Galaxy namespaces](https://galaxy.ansible.com/docs/contributing/namespaces.html#galaxy-namespaces) on the Galaxy docsite for namespace requirements. Notify[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Notify "Link to this term") The act of a [task](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Tasks) registering a change event and informing a [handler](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Handlers) task that another [action](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Action) needs to be run at the end of the [play](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Plays) . If a handler is notified by multiple tasks, it will still be run only once. Handlers are run in the order they are listed, not in the order that they are notified. Orchestration[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Orchestration "Link to this term") Many software automation systems use this word to mean different things. Ansible uses it as a conductor would conduct an orchestra. A datacenter or cloud architecture is full of many systems, playing many parts – web servers, database servers, maybe load balancers, monitoring systems, continuous integration systems, and so on. In performing any process, it is necessary to touch systems in particular orders, often to simulate rolling updates or to deploy software correctly. Some system may perform some steps, then others, then previous systems already processed may need to perform more steps. Along the way, emails may need to be sent or web services contacted. Ansible orchestration is all about modeling that kind of process. paramiko[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-paramiko "Link to this term") Ansible can use a Python SSH implementation called `paramiko`. The paramiko library is generally fast and easy to manage. To use paramiko you need to specify the connection type in your [playbooks](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Playbooks) , or by using the `-c paramiko` flag. Playbooks[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Playbooks "Link to this term") Playbooks are the language by which Ansible orchestrates, configures, administers, or deploys systems. They are called playbooks partially because it is a sports analogy, and it is supposed to be fun using them. They aren’t workbooks :) Plays[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Plays "Link to this term") A [playbook](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Playbooks) is a list of plays. A play is minimally a mapping between a set of [hosts](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Host) selected by a host specifier (usually chosen by [groups](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Group) but sometimes by hostname [globs](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Globbing) ) and the [tasks](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Tasks) which run on those hosts to define the role that those systems will perform. There can be one or many plays in a playbook. Pull Mode[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Pull-Mode "Link to this term") By default, Ansible runs in [push mode](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Push-Mode) , which allows it very fine-grained control over when it talks to each system. Pull mode is provided for when you would rather have nodes check in every N minutes on a particular schedule. It uses a program called **ansible-pull** and can also be set up (or reconfigured) using a push-mode [playbook](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Playbooks) . Most Ansible users use push mode, but pull mode is included for variety and the sake of having choices. **ansible-pull** works by checking configuration orders out of Git on a crontab and then managing the machine locally, using the [local connection](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Local-Connection) plugin. Pulp 3 Galaxy[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Pulp-3-Galaxy "Link to this term") A self-hosted distribution server based on the [GalaxyNG codebase](https://galaxyng.netlify.app/) , based on Pulp version 3. Use it to find and share your own curated set of content. You can access your content with the `ansible-galaxy collection` command. Push Mode[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Push-Mode "Link to this term") Push mode is the default mode of Ansible. In fact, it is not really a mode at all – it is just how Ansible works when you aren’t thinking about it. Push mode allows Ansible to be fine-grained and conduct nodes through complex orchestration processes without waiting for them to check in. Register Variable[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Register-Variable "Link to this term") The result of running any [task](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Tasks) in Ansible can be stored in a variable for use in a template or a conditional statement. The keyword used to define the variable is called `register`, taking its name from the idea of registers in assembly programming (though Ansible will never feel like assembly programming). There are an infinite number of variable names you can use for registration. Resource Model[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Resource-Model "Link to this term") Ansible modules work in terms of resources. For example, the [file module](https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/file_module.html#file-module) will select a particular file and ensure that the attributes of that resource match a particular model. As an example, we might wish to change the owner of `/etc/motd` to `root` if it is not already set to `root`, or set its mode to `0644` if it is not already set to `0644`. The resource models are [idempotent](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Idempotency) meaning change commands are not run unless needed, and Ansible will bring the system back to a desired state regardless of the actual state – rather than you having to tell it how to get to the state. Roles[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Roles "Link to this term") Roles are units of organization in Ansible. Assigning a role to a group of [hosts](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Host) (or a set of [groups](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Group) , or [host patterns](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Globbing) , and so on) implies that they should implement a specific behavior. A role may include applying certain variable values, certain [tasks](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Tasks) , and certain [handlers](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Handlers) – or just one or more of these things. Because of the file structure associated with a role, roles become redistributable units that allow you to share behavior among [playbooks](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Playbooks) – or even with other users. Rolling Update[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Rolling-Update "Link to this term") The act of addressing a number of nodes in a group N at a time to avoid updating them all at once and bringing the system offline. For instance, in a web topology of 500 nodes handling very large volume, it may be reasonable to update 10 or 20 machines at a time, moving on to the next 10 or 20 when done. The `serial:` keyword in an Ansible [playbooks](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Playbooks) control the size of the rolling update pool. The default is to address the batch size all at once, so this is something that you must opt-in to. OS configuration (such as making sure config files are correct) does not typically have to use the rolling update model, but can do so if desired. Serial[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Serial "Link to this term") See also [Rolling Update](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Rolling-Update) Sudo[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Sudo "Link to this term") Ansible does not require root logins, and since it is daemonless, definitely does not require root level daemons (which can be a security concern in sensitive environments). Ansible can log in and perform many operations wrapped in a sudo command, and can work with both password-less and password-based sudo. Some operations that don’t normally work with sudo (like scp file transfer) can be achieved with Ansible’s [copy](https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/copy_module.html#copy-module) , [template](https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/template_module.html#template-module) , and [fetch](https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/fetch_module.html#fetch-module) modules while running in sudo mode. SSH (Native)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-SSH-Native "Link to this term") Native OpenSSH as an Ansible transport is specified with `-c ssh` (or a config file, or a keyword in the [playbook](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Playbooks) ) and can be useful if wanting to login through Kerberized SSH or using SSH jump hosts, and so on. In 1.2.1, `ssh` will be used by default if the OpenSSH binary on the control machine is sufficiently new. Previously, Ansible selected `paramiko` as a default. Using a client that supports `ControlMaster` and `ControlPersist` is recommended for maximum performance – if you don’t have that and don’t need Kerberos, jump hosts, or other features, `paramiko` is a good choice. Ansible will warn you if it doesn’t detect ControlMaster/ControlPersist capability. Tags[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Tags "Link to this term") Ansible allows tagging resources in a [playbook](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Playbooks) with arbitrary keywords, and then running only the parts of the playbook that correspond to those keywords. For example, it is possible to have an entire OS configuration, and have certain steps labeled `ntp`, and then run just the `ntp` steps to reconfigure the time server information on a remote host. Task[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Task "Link to this term") [Playbooks](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Playbooks) exist to run tasks. Tasks combine an [action](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Action) (a module and its arguments) with a name and optionally some other keywords (like [looping keywords](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Loops) ). [Handlers](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Handlers) are also tasks, but they are a special kind of task that do not run unless they are notified by name when a task reports an underlying change on a remote system. Tasks[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Tasks "Link to this term") A list of [Task](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Task) . Templates[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Templates "Link to this term") Ansible can easily transfer files to remote systems but often it is desirable to substitute variables in other files. Variables may come from the [inventory](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Inventory) file, [Host Vars](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Host-Vars) , [Group Vars](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Group-Vars) , or [Facts](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Facts) . Templates use the [Jinja2](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Jinja2) template engine and can also include logical constructs like loops and if statements. Transport[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Transport "Link to this term") Ansible uses :term:`Connection Plugins` to define types of available transports. These are simply how Ansible will reach out to managed systems. Transports included are [paramiko](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-paramiko) , [ssh](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-SSH-Native) (using OpenSSH), and [local](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Local-Connection) . When[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-When "Link to this term") An optional conditional statement attached to a [task](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Tasks) that is used to determine if the task should run or not. If the expression following the `when:` keyword evaluates to false, the task will be ignored. Vars (Variables)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Vars-Variables "Link to this term") As opposed to [Facts](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Facts) , variables are names of values (they can be simple scalar values – integers, booleans, strings) or complex ones (dictionaries/hashes, lists) that can be used in templates and [playbooks](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Playbooks) . They are declared things, not things that are inferred from the remote system’s current state or nature (which is what Facts are). YAML[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-YAML "Link to this term") Ansible does not want to force people to write programming language code to automate infrastructure, so Ansible uses YAML to define [playbook](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Playbooks) configuration languages and also variable files. YAML is nice because it has a minimum of syntax and is very clean and easy for people to skim. It is a good data format for configuration files and humans, but also machine readable. Ansible’s usage of YAML stemmed from Michael DeHaan’s first use of it inside of Cobbler around 2006. YAML is fairly popular in the dynamic language community and the format has libraries available for serialization in many languages (Python, Perl, Ruby, and so on). See also [Frequently Asked Questions](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#ansible-faq) Frequently asked questions [Working with playbooks](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks.html#working-with-playbooks) An introduction to playbooks [Ansible tips and tricks](https://docs.ansible.com/projects/ansible/latest/tips_tricks/index.html#playbooks-best-practices) Tips and tricks for playbooks [Communication](https://docs.ansible.com/projects/ansible/latest/community/communication.html#communication) Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide --- # ansible-core Roadmaps — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * ansible-core Roadmaps * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/roadmap/ansible_core_roadmap_index.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * ansible-core Roadmaps[](https://docs.ansible.com/projects/ansible/latest/roadmap/ansible_core_roadmap_index.html#ansible-core-roadmaps "Link to this heading") ================================================================================================================================================================ The `ansible-core` team develops a roadmap for each major and minor `ansible-core` release. The latest roadmap shows current work; older roadmaps provide a history of the project. We don’t publish roadmaps for subminor versions. So 2.10 and 2.11 have roadmaps, but 2.10.1 does not. We incorporate team and community feedback in each roadmap, and aim for further transparency and better inclusion of both community desires and submissions. Each roadmap offers a _best guess_, based on the `ansible-core` team’s experience and on requests and feedback from the community, of what will be included in a given release. However, some items on the roadmap may be dropped due to time constraints, lack of community maintainers, and so on. Each roadmap is published both as an idea of what is upcoming in `ansible-core`, and as a medium for seeking further feedback from the community. You can submit feedback on the current roadmap by creating a topic on the [Ansible Forum](https://docs.ansible.com/projects/ansible/latest/community/communication.html#ansible-forum) tagged with `ansible-core`. ansible-core Roadmaps * [Ansible-core 2.20](https://docs.ansible.com/projects/ansible/latest/roadmap/ROADMAP_2_20.html) * [Ansible-core 2.19](https://docs.ansible.com/projects/ansible/latest/roadmap/ROADMAP_2_19.html) * [Ansible-core 2.18](https://docs.ansible.com/projects/ansible/latest/roadmap/ROADMAP_2_18.html) * [Ansible-core 2.17](https://docs.ansible.com/projects/ansible/latest/roadmap/ROADMAP_2_17.html) * [Ansible-core 2.16](https://docs.ansible.com/projects/ansible/latest/roadmap/ROADMAP_2_16.html) * [Ansible-core 2.15](https://docs.ansible.com/projects/ansible/latest/roadmap/ROADMAP_2_15.html) * [Ansible-core 2.14](https://docs.ansible.com/projects/ansible/latest/roadmap/ROADMAP_2_14.html) * [Ansible-core 2.13](https://docs.ansible.com/projects/ansible/latest/roadmap/ROADMAP_2_13.html) * [Ansible-core 2.12](https://docs.ansible.com/projects/ansible/latest/roadmap/ROADMAP_2_12.html) * [Ansible-core 2.11](https://docs.ansible.com/projects/ansible/latest/roadmap/ROADMAP_2_11.html) * [Ansible-base 2.10](https://docs.ansible.com/projects/ansible/latest/roadmap/ROADMAP_2_10.html) --- # Ansible tips and tricks — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * Ansible tips and tricks * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/tips_tricks/index.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Ansible tips and tricks[](https://docs.ansible.com/projects/ansible-core/devel/tips_tricks/index.html#ansible-tips-and-tricks "Link to this heading") ======================================================================================================================================================= Note **Making Open Source More Inclusive** 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) . Welcome to the Ansible tips and tricks guide. These tips and tricks have helped us optimize our Ansible usage and we offer them here as suggestions. We hope they will help you organize content, write playbooks, maintain inventory, and execute Ansible. Ultimately, though, you should use Ansible in the way that makes the most sense for your organization and your goals. * [General tips](https://docs.ansible.com/projects/ansible-core/devel/tips_tricks/ansible_tips_tricks.html) * [Keep it simple](https://docs.ansible.com/projects/ansible-core/devel/tips_tricks/ansible_tips_tricks.html#keep-it-simple) * [Use version control](https://docs.ansible.com/projects/ansible-core/devel/tips_tricks/ansible_tips_tricks.html#use-version-control) * [Customize the CLI output](https://docs.ansible.com/projects/ansible-core/devel/tips_tricks/ansible_tips_tricks.html#customize-the-cli-output) * [Avoid configuration-dependent content](https://docs.ansible.com/projects/ansible-core/devel/tips_tricks/ansible_tips_tricks.html#avoid-configuration-dependent-content) * [Playbook tips](https://docs.ansible.com/projects/ansible-core/devel/tips_tricks/ansible_tips_tricks.html#playbook-tips) * [Use whitespace](https://docs.ansible.com/projects/ansible-core/devel/tips_tricks/ansible_tips_tricks.html#use-whitespace) * [Always name plays, tasks, and blocks](https://docs.ansible.com/projects/ansible-core/devel/tips_tricks/ansible_tips_tricks.html#always-name-plays-tasks-and-blocks) * [Always mention the state](https://docs.ansible.com/projects/ansible-core/devel/tips_tricks/ansible_tips_tricks.html#always-mention-the-state) * [Use comments](https://docs.ansible.com/projects/ansible-core/devel/tips_tricks/ansible_tips_tricks.html#use-comments) * [Use fully qualified collection names](https://docs.ansible.com/projects/ansible-core/devel/tips_tricks/ansible_tips_tricks.html#use-fully-qualified-collection-names) * [Inventory tips](https://docs.ansible.com/projects/ansible-core/devel/tips_tricks/ansible_tips_tricks.html#inventory-tips) * [Use dynamic inventory with clouds](https://docs.ansible.com/projects/ansible-core/devel/tips_tricks/ansible_tips_tricks.html#use-dynamic-inventory-with-clouds) * [Group inventory by function](https://docs.ansible.com/projects/ansible-core/devel/tips_tricks/ansible_tips_tricks.html#group-inventory-by-function) * [Separate production and staging inventory](https://docs.ansible.com/projects/ansible-core/devel/tips_tricks/ansible_tips_tricks.html#separate-production-and-staging-inventory) * [Keep vaulted variables safely visible](https://docs.ansible.com/projects/ansible-core/devel/tips_tricks/ansible_tips_tricks.html#keep-vaulted-variables-safely-visible) * [Execution tricks](https://docs.ansible.com/projects/ansible-core/devel/tips_tricks/ansible_tips_tricks.html#execution-tricks) * [Use Execution Environments](https://docs.ansible.com/projects/ansible-core/devel/tips_tricks/ansible_tips_tricks.html#use-execution-environments) * [Try it in staging first](https://docs.ansible.com/projects/ansible-core/devel/tips_tricks/ansible_tips_tricks.html#try-it-in-staging-first) * [Update in batches](https://docs.ansible.com/projects/ansible-core/devel/tips_tricks/ansible_tips_tricks.html#update-in-batches) * [Handling OS and distro differences](https://docs.ansible.com/projects/ansible-core/devel/tips_tricks/ansible_tips_tricks.html#handling-os-and-distro-differences) * [Sample Ansible setup](https://docs.ansible.com/projects/ansible-core/devel/tips_tricks/sample_setup.html) * [Sample directory layout](https://docs.ansible.com/projects/ansible-core/devel/tips_tricks/sample_setup.html#sample-directory-layout) * [Alternative directory layout](https://docs.ansible.com/projects/ansible-core/devel/tips_tricks/sample_setup.html#alternative-directory-layout) * [Sample group and host variables](https://docs.ansible.com/projects/ansible-core/devel/tips_tricks/sample_setup.html#sample-group-and-host-variables) * [Sample playbooks organized by function](https://docs.ansible.com/projects/ansible-core/devel/tips_tricks/sample_setup.html#sample-playbooks-organized-by-function) * [Sample task and handler files in a function-based role](https://docs.ansible.com/projects/ansible-core/devel/tips_tricks/sample_setup.html#sample-task-and-handler-files-in-a-function-based-role) * [What the sample setup enables](https://docs.ansible.com/projects/ansible-core/devel/tips_tricks/sample_setup.html#what-the-sample-setup-enables) * [Organizing for deployment or configuration](https://docs.ansible.com/projects/ansible-core/devel/tips_tricks/sample_setup.html#organizing-for-deployment-or-configuration) * [Using local Ansible modules](https://docs.ansible.com/projects/ansible-core/devel/tips_tricks/sample_setup.html#using-local-ansible-modules) --- # Getting started with Ansible — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * Getting started with Ansible * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/getting_started/index.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Getting started with Ansible[](https://docs.ansible.com/projects/ansible/latest/getting_started/index.html#getting-started-with-ansible "Link to this heading") ================================================================================================================================================================= Ansible automates the management of remote systems and controls their desired state. [![Basic components of an Ansible environment include a control node, an inventory of managed nodes, and a module copied to each managed node.](https://docs.ansible.com/projects/ansible/latest/_images/ansible_inv_start.svg)](https://docs.ansible.com/projects/ansible/latest/_images/ansible_inv_start.svg) As shown in the preceding figure, most Ansible environments have three main components: Control node A system on which Ansible is installed. You run Ansible commands such as `ansible` or `ansible-inventory` on a control node. Inventory A list of managed nodes that are logically organized. You create an inventory on the control node to describe host deployments to Ansible. Managed node A remote system, or host, that Ansible controls. * [Introduction to Ansible](https://docs.ansible.com/projects/ansible/latest/getting_started/introduction.html) * [Start automating with Ansible](https://docs.ansible.com/projects/ansible/latest/getting_started/get_started_ansible.html) * [Building an inventory](https://docs.ansible.com/projects/ansible/latest/getting_started/get_started_inventory.html) * [Creating a playbook](https://docs.ansible.com/projects/ansible/latest/getting_started/get_started_playbook.html) * [Ansible concepts](https://docs.ansible.com/projects/ansible/latest/getting_started/basic_concepts.html) --- # Getting started with Execution Environments — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * Getting started with Execution Environments * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/getting_started_ee/index.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Getting started with Execution Environments[](https://docs.ansible.com/projects/ansible/latest/getting_started_ee/index.html#getting-started-with-execution-environments "Link to this heading") ================================================================================================================================================================================================== You can run Ansible automation in containers, like any other modern software application. Ansible uses container images known as Execution Environments (EE) that act as control nodes. EEs remove complexity to scale out automation projects and make things like deployment operations much more straightforward. An Execution Environment image contains the following packages as standard: * `ansible-core` * `ansible-runner` * Python * Ansible content dependencies In addition to the standard packages, an EE can also contain: * one or more Ansible collections and their dependencies * other custom components This getting started guide shows you how to build and test a simple Execution Environment. The resulting container image represents an Ansible control node that contains: * standard EE packages * `community.postgresql` collection * `psycopg2-binary` Python package * [Introduction to Execution Environments](https://docs.ansible.com/projects/ansible/latest/getting_started_ee/introduction.html) * [Setting up your environment](https://docs.ansible.com/projects/ansible/latest/getting_started_ee/setup_environment.html) * [Building your first Execution Environment](https://docs.ansible.com/projects/ansible/latest/getting_started_ee/build_execution_environment.html) * [Running your EE](https://docs.ansible.com/projects/ansible/latest/getting_started_ee/run_execution_environment.html) * [Running Ansible with the community EE image](https://docs.ansible.com/projects/ansible/latest/getting_started_ee/run_community_ee_image.html) --- # Ansible Roadmap — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * Ansible Roadmap * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/roadmap/ansible_roadmap_index.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Ansible Roadmap[](https://docs.ansible.com/projects/ansible/latest/roadmap/ansible_roadmap_index.html#ansible-roadmap "Link to this heading") =============================================================================================================================================== The Ansible team develops a roadmap for each major and minor Ansible release. The latest roadmap shows current work; older roadmaps provide a history of the project. We don’t publish roadmaps for subminor versions. So 2.10 and 2.11 have roadmaps, but 2.10.1 does not. We incorporate team and community feedback in each roadmap, and aim for further transparency and better inclusion of both community desires and submissions. Each roadmap offers a _best guess_, based on the Ansible team’s experience and on requests and feedback from the community, of what will be included in a given release. However, some items on the roadmap may be dropped due to time constraints, lack of community maintainers, and so on. Each roadmap is published both as an idea of what is upcoming in Ansible, and as a medium for seeking further feedback from the community. You can submit feedback on the current roadmap by creating a [community topic](https://docs.ansible.com/projects/ansible/latest/community/steering/community_steering_committee.html#creating-community-topic) . Visit the [Ansible communication guide](https://docs.ansible.com/projects/ansible/latest/community/communication.html#communication) for details on how to join and use Ansible communication platforms. Ansible Release Roadmaps * [Ansible project 13.0](https://docs.ansible.com/projects/ansible/latest/roadmap/COLLECTIONS_13.html) * [Ansible project 12.0](https://docs.ansible.com/projects/ansible/latest/roadmap/COLLECTIONS_12.html) * [Ansible project 11.0](https://docs.ansible.com/projects/ansible/latest/roadmap/COLLECTIONS_11.html) * [Ansible project 10.0](https://docs.ansible.com/projects/ansible/latest/roadmap/COLLECTIONS_10.html) * [Ansible project 9.0](https://docs.ansible.com/projects/ansible/latest/roadmap/COLLECTIONS_9.html) * [Ansible project 8.0](https://docs.ansible.com/projects/ansible/latest/roadmap/COLLECTIONS_8.html) * [Ansible project 7.0](https://docs.ansible.com/projects/ansible/latest/roadmap/COLLECTIONS_7.html) * [Ansible project 6.0](https://docs.ansible.com/projects/ansible/latest/roadmap/COLLECTIONS_6.html) * [Ansible project 5.0](https://docs.ansible.com/projects/ansible/latest/roadmap/COLLECTIONS_5.html) * [Ansible project 4.0](https://docs.ansible.com/projects/ansible/latest/roadmap/COLLECTIONS_4.html) * [Ansible project 3.0](https://docs.ansible.com/projects/ansible/latest/roadmap/COLLECTIONS_3_0.html) * [Ansible project 2.10](https://docs.ansible.com/projects/ansible/latest/roadmap/COLLECTIONS_2_10.html) * [Older Roadmaps](https://docs.ansible.com/projects/ansible/latest/roadmap/old_roadmap_index.html) --- # Contributor path — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * [Ansible Community Guide](https://docs.ansible.com/projects/ansible/latest/community/index.html) * Contributor path * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/community/contributor_path.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Contributor path[](https://docs.ansible.com/projects/ansible/latest/community/contributor_path.html#contributor-path "Link to this heading") ============================================================================================================================================== This section describes the contributor’s journey from the beginning to becoming a leader who helps shape the future of Ansible. You can use this path as a roadmap for your long-term participation. Any contribution to the project, even a small one, is very welcome and valuable. Any contribution counts, whether it is feedback on an issue, a pull request, a topic or documentation change, or a coding contribution. When you contribute regularly, your proficiency and judgment in the related area increase and, along with this, the importance of your presence in the project. [Determine your area of interest](https://docs.ansible.com/projects/ansible/latest/community/contributor_path.html#id1) [](https://docs.ansible.com/projects/ansible/latest/community/contributor_path.html#determine-your-area-of-interest "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- First, determine areas that are interesting to you. Consider your current experience and what you’d like to gain. For example, if you use a specific collection, have a look there. See [How can I help?](https://docs.ansible.com/projects/ansible/latest/community/how_can_I_help.html#how-can-i-help) for more ideas on how to help. [Find the corresponding project](https://docs.ansible.com/projects/ansible/latest/community/contributor_path.html#id2) [](https://docs.ansible.com/projects/ansible/latest/community/contributor_path.html#find-the-corresponding-project "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- These are multiple community projects in the Ansible ecosystem you could contribute to: * [Ansible Core](https://docs.ansible.com/ansible-core/devel/index.html) * [Collections](https://docs.ansible.com/projects/ansible/latest/collections_guide/index.html#collections-index) * [AWX](https://github.com/ansible/awx) * [Galaxy](https://galaxy.ansible.com/) * [ansible-lint](https://ansible-lint.readthedocs.io/en/latest/) * [Molecule](https://ansible.readthedocs.io/projects/molecule/) [Learn](https://docs.ansible.com/projects/ansible/latest/community/contributor_path.html#id3) [](https://docs.ansible.com/projects/ansible/latest/community/contributor_path.html#learn "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The required skillset depends on the area of interest and the project you’ll be working on. Remember that the best way to learn is by doing. ### [Specific knowledge for code developers](https://docs.ansible.com/projects/ansible/latest/community/contributor_path.html#id4) [](https://docs.ansible.com/projects/ansible/latest/community/contributor_path.html#specific-knowledge-for-code-developers "Link to this heading") Code development requires the most technical knowledge. Let’s sort out what an Ansible developer should learn. You should understand at least the _basics_ of the following tools: * [Python programming language](https://docs.python.org/3/tutorial/) * [Git](https://git-scm.com/docs/gittutorial) * [GitHub collaborative development model through forks and pull requests](https://docs.github.com/en/github/collaborating-with-pull-requests/getting-started/about-collaborative-development-models) You can learn these tools more in-depth when working on your first contributions. Each Ansible project has its own set of contributor guidelines. Familiarize yourself with these as you prepare your first contributions. * [Ansible Core development](https://docs.ansible.com/projects/ansible/latest/dev_guide/index.html#developer-guide) . * [Ansible collection development](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_collections.html#developing-collections) and the collection-level contributor guidelines in the collection repository. [Making your first contribution](https://docs.ansible.com/projects/ansible/latest/community/contributor_path.html#id5) [](https://docs.ansible.com/projects/ansible/latest/community/contributor_path.html#making-your-first-contribution "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can find some ideas on how you can contribute in [How can I help?](https://docs.ansible.com/projects/ansible/latest/community/how_can_I_help.html#how-can-i-help) . If you are interested in contributing to collections, take a look at [collection contributions](https://docs.ansible.com/projects/ansible/latest/community/contributions_collections.html#collections-contributions) and the [collection repository](https://github.com/ansible-collections/) ’s `README` and `CONTRIBUTING` files. To make your first experience as smooth as possible, read the repository documentation carefully, then ask the repository maintainers for guidance if you have any questions. Take a look at GitHub issues labeled with the `easyfix` and `good_first_issue` labels for: * [Ansible collections repositories](https://github.com/search?q=user%3Aansible-collections+label%3Aeasyfix%2C%22good+first+issue%22+state%3Aopen&type=Issues) * [All other Ansible projects](https://github.com/search?q=user%3Aansible+user%3Aansible-community+label%3Aeasyfix%2C%22good+first+issue%22+state%3Aopen&type=Issues) Issues labeled with the `docs` label in [Ansible collections](https://github.com/search?q=user%3Aansible-collections+label%3Adocs+state%3Aopen+type%3Aissue&type=Issues) and [other](https://github.com/search?q=user%3Aansible+user%3Aansible-community+label%3Adocs+state%3Aopen+type%3Aissue&type=Issues) Ansible projects can be also good to start with. When you choose an issue to work on, add a comment directly on the GitHub issue to say you are looking at it and let others know to avoid conflicting work. You can also ask for help in a comment if you need it. [Continue to contribute](https://docs.ansible.com/projects/ansible/latest/community/contributor_path.html#id6) [](https://docs.ansible.com/projects/ansible/latest/community/contributor_path.html#continue-to-contribute "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- We don’t expect everybody to know everything. Start small, think big. When you contribute regularly, your proficiency and judgment in the related area will improve quickly and, along with this, the importance of your presence in the project. See [Communicating with the Ansible community](https://docs.ansible.com/projects/ansible/latest/community/communication.html#communication) for ways to communicate and engage with the Ansible community, including working group meetings, accessing the Bullhorn news bulletin, and upcoming contributor summits. [Teach others](https://docs.ansible.com/projects/ansible/latest/community/contributor_path.html#id7) [](https://docs.ansible.com/projects/ansible/latest/community/contributor_path.html#teach-others "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Share your experience with other contributors through [improving documentation](https://docs.ansible.com/projects/ansible/latest/community/documentation_contributions.html#community-documentation-contributions) , answering questions from other contributors and users on [Matrix/Libera.Chat IRC](https://docs.ansible.com/projects/ansible/latest/community/communication.html#communication) , giving advice on issues and pull requests, and discussing topics on the [Forum](https://docs.ansible.com/projects/ansible/latest/community/communication.html#ansible-forum) . [Become a collection maintainer](https://docs.ansible.com/projects/ansible/latest/community/contributor_path.html#id8) [](https://docs.ansible.com/projects/ansible/latest/community/contributor_path.html#become-a-collection-maintainer "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- If you are a code contributor to a collection, you can get extended permissions in the repository and become a maintainer. A collection maintainer is a contributor trusted by the community who makes significant and regular contributions to the project and showed themselves as a specialist in the related area. See [Guidelines for collection maintainers](https://docs.ansible.com/projects/ansible/latest/community/maintainers.html#maintainers) for details. For some collections that use the [collection bot](https://github.com/ansible-community/collection_bot) , such as [community.general](https://github.com/ansible-collections/community.general) and [community.network](https://github.com/ansible-collections/community.network) , you can have different levels of access and permissions: * File-level permissions: the stage prior to becoming a collection maintainer. The file is usually a module or plugin. File maintainers have indirect commit rights. * Supershipit permissions: similar to being a file maintainer but the scope where a maintainer has the indirect commit is the whole repository. * Triage access to the repository: allows contributors to manage issues and pull requests. * Write access to the repository also known as `commit`: allows contributors to merge pull requests to the development branch as well as perform all the other activities listed in the [Guidelines for collection maintainers](https://docs.ansible.com/projects/ansible/latest/community/maintainers.html#maintainers) . For information about permission levels, see the [GitHub official documentation](https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/repository-permission-levels-for-an-organization) . [Become a steering committee member](https://docs.ansible.com/projects/ansible/latest/community/contributor_path.html#id9) [](https://docs.ansible.com/projects/ansible/latest/community/contributor_path.html#become-a-steering-committee-member "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Note You do NOT have to be a programmer to become a steering committee member. The [Steering Committee](https://docs.ansible.com/projects/ansible/latest/community/steering/steering_index.html#community-steering-committee) member status reflects the highest level of trust and allows contributors to lead the project by making important decisions for the Ansible project. The Committee members are community leaders who shape the project’s future and the future of automation in the IT world in general. To reach the status, as the current Committee members did before getting it, along with the things mentioned in this document, you should: * Subscribe to, comment on, and vote on the community topics. * Propose your topics. * If time permits, join the [Community meetings](https://github.com/ansible-community/meetings/blob/main/README.md#schedule) . Note this is **NOT** a requirement. --- # Ansible Reference: Module Utilities — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * Ansible Reference: Module Utilities * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/reference_appendices/module_utils.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Ansible Reference: Module Utilities[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible-reference-module-utilities "Link to this heading") ========================================================================================================================================================================================== This page documents utilities intended to be helpful when writing Ansible modules in Python. AnsibleModule[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansiblemodule "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------- To use this functionality, include `from ansible.module_utils.basic import AnsibleModule` in your module. _class_ ansible.module\_utils.basic.AnsibleModule(_argument\_spec_, _bypass\_checks\=False_, _no\_log\=False_, _mutually\_exclusive\=None_, _required\_together\=None_, _required\_one\_of\=None_, _add\_file\_common\_args\=False_, _supports\_check\_mode\=False_, _required\_if\=None_, _required\_by\=None_) Common code for quickly building an ansible module in Python (although you can write modules with anything that can return JSON). See [Developing modules](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_general.html#developing-modules-general) for a general introduction and [Ansible module architecture](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_program_flow_modules.html#developing-program-flow-modules) for more detailed explanation. add\_path\_info(_kwargs_) for results that are files, supplement the info about the file in the return path with stats about the file path. atomic\_move(_src_, _dest_, _unsafe\_writes\=False_, _keep\_dest\_attrs\=True_) atomically move src to dest, copying attributes from dest, returns true on success it uses os.rename to ensure this as it is an atomic operation, rest of the function is to work around limitations, corner cases and ensure selinux context is saved if possible backup\_local(_fn_) make a date-marked backup of the specified file, return True or False on success or failure boolean(_arg_) Convert the argument to a boolean deprecate(_msg: [str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") _, _version: [str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") | [None](https://docs.python.org/3/library/constants.html#None "(in Python v3.14)") \= None_, _date: [str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") | [None](https://docs.python.org/3/library/constants.html#None "(in Python v3.14)") \= None_, _collection\_name: [str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") | [None](https://docs.python.org/3/library/constants.html#None "(in Python v3.14)") \= None_, _\*_, _deprecator: PluginInfo | [None](https://docs.python.org/3/library/constants.html#None "(in Python v3.14)") \= None_, _help\_text: [str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") | [None](https://docs.python.org/3/library/constants.html#None "(in Python v3.14)") \= None_) → [None](https://docs.python.org/3/library/constants.html#None "(in Python v3.14)") Record a deprecation warning to be returned with the module result. Most callers do not need to provide collection\_name or deprecator – but provide only one if needed. Specify version or date, but not both. If date is a string, it must be in the form YYYY-MM-DD. digest\_from\_file(_filename_, _algorithm_) Return hex digest of local file for a digest\_method specified by name, or None if file is not present. error\_as\_warning(_msg: [str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") | [None](https://docs.python.org/3/library/constants.html#None "(in Python v3.14)") _, _exception: [BaseException](https://docs.python.org/3/library/exceptions.html#BaseException "(in Python v3.14)") _, _\*_, _help\_text: [str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") | [None](https://docs.python.org/3/library/constants.html#None "(in Python v3.14)") \= None_) → [None](https://docs.python.org/3/library/constants.html#None "(in Python v3.14)") Display an exception as a warning. exit\_json(_\*\*kwargs_) → [NoReturn](https://docs.python.org/3/library/typing.html#typing.NoReturn "(in Python v3.14)") return from the module, without error fail\_json(_msg: str_, _\*_, _exception: BaseException | str | None \= _, _\*\*kwargs_) → [NoReturn](https://docs.python.org/3/library/typing.html#typing.NoReturn "(in Python v3.14)") Return from the module with an error message and optional exception/traceback detail. A traceback will only be included in the result if error traceback capturing has been enabled. When exception is an exception object, its message chain will be automatically combined with msg to create the final error message. The message chain includes the exception’s message as well as messages from any \_\_cause\_\_ exceptions. The traceback from exception will be used for the formatted traceback. When exception is a string, it will be used as the formatted traceback. When exception is set to None, the current call stack will be used for the formatted traceback. When exception is not specified, a formatted traceback will be retrieved from the current exception. If no exception is pending, the current call stack will be used instead. find\_mount\_point(_path_) > Takes a path and returns its mount point Parameters: **path** – a string type with a filesystem path Returns: the path to the mount point as a text type get\_bin\_path(_arg_, _required\=False_, _opt\_dirs\=None_) Find system executable in PATH. Parameters: * **arg** – The executable to find. * **required** – if the executable is not found and required is `True`, fail\_json * **opt\_dirs** – optional list of directories to search in addition to `PATH` Returns: if found return full path; otherwise return original arg, unless ‘warning’ then return None Raises: Sysexit: if arg is not found and required=True (via fail\_json) is\_executable(_path_) is the given path executable? Parameters: **path** – The path of the file to check. Limitations: * Does not account for FSACLs. * Most times we really want to know “Can the current user execute this file”. This function does not tell us that, only if any execute bit is set. is\_special\_selinux\_path(_path_) Returns a tuple containing (True, selinux\_context) if the given path is on a NFS or other ‘special’ fs mount point, otherwise the return will be (False, None). load\_file\_common\_arguments(_params_, _path\=None_) many modules deal with files, this encapsulates common options that the file module accepts such that it is directly available to all modules and they can share code. Allows to overwrite the path/dest module argument by providing path. md5(_filename_) Return MD5 hex digest of local file using digest\_from\_file(). Do not use this function unless you have no other choice for: 1. Optional backwards compatibility 2. Compatibility with a third party protocol This function will not work on systems complying with FIPS-140-2. Most uses of this function can use the module.sha1 function instead. preserved\_copy(_src_, _dest_) Copy a file with preserved ownership, permissions and context run\_command(_args_, _check\_rc\=False_, _close\_fds\=True_, _executable\=None_, _data\=None_, _binary\_data\=False_, _path\_prefix\=None_, _cwd\=None_, _use\_unsafe\_shell\=False_, _prompt\_regex\=None_, _environ\_update\=None_, _umask\=None_, _encoding\='utf-8'_, _errors\='surrogate\_or\_strict'_, _expand\_user\_and\_vars\=True_, _pass\_fds\=None_, _before\_communicate\_callback\=None_, _ignore\_invalid\_cwd\=True_, _handle\_exceptions\=True_) Execute a command, returns rc, stdout, and stderr. The mechanism of this method for reading stdout and stderr differs from that of CPython subprocess.Popen.communicate, in that this method will stop reading once the spawned command has exited and stdout and stderr have been consumed, as opposed to waiting until stdout/stderr are closed. This can be an important distinction, when taken into account that a forked or backgrounded process may hold stdout or stderr open for longer than the spawned command. Parameters: **args** – is the command to run \* If args is a list, the command will be run with shell=False. \* If args is a string and use\_unsafe\_shell=False it will split args to a list and run with shell=False \* If args is a string and use\_unsafe\_shell=True it runs with shell=True. Kw check\_rc: Whether to call fail\_json in case of non zero RC. Default False Kw close\_fds: See documentation for subprocess.Popen(). Default True Kw executable: See documentation for subprocess.Popen(). Default None Kw data: If given, information to write to the stdin of the command Kw binary\_data: If False, append a newline to the data. Default False Kw path\_prefix: If given, additional path to find the command in. This adds to the PATH environment variable so helper commands in the same directory can also be found Kw cwd: If given, working directory to run the command inside Kw use\_unsafe\_shell: See args parameter. Default False Kw prompt\_regex: Regex string (not a compiled regex) which can be used to detect prompts in the stdout which would otherwise cause the execution to hang (especially if no input data is specified) Kw environ\_update: dictionary to _update_ environ variables with Kw umask: Umask to be used when running the command. Default None Kw encoding: Since we return strings, we need to know the encoding to use to transform from bytes to text. If you want to always get bytes back, use encoding=None. The default is “utf-8”. This does not affect transformation of strings given as args. Kw errors: Since we return strings, we need to transform stdout and stderr from bytes to text. If the bytes are undecodable in the `encoding` specified, then use this error handler to deal with them. The default is `surrogate_or_strict` which means that the bytes will be decoded using the surrogateescape error handler if available (available on all Python versions we support) otherwise a UnicodeError traceback will be raised. This does not affect transformations of strings given as args. Kw expand\_user\_and\_vars: When `use_unsafe_shell=False` this argument dictates whether `~` is expanded in paths and environment variables are expanded before running the command. When `True` a string such as `$SHELL` will be expanded regardless of escaping. When `False` and `use_unsafe_shell=False` no path or variable expansion will be done. Kw pass\_fds: This argument dictates which file descriptors should be passed to an underlying `Popen` constructor. Kw before\_communicate\_callback: This function will be called after `Popen` object will be created but before communicating to the process. (`Popen` object will be passed to callback as a first argument) Kw ignore\_invalid\_cwd: This flag indicates whether an invalid `cwd` (non-existent or not a directory) should be ignored or should raise an exception. Kw handle\_exceptions: This flag indicates whether an exception will be handled inline and issue a failed\_json or if the caller should handle it. Returns: A 3-tuple of return code (int), stdout (str), and stderr (str). stdout and stderr are text strings converted according to the encoding and errors parameters. If you want byte strings, use encoding=None to turn decoding to text off. sha1(_filename_) Return SHA1 hex digest of local file using digest\_from\_file(). sha256(_filename_) Return SHA-256 hex digest of local file using digest\_from\_file(). Basic[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#basic "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------- To use this functionality, include `import ansible.module_utils.basic` in your module. ansible.module\_utils.basic.get\_all\_subclasses(_cls_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.basic.get_all_subclasses "Link to this definition") **Deprecated**: Use ansible.module\_utils.common.\_utils.get\_all\_subclasses instead ansible.module\_utils.basic.get\_platform()[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.basic.get_platform "Link to this definition") **Deprecated** Use [`platform.system()`](https://docs.python.org/3/library/platform.html#platform.system "(in Python v3.14)") directly. Returns: Name of the platform the module is running on in a native string Returns a native string that labels the platform (“Linux”, “Solaris”, etc). Currently, this is the result of calling [`platform.system()`](https://docs.python.org/3/library/platform.html#platform.system "(in Python v3.14)") . ansible.module\_utils.basic.heuristic\_log\_sanitize(_data_, _no\_log\_values\=None_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.basic.heuristic_log_sanitize "Link to this definition") Remove strings that look like passwords from log messages ansible.module\_utils.basic.load\_platform\_subclass(_cls_, _\*args_, _\*\*kwargs_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.basic.load_platform_subclass "Link to this definition") **Deprecated**: Use ansible.module\_utils.common.sys\_info.get\_platform\_subclass instead Argument Spec[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#argument-spec "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------- Classes and functions for validating parameters against an argument spec. ### ArgumentSpecValidator[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#argumentspecvalidator "Link to this heading") _class_ ansible.module\_utils.common.arg\_spec.ArgumentSpecValidator(_argument\_spec_, _mutually\_exclusive\=None_, _required\_together\=None_, _required\_one\_of\=None_, _required\_if\=None_, _required\_by\=None_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.arg_spec.ArgumentSpecValidator "Link to this definition") Argument spec validation class Creates a validator based on the `argument_spec` that can be used to validate a number of parameters using the [`validate()`](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.arg_spec.ArgumentSpecValidator.validate "ansible.module_utils.common.arg_spec.ArgumentSpecValidator.validate") method. Parameters: * **argument\_spec** ([_dict_](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.14)") _\[_[_str_](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ _,_ [_dict_](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.14)")\ _\]_) – Specification of valid parameters and their type. May include nested argument specs. * **mutually\_exclusive** ([_list_](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.14)") _\[_[_str_](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ _\] or_ [_list_](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.14)") _\[_[_list_](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.14)")\ _\[_[_str_](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ _\]__\]_) – List or list of lists of terms that should not be provided together. * **required\_together** ([_list_](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.14)") _\[_[_list_](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.14)")\ _\[_[_str_](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ _\]__\]_) – List of lists of terms that are required together. * **required\_one\_of** ([_list_](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.14)") _\[_[_list_](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.14)")\ _\[_[_str_](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ _\]__\]_) – List of lists of terms, one of which in each list is required. * **required\_if** ([_list_](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.14)") ) – List of lists of `[parameter, value, [parameters]]` where one of `[parameters]` is required if `parameter == value`. * **required\_by** ([_dict_](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.14)") _\[_[_str_](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ _,_ [_list_](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.14)")\ _\[_[_str_](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ _\]__\]_) – Dictionary of parameter names that contain a list of parameters required by each key in the dictionary. validate(_parameters_, _\*args_, _\*\*kwargs_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.arg_spec.ArgumentSpecValidator.validate "Link to this definition") Validate `parameters` against argument spec. Error messages in the [`ValidationResult`](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.arg_spec.ValidationResult "ansible.module_utils.common.arg_spec.ValidationResult") may contain no\_log values and should be sanitized with [`sanitize_keys()`](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.parameters.sanitize_keys "ansible.module_utils.common.parameters.sanitize_keys") before logging or displaying. Parameters: **parameters** ([_dict_](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.14)") _\[_[_str_](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ _,_ [_dict_](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.14)")\ _\]_) – Parameters to validate against the argument spec Returns: [`ValidationResult`](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.arg_spec.ValidationResult "ansible.module_utils.common.arg_spec.ValidationResult") containing validated parameters. Simple Example: argument\_spec = { 'name': {'type': 'str'}, 'age': {'type': 'int'}, } parameters = { 'name': 'bo', 'age': '42', } validator = ArgumentSpecValidator(argument\_spec) result = validator.validate(parameters) if result.error\_messages: sys.exit("Validation failed: {0}".format(", ".join(result.error\_messages)) valid\_params = result.validated\_parameters ### ValidationResult[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#validationresult "Link to this heading") _class_ ansible.module\_utils.common.arg\_spec.ValidationResult(_parameters_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.arg_spec.ValidationResult "Link to this definition") Result of argument spec validation. This is the object returned by [`ArgumentSpecValidator.validate()`](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.arg_spec.ArgumentSpecValidator.validate "ansible.module_utils.common.arg_spec.ArgumentSpecValidator.validate") containing the validated parameters and any errors. Parameters: **parameters** ([_dict_](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.14)") ) – Terms to be validated and coerced to the correct type. errors[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.arg_spec.ValidationResult.errors "Link to this definition") [`AnsibleValidationErrorMultiple`](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.errors.AnsibleValidationErrorMultiple "ansible.module_utils.errors.AnsibleValidationErrorMultiple") containing all [`AnsibleValidationError`](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.errors.AnsibleValidationError "ansible.module_utils.errors.AnsibleValidationError") objects if there were any failures during validation. _property_ validated\_parameters[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.arg_spec.ValidationResult.validated_parameters "Link to this definition") Validated and coerced parameters. _property_ unsupported\_parameters[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.arg_spec.ValidationResult.unsupported_parameters "Link to this definition") [`set`](https://docs.python.org/3/library/stdtypes.html#set "(in Python v3.14)") of unsupported parameter names. _property_ error\_messages[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.arg_spec.ValidationResult.error_messages "Link to this definition") [`list`](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.14)") of all error messages from each exception in [`errors`](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.arg_spec.ValidationResult.errors "ansible.module_utils.common.arg_spec.ValidationResult.errors") . ### Parameters[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#module-ansible.module_utils.common.parameters "Link to this heading") ansible.module\_utils.common.parameters.DEFAULT\_TYPE\_VALIDATORS[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.parameters.DEFAULT_TYPE_VALIDATORS "Link to this definition") [`dict`](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.14)") of type names, such as `'str'`, and the default function used to check that type, [`check_type_str()`](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_str "ansible.module_utils.common.validation.check_type_str") in this case. ansible.module\_utils.common.parameters.env\_fallback(_\*args_, _\*\*kwargs_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.parameters.env_fallback "Link to this definition") Load value from environment variable ansible.module\_utils.common.parameters.remove\_values(_value_, _no\_log\_strings_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.parameters.remove_values "Link to this definition") Remove strings in `no_log_strings` from value. If value is a container type, then remove a lot more. Use of `deferred_removals` exists, rather than a pure recursive solution, because of the potential to hit the maximum recursion depth when dealing with large amounts of data (see [issue #24560](https://github.com/ansible/ansible/issues/24560) ). ansible.module\_utils.common.parameters.sanitize\_keys(_obj_, _no\_log\_strings_, _ignore\_keys\=frozenset({})_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.parameters.sanitize_keys "Link to this definition") Sanitize the keys in a container object by removing `no_log` values from key names. This is a companion function to the [`remove_values()`](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.parameters.remove_values "ansible.module_utils.common.parameters.remove_values") function. Similar to that function, we make use of `deferred_removals` to avoid hitting maximum recursion depth in cases of large data structures. Parameters: * **obj** – The container object to sanitize. Non-container objects are returned unmodified. * **no\_log\_strings** – A set of string values we do not want logged. * **ignore\_keys** – A set of string values of keys to not sanitize. Returns: An object with sanitized keys. ### Validation[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#validation "Link to this heading") Standalone functions for validating various parameter types. ansible.module\_utils.common.validation.check\_missing\_parameters(_parameters_, _required\_parameters\=None_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_missing_parameters "Link to this definition") This is for checking for required params when we can not check via argspec because we need more information than is simply given in the argspec. Raises [`TypeError`](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") if any required parameters are missing Parameters: * **parameters** – Dictionary of parameters * **required\_parameters** – List of parameters to look for in the given parameters. Returns: Empty list or raises [`TypeError`](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") if the check fails. ansible.module\_utils.common.validation.check\_mutually\_exclusive(_terms_, _parameters_, _options\_context\=None_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_mutually_exclusive "Link to this definition") Check mutually exclusive terms against argument parameters Accepts a single list or list of lists that are groups of terms that should be mutually exclusive with one another Parameters: * **terms** – List of mutually exclusive parameters * **parameters** – Dictionary of parameters * **options\_context** – List of strings of parent key names if `terms` are in a sub spec. Returns: Empty list or raises [`TypeError`](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") if the check fails. ansible.module\_utils.common.validation.check\_required\_arguments(_argument\_spec_, _parameters_, _options\_context\=None_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_required_arguments "Link to this definition") Check all parameters in argument\_spec and return a list of parameters that are required but not present in parameters. Raises [`TypeError`](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") if the check fails Parameters: * **argument\_spec** – Argument spec dictionary containing all parameters and their specification * **parameters** – Dictionary of parameters * **options\_context** – List of strings of parent key names if `argument_spec` are in a sub spec. Returns: Empty list or raises [`TypeError`](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") if the check fails. ansible.module\_utils.common.validation.check\_required\_by(_requirements_, _parameters_, _options\_context\=None_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_required_by "Link to this definition") For each key in requirements, check the corresponding list to see if they exist in parameters. Accepts a single string or list of values for each key. Parameters: * **requirements** – Dictionary of requirements * **parameters** – Dictionary of parameters * **options\_context** – List of strings of parent key names if `requirements` are in a sub spec. Returns: Empty dictionary or raises [`TypeError`](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") if the check fails. ansible.module\_utils.common.validation.check\_required\_if(_requirements_, _parameters_, _options\_context\=None_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_required_if "Link to this definition") Check parameters that are conditionally required Raises [`TypeError`](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") if the check fails Parameters: **requirements** – List of lists specifying a parameter, value, parameters required when the given parameter is the specified value, and optionally a boolean indicating any or all parameters are required. Example: required\_if\=\[\ \['state', 'present', ('path',), True\],\ \['someint', 99, ('bool\_param', 'string\_param')\],\ \] Parameters: * **parameters** – Dictionary of parameters * **options\_context** – List of strings of parent key names if `requirements` are in a sub spec. Returns: Empty list or raises [`TypeError`](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") if the check fails. The results attribute of the exception contains a list of dictionaries. Each dictionary is the result of evaluating each item in requirements. Each return dictionary contains the following keys: > key missing: > > List of parameters that are required but missing > > key requires: > > ’any’ or ‘all’ > > key parameter: > > Parameter name that has the requirement > > key value: > > Original value of the parameter > > key requirements: > > Original required parameters Example: \[\ {\ 'parameter': 'someint',\ 'value': 99\ 'requirements': ('bool\_param', 'string\_param'),\ 'missing': \['string\_param'\],\ 'requires': 'all',\ }\ \] ansible.module\_utils.common.validation.check\_required\_one\_of(_terms_, _parameters_, _options\_context\=None_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_required_one_of "Link to this definition") Check each list of terms to ensure at least one exists in the given module parameters Accepts a list of lists or tuples Parameters: * **terms** – List of lists of terms to check. For each list of terms, at least one is required. * **parameters** – Dictionary of parameters * **options\_context** – List of strings of parent key names if `terms` are in a sub spec. Returns: Empty list or raises [`TypeError`](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") if the check fails. ansible.module\_utils.common.validation.check\_required\_together(_terms_, _parameters_, _options\_context\=None_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_required_together "Link to this definition") Check each list of terms to ensure every parameter in each list exists in the given parameters. Accepts a list of lists or tuples. Parameters: * **terms** – List of lists of terms to check. Each list should include parameters that are all required when at least one is specified in the parameters. * **parameters** – Dictionary of parameters * **options\_context** – List of strings of parent key names if `terms` are in a sub spec. Returns: Empty list or raises [`TypeError`](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") if the check fails. ansible.module\_utils.common.validation.check\_type\_bits(_value_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_bits "Link to this definition") Convert a human-readable string bits value to bits in integer. Example: `check_type_bits('1Mb')` returns integer 1048576. Raises [`TypeError`](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") if unable to convert the value. ansible.module\_utils.common.validation.check\_type\_bool(_value_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_bool "Link to this definition") Verify that the value is a bool or convert it to a bool and return it. Raises [`TypeError`](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") if unable to convert to a bool Parameters: **value** – String, int, or float to convert to bool. Valid booleans include: ‘1’, ‘on’, 1, ‘0’, 0, ‘n’, ‘f’, ‘false’, ‘true’, ‘y’, ‘t’, ‘yes’, ‘no’, ‘off’ Returns: Boolean True or False ansible.module\_utils.common.validation.check\_type\_bytes(_value_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_bytes "Link to this definition") Convert a human-readable string value to bytes Raises [`TypeError`](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") if unable to convert the value ansible.module\_utils.common.validation.check\_type\_dict(_value_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_dict "Link to this definition") Verify that value is a dict or convert it to a dict and return it. Raises [`TypeError`](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") if unable to convert to a dict Parameters: **value** – Dict or string to convert to a dict. Accepts `k1=v2, k2=v2` or `k1=v2 k2=v2`. Returns: value converted to a dictionary ansible.module\_utils.common.validation.check\_type\_float(_value_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_float "Link to this definition") Verify that value is a float or convert it to a float and return it Raises [`TypeError`](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") if unable to convert to a float Parameters: **value** – float, int, str, or bytes to verify or convert and return. Returns: float of given value. ansible.module\_utils.common.validation.check\_type\_int(_value_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_int "Link to this definition") Verify that the value is an integer and return it or convert the value to an integer and return it Raises [`TypeError`](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") if unable to convert to an int Parameters: **value** – String or int to convert of verify Returns: int of given value ansible.module\_utils.common.validation.check\_type\_jsonarg(_value_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_jsonarg "Link to this definition") JSON serialize dict/list/tuple, strip str and bytes. Previously required for cases where Ansible/Jinja classic-mode literal eval pass could inadvertently deserialize objects. ansible.module\_utils.common.validation.check\_type\_list(_value_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_list "Link to this definition") Verify that the value is a list or convert to a list A comma separated string will be split into a list. Raises a [`TypeError`](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") if unable to convert to a list. Parameters: **value** – Value to validate or convert to a list Returns: Original value if it is already a list, single item list if a float, int, or string without commas, or a multi-item list if a comma-delimited string. ansible.module\_utils.common.validation.check\_type\_path(_value_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_path "Link to this definition") Verify the provided value is a string or convert it to a string, then return the expanded path ansible.module\_utils.common.validation.check\_type\_raw(_value_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_raw "Link to this definition") Returns the raw value ansible.module\_utils.common.validation.check\_type\_str(_value_, _allow\_conversion\=True_, _param\=None_, _prefix\=''_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_str "Link to this definition") Verify that the value is a string or convert to a string. Since unexpected changes can sometimes happen when converting to a string, `allow_conversion` controls whether or not the value will be converted or a TypeError will be raised if the value is not a string and would be converted Parameters: * **value** – Value to validate or convert to a string * **allow\_conversion** – Whether to convert the string and return it or raise a TypeError Returns: Original value if it is a string, the value converted to a string if allow\_conversion=True, or raises a TypeError if allow\_conversion=False. ansible.module\_utils.common.validation.count\_terms(_terms_, _parameters_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.validation.count_terms "Link to this definition") Count the number of occurrences of a key in a given dictionary Parameters: * **terms** – String or iterable of values to check * **parameters** – Dictionary of parameters Returns: An integer that is the number of occurrences of the terms values in the provided dictionary. Errors[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#module-ansible.module_utils.errors "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------- _exception_ ansible.module\_utils.errors.AnsibleFallbackNotFound[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.errors.AnsibleFallbackNotFound "Link to this definition") Fallback validator was not found _exception_ ansible.module\_utils.errors.AnsibleValidationError(_message_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.errors.AnsibleValidationError "Link to this definition") Single argument spec validation error error\_message[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.errors.AnsibleValidationError.error_message "Link to this definition") The error message passed in when the exception was raised. _property_ msg[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.errors.AnsibleValidationError.msg "Link to this definition") The error message passed in when the exception was raised. _exception_ ansible.module\_utils.errors.AnsibleValidationErrorMultiple(_errors\=None_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.errors.AnsibleValidationErrorMultiple "Link to this definition") Multiple argument spec validation errors errors[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.errors.AnsibleValidationErrorMultiple.errors "Link to this definition") [`list`](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.14)") of [`AnsibleValidationError`](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.errors.AnsibleValidationError "ansible.module_utils.errors.AnsibleValidationError") objects _property_ msg[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.errors.AnsibleValidationErrorMultiple.msg "Link to this definition") The first message from the first error in `errors`. _property_ messages[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.errors.AnsibleValidationErrorMultiple.messages "Link to this definition") [`list`](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.14)") of each error message in `errors`. append(_error_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.errors.AnsibleValidationErrorMultiple.append "Link to this definition") Append a new error to `self.errors`. Only [`AnsibleValidationError`](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.errors.AnsibleValidationError "ansible.module_utils.errors.AnsibleValidationError") should be added. extend(_errors_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.errors.AnsibleValidationErrorMultiple.extend "Link to this definition") Append each item in `errors` to `self.errors`. Only [`AnsibleValidationError`](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.errors.AnsibleValidationError "ansible.module_utils.errors.AnsibleValidationError") should be added. _exception_ ansible.module\_utils.errors.AliasError(_message_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.errors.AliasError "Link to this definition") Error handling aliases _exception_ ansible.module\_utils.errors.ArgumentTypeError(_message_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.errors.ArgumentTypeError "Link to this definition") Error with parameter type _exception_ ansible.module\_utils.errors.ArgumentValueError(_message_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.errors.ArgumentValueError "Link to this definition") Error with parameter value _exception_ ansible.module\_utils.errors.DeprecationError(_message_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.errors.DeprecationError "Link to this definition") Error processing parameter deprecations _exception_ ansible.module\_utils.errors.ElementError(_message_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.errors.ElementError "Link to this definition") Error when validating elements _exception_ ansible.module\_utils.errors.MutuallyExclusiveError(_message_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.errors.MutuallyExclusiveError "Link to this definition") Mutually exclusive parameters were supplied _exception_ ansible.module\_utils.errors.NoLogError(_message_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.errors.NoLogError "Link to this definition") Error converting no\_log values _exception_ ansible.module\_utils.errors.RequiredByError(_message_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.errors.RequiredByError "Link to this definition") Error with parameters that are required by other parameters _exception_ ansible.module\_utils.errors.RequiredDefaultError(_message_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.errors.RequiredDefaultError "Link to this definition") A required parameter was assigned a default value _exception_ ansible.module\_utils.errors.RequiredError(_message_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.errors.RequiredError "Link to this definition") Missing a required parameter _exception_ ansible.module\_utils.errors.RequiredIfError(_message_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.errors.RequiredIfError "Link to this definition") Error with conditionally required parameters _exception_ ansible.module\_utils.errors.RequiredOneOfError(_message_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.errors.RequiredOneOfError "Link to this definition") Error with parameters where at least one is required _exception_ ansible.module\_utils.errors.RequiredTogetherError(_message_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.errors.RequiredTogetherError "Link to this definition") Error with parameters that are required together _exception_ ansible.module\_utils.errors.SubParameterTypeError(_message_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.errors.SubParameterTypeError "Link to this definition") Incorrect type for subparameter _exception_ ansible.module\_utils.errors.UnsupportedError(_message_)[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.errors.UnsupportedError "Link to this definition") Unsupported parameters were supplied --- # Community Code of Conduct — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * [Ansible Community Guide](https://docs.ansible.com/projects/ansible/latest/community/index.html) * [Getting started](https://docs.ansible.com/projects/ansible/latest/community/getting_started.html) * Community Code of Conduct * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/community/code_of_conduct.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * [Community Code of Conduct](https://docs.ansible.com/projects/ansible/latest/community/code_of_conduct.html#id1) [](https://docs.ansible.com/projects/ansible/latest/community/code_of_conduct.html#community-code-of-conduct "Link to this heading") ======================================================================================================================================================================================================================================================= Every community can be strengthened by a diverse variety of viewpoints, insights, opinions, skillsets, and skill levels. However, with diversity comes the potential for disagreement and miscommunication. The purpose of this Code of Conduct is to ensure that disagreements and differences of opinion are conducted respectfully and on their own merits, without personal attacks or other behavior that might create an unsafe or unwelcoming environment. These policies are not designed to be a comprehensive set of Things You Cannot Do. We ask that you treat your fellow community members with respect and courtesy, and in general, Don’t Be A Jerk. This Code of Conduct is meant to be followed in spirit as much as in letter and is not exhaustive. All Ansible events and participants therein are governed by this Code of Conduct and anti-harassment policy. We expect organizers to enforce these guidelines throughout all events, and we expect attendees, speakers, sponsors, and volunteers to help ensure a safe environment for our whole community. Specifically, this Code of Conduct covers participation in all Ansible-related forums and mailing lists, code and documentation contributions, public chat (Matrix, IRC), private correspondence, and public meetings. Ansible community members are… **Considerate** Contributions of every kind have far-ranging consequences. Just as your work depends on the work of others, decisions you make surrounding your contributions to the Ansible community will affect your fellow community members. You are strongly encouraged to take those consequences into account while making decisions. **Patient** Asynchronous communication can come with its own frustrations, even in the most responsive of communities. Please remember that our community is largely built on volunteered time, and that questions, contributions, and requests for support may take some time to receive a response. Repeated “bumps” or “reminders” in rapid succession are not good displays of patience. Additionally, it is considered poor manners to ping a specific person with general questions. Pose your question to the community as a whole, and wait patiently for a response. **Respectful** Every community inevitably has disagreements, but remember that it is possible to disagree respectfully and courteously. Disagreements are never an excuse for rudeness, hostility, threatening behavior, abuse (verbal or physical), or personal attacks. **Kind** Everyone should feel welcome in the Ansible community, regardless of their background. Please be courteous, respectful and polite to fellow community members. Do not make or post offensive comments related to skill level, gender, gender identity or expression, sexual orientation, disability, physical appearance, body size, race, or religion. Sexualized images or imagery, real or implied violence, intimidation, oppression, stalking, sustained disruption of activities, publishing the personal information of others without explicit permission to do so, unwanted physical contact, and unwelcome sexual attention are all strictly prohibited. Additionally, you are encouraged not to make assumptions about the background or identity of your fellow community members. **Inquisitive** The only stupid question is the one that does not get asked. We encourage our users to ask early and ask often. Rather than asking whether you can ask a question (the answer is always yes!), instead, simply ask your question. You are encouraged to provide as many specifics as possible. Code snippets in the form of Gists or other paste site links are almost always needed in order to get the most helpful answers. Refrain from pasting multiple lines of code directly into the chat channels - instead use gist.github.com or another paste site to provide code snippets. **Helpful** The Ansible community is committed to being a welcoming environment for all users, regardless of skill level. We were all beginners once upon a time, and our community cannot grow without an environment where new users feel safe and comfortable asking questions. It can become frustrating to answer the same questions repeatedly; however, community members are expected to remain courteous and helpful to all users equally, regardless of skill or knowledge level. Avoid providing responses that prioritize snideness and snark over useful information. At the same time, everyone is expected to read the provided documentation thoroughly. We are happy to answer questions, provide strategic guidance, and suggest effective workflows, but we are not here to do your job for you. [Anti-harassment policy](https://docs.ansible.com/projects/ansible/latest/community/code_of_conduct.html#id2) [](https://docs.ansible.com/projects/ansible/latest/community/code_of_conduct.html#anti-harassment-policy "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Harassment includes (but is not limited to) all of the following behaviors: * Offensive comments related to gender (including gender expression and identity), age, sexual orientation, disability, physical appearance, body size, race, and religion * Derogatory terminology including words commonly known to be slurs * Posting sexualized images or imagery in public spaces * Deliberate intimidation * Stalking * Posting others’ personal information without explicit permission * Sustained disruption of talks or other events * Inappropriate physical contact * Unwelcome sexual attention Participants asked to stop any harassing behavior are expected to comply immediately. Sponsors are also subject to the anti-harassment policy. In particular, sponsors should not use sexualized images, activities, or other material. Meetup organizing staff and other volunteer organizers should not use sexualized attire or otherwise create a sexualized environment at community events. In addition to the behaviors outlined above, continuing to behave a certain way after you have been asked to stop also constitutes harassment, even if that behavior is not specifically outlined in this policy. It is considerate and respectful to stop doing something after you have been asked to stop, and all community members are expected to comply with such requests immediately. [Policy violations](https://docs.ansible.com/projects/ansible/latest/community/code_of_conduct.html#id3) [](https://docs.ansible.com/projects/ansible/latest/community/code_of_conduct.html#policy-violations "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting [codeofconduct@ansible.com](mailto:codeofconduct%40ansible.com) , to anyone with administrative power in community chat (Admins or Moderators on Matrix, ops on IRC), or to the local organizers of an event. Meetup organizers are encouraged to prominently display points of contact for reporting unacceptable behavior at local events. If a participant engages in harassing behavior, the meetup organizers may take any action they deem appropriate. These actions may include but are not limited to warning the offender, expelling the offender from the event, and barring the offender from future community events. Organizers will be happy to help participants contact security or local law enforcement, provide escorts to an alternate location, or otherwise assist those experiencing harassment to feel safe for the duration of the meetup. We value the safety and well-being of our community members and want everyone to feel welcome at our events, both online and offline. We expect all participants, organizers, speakers, and attendees to follow these policies at all of our event venues and event-related social events. The Ansible Community Code of Conduct is licensed under the Creative Commons Attribution-Share Alike 3.0 license. Our Code of Conduct was adapted from Codes of Conduct of other open source projects, including: * Contributor Covenant * Elastic * The Fedora Project * OpenStack * Puppet Labs * Ubuntu --- # Working with dynamic inventory — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * [Building Ansible inventories](https://docs.ansible.com/projects/ansible/latest/inventory_guide/index.html) * Working with dynamic inventory * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/inventory_guide/intro_dynamic_inventory.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Working with dynamic inventory[](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_dynamic_inventory.html#working-with-dynamic-inventory "Link to this heading") ======================================================================================================================================================================================= If your Ansible inventory fluctuates over time, with hosts spinning up and shutting down in response to business demands, the static inventory solutions described in [How to build your inventory](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#inventory) will not serve your needs. You may need to track hosts from multiple sources: cloud providers, LDAP, [Cobbler](https://cobbler.github.io/) , and/or enterprise CMDB systems. Ansible integrates all of these options through a dynamic external inventory system. Ansible supports two ways to connect with external inventory: [Inventory plugins](https://docs.ansible.com/projects/ansible/latest/plugins/inventory.html#inventory-plugins) and inventory scripts. Inventory plugins take advantage of the most recent updates to the Ansible Core code. We recommend plugins over scripts for dynamic inventory. You can [write your own plugin](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_inventory.html#developing-inventory) to connect to additional dynamic inventory sources. You can still use inventory scripts if you choose. When we implemented inventory plugins, we ensured backwards compatibility through the script inventory plugin. The examples below illustrate how to use inventory scripts. If you prefer a GUI for handling dynamic inventory, the inventory database on AWX or [Red Hat Ansible Automation Platform](https://docs.ansible.com/projects/ansible/latest/reference_appendices/tower.html#ansible-platform) syncs with all your dynamic inventory sources, provides web and REST access to the results, and offers a graphical inventory editor. With a database record of all of your hosts, you can correlate past event history and see which hosts have had failures on their last playbook runs. [Inventory script example: Cobbler](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_dynamic_inventory.html#id3) [](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_dynamic_inventory.html#inventory-script-example-cobbler "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Ansible integrates seamlessly with [Cobbler](https://cobbler.github.io/) , a Linux installation server originally written by Michael DeHaan and now led by James Cammarata, who works for Ansible. While primarily used to kickoff OS installations and manage DHCP and DNS, Cobbler has a generic layer that can represent data for multiple configuration management systems (even at the same time) and serve as a ‘lightweight CMDB’. To tie your Ansible inventory to Cobbler, copy [this script](https://raw.githubusercontent.com/ansible-community/contrib-scripts/main/inventory/cobbler.py) to `/etc/ansible` and `chmod +x` the file. Run `cobblerd` any time you use Ansible and use the `-i` command line option (for example, `-i /etc/ansible/cobbler.py`) to communicate with Cobbler using Cobbler’s XMLRPC API. Add a `cobbler.ini` file in `/etc/ansible` so Ansible knows where the Cobbler server is and some cache improvements can be used. For example: \[cobbler\] # Set Cobbler's hostname or IP address host = http://127.0.0.1/cobbler\_api # API calls to Cobbler can be slow. For this reason, we cache the results of an API # call. Set this to the path you want cache files to be written to. Two files # will be written to this directory: # - ansible-cobbler.cache # - ansible-cobbler.index cache\_path = /tmp # The number of seconds a cache file is considered valid. After this many # seconds, a new API call will be made, and the cache file will be updated. cache\_max\_age = 900 First test the script by running `/etc/ansible/cobbler.py` directly. You should see some JSON data output, but it may not have anything in it just yet. Let’s explore what this does. In Cobbler, assume a scenario somewhat like the following: cobbler profile add \--name\=webserver \--distro\=CentOS6-x86\_64 cobbler profile edit \--name\=webserver \--mgmt-classes\="webserver" \--ksmeta\="a=2 b=3" cobbler system edit \--name\=foo \--dns-name\="foo.example.com" \--mgmt-classes\="atlanta" \--ksmeta\="c=4" cobbler system edit \--name\=bar \--dns-name\="bar.example.com" \--mgmt-classes\="atlanta" \--ksmeta\="c=5" In the example above, the system ‘foo.example.com’ is addressable by ansible directly, but is also addressable when using the group names ‘webserver’ or ‘atlanta’. Since Ansible uses SSH, it contacts system foo over ‘foo.example.com’, only, never just ‘foo’. Similarly, if you tried “ansible foo”, it would not find the system… but “ansible ‘foo\*’” would do, because the system DNS name starts with ‘foo’. The script provides more than host and group info. In addition, as a bonus, when the ‘setup’ module is run (which happens automatically when using playbooks), the variables ‘a’, ‘b’, and ‘c’ will all be auto-populated in the templates: \# file: /srv/motd.j2 Welcome, I am templated with a value of a={{ a }}, b={{ b }}, and c={{ c }} Which could be executed just like this: ansible webserver \-m setup ansible webserver \-m template \-a "src=/tmp/motd.j2 dest=/etc/motd" Note The name ‘webserver’ came from Cobbler, as did the variables for the config file. You can still pass in your own variables like normal in Ansible, but variables from the external inventory script will override any that have the same name. So, with the template above (`motd.j2`), this results in the following data being written to `/etc/motd` for system ‘foo’: Welcome, I am templated with a value of a=2, b=3, and c=4 And on system ‘bar’ (bar.example.com): Welcome, I am templated with a value of a=2, b=3, and c=5 And technically, though there is no major good reason to do it, this also works: ansible webserver \-m ansible.builtin.shell \-a "echo {{ a }}" So, in other words, you can use those variables in arguments/actions as well. [Other inventory scripts](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_dynamic_inventory.html#id4) [](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_dynamic_inventory.html#other-inventory-scripts "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- In Ansible 2.10 and later, inventory scripts moved to their associated collections. Many are now in the [ansible-community/contrib-scripts repository](https://github.com/ansible-community/contrib-scripts/tree/main/inventory) . We recommend you use [Inventory plugins](https://docs.ansible.com/projects/ansible/latest/plugins/inventory.html#inventory-plugins) instead. [Using inventory directories and multiple inventory sources](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_dynamic_inventory.html#id5) [](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_dynamic_inventory.html#using-inventory-directories-and-multiple-inventory-sources "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- If the location given to `-i` in Ansible is a directory (or as so configured in `ansible.cfg`), Ansible can use multiple inventory sources at the same time. When doing so, it is possible to mix both dynamic and statically managed inventory sources in the same ansible run. Instant hybrid cloud! In an inventory directory, executable files are treated as dynamic inventory sources and most other files as static sources. Files which end with any of the following are ignored: ~, .orig, .bak, .ini, .cfg, .retry, .pyc, .pyo You can replace this list with your own selection by configuring an `inventory_ignore_extensions` list in `ansible.cfg`, or setting the [`ANSIBLE_INVENTORY_IGNORE`](https://docs.ansible.com/projects/ansible/latest/reference_appendices/config.html#envvar-ANSIBLE_INVENTORY_IGNORE) environment variable. The value in either case must be a comma-separated list of patterns, as shown above. Any `group_vars` and `host_vars` subdirectories in an inventory directory are interpreted as expected, making inventory directories a powerful way to organize different sets of configurations. See [Passing multiple inventory sources](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#using-multiple-inventory-sources) for more information. [Static groups of dynamic groups](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_dynamic_inventory.html#id6) [](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_dynamic_inventory.html#static-groups-of-dynamic-groups "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- When defining groups of groups in the static inventory file, the child groups must also be defined in the static inventory file, otherwise ansible returns an error. If you want to define a static group of dynamic child groups, define the dynamic groups as empty in the static inventory file. For example: \[tag\_Name\_staging\_foo\] \[tag\_Name\_staging\_bar\] \[staging:children\] tag\_Name\_staging\_foo tag\_Name\_staging\_bar See also [How to build your inventory](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#intro-inventory) All about static inventory files [Communication](https://docs.ansible.com/projects/ansible/latest/community/communication.html#communication) Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide --- # Frequently Asked Questions — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * Frequently Asked Questions * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/reference_appendices/faq.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Frequently Asked Questions[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#frequently-asked-questions "Link to this heading") ==================================================================================================================================================================== Here are some commonly asked questions and their answers. Where did all the modules go?[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#where-did-all-the-modules-go "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- In July, 2019, we announced that collections would be the [future of Ansible content delivery](https://www.ansible.com/blog/the-future-of-ansible-content-delivery) . A collection is a distribution format for Ansible content that can include playbooks, roles, modules, and plugins. In Ansible 2.9 we added support for collections. In Ansible 2.10 we [extracted most modules from the main ansible/ansible repository](https://access.redhat.com/solutions/5295121) and placed them in [collections](https://docs.ansible.com/projects/ansible-core/devel/collections/index.html#list-of-collections) . Collections may be maintained by the Ansible team, by the Ansible community, or by Ansible partners. The [ansible/ansible repository](https://github.com/ansible/ansible) now contains the code for basic features and functions, such as copying module code to managed nodes. This code is also known as `ansible-core` (it was briefly called `ansible-base` for version 2.10). * To learn more about using collections, see [Using Ansible collections](https://docs.ansible.com/projects/ansible-core/devel/collections_guide/index.html#collections) . * To learn more about developing collections, see [Developing collections](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_collections.html#developing-collections) . * To learn more about contributing to existing collections, see the individual collection repository for guidelines, or see [Contributing to Ansible-maintained Collections](https://docs.ansible.com/projects/ansible/12/community/contributing_maintained_collections.html#contributing-maintained-collections "(in Ansible v12)") to contribute to one of the Ansible-maintained collections. Where did this specific module go?[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#where-did-this-specific-module-go "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- IF you are searching for a specific module, you can check the [runtime.yml](https://github.com/ansible/ansible/blob/devel/lib/ansible/config/ansible_builtin_runtime.yml) file, which lists the first destination for each module that we extracted from the main ansible/ansible repository. Some modules have moved again since then. You can also search on [Ansible Galaxy](https://galaxy.ansible.com/) or ask on one of our [chat channels](https://docs.ansible.com/projects/ansible-core/devel/community/communication.html#communication-irc) . How can I speed up Ansible on systems with slow disks?[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#how-can-i-speed-up-ansible-on-systems-with-slow-disks "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Ansible may feel sluggish on systems with slow disks, such as Raspberry PI. See [Ansible might be running slow if libyaml is not available](https://www.jeffgeerling.com/blog/2021/ansible-might-be-running-slow-if-libyaml-not-available) for hints on how to improve this. How can I set the PATH or any other environment variable for a task or entire play?[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#how-can-i-set-the-path-or-any-other-environment-variable-for-a-task-or-entire-play "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Setting environment variables can be done with the environment keyword. It can be used at the task or other levels in the play. shell: cmd: date environment: LANG=fr\_FR.UTF-8 hosts: servers environment: PATH: "{{ ansible\_env.PATH }}:/thingy/bin" SOME: value Note starting in 2.0.1 the setup task from `gather_facts` also inherits the environment directive from the play, you might need to use the `|default` filter to avoid errors if setting this at play level. How do I handle different machines needing different user accounts or ports to log in with?[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#how-do-i-handle-different-machines-needing-different-user-accounts-or-ports-to-log-in-with "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Setting inventory variables in the inventory file is the easiest way. For example, suppose these hosts have different usernames and ports: \[webservers\] asdf.example.com ansible\_port\=5000 ansible\_user=alice jkl.example.com ansible\_port\=5001 ansible\_user=bob You can also dictate the connection type to be used, if you want: \[testcluster\] localhost ansible\_connection\=local /path/to/chroot1 ansible\_connection\=chroot foo.example.com ansible\_connection\=paramiko You may also wish to keep these in group variables instead, or file them in a group\_vars/ file. See the rest of the documentation for more information about how to organize variables. How do I get ansible to reuse connections, enable Kerberized SSH, or have Ansible pay attention to my local SSH config file?[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#how-do-i-get-ansible-to-reuse-connections-enable-kerberized-ssh-or-have-ansible-pay-attention-to-my-local-ssh-config-file "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Switch your default connection type in the configuration file to `ssh`, or use `-c ssh` to use Native OpenSSH for connections instead of the python paramiko library. In Ansible 1.2.1 and later, `ssh` will be used by default if OpenSSH is new enough to support ControlPersist as an option. Paramiko is great for starting out, but the OpenSSH type offers many advanced options. You will want to run Ansible from a machine new enough to support ControlPersist, if you are using this connection type. You can still manage older clients. If you are using RHEL 6, CentOS 6, SLES 10 or SLES 11 the version of OpenSSH is still a bit old, so consider managing from a Fedora or openSUSE client even though you are managing older nodes, or just use paramiko. We keep paramiko as the default as if you are first installing Ansible on these enterprise operating systems, it offers a better experience for new users. How do I configure a jump host to access servers that I have no direct access to?[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#how-do-i-configure-a-jump-host-to-access-servers-that-i-have-no-direct-access-to "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can set a `ProxyCommand` in the `ansible_ssh_common_args` inventory variable. Any arguments specified in this variable are added to the sftp/scp/ssh command line when connecting to the relevant host(s). Consider the following inventory group: \[gatewayed\] foo ansible\_host\=192.0.2.1 bar ansible\_host\=192.0.2.2 You can create group\_vars/gatewayed.yml with the following contents: ansible\_ssh\_common\_args: '-o ProxyCommand="ssh \-W %h:%p \-q user@gateway.example.com"' Ansible will append these arguments to the command line when trying to connect to any hosts in the group `gatewayed`. (These arguments are used in addition to any `ssh_args` from `ansible.cfg`, so you do not need to repeat global `ControlPersist` settings in `ansible_ssh_common_args`.) Note that `ssh -W` is available only with OpenSSH 5.4 or later. With older versions, it is necessary to execute `nc %h:%p` or some equivalent command on the bastion host. With earlier versions of Ansible, it was necessary to configure a suitable `ProxyCommand` for one or more hosts in `~/.ssh/config`, or globally by setting `ssh_args` in `ansible.cfg`. How do I get Ansible to notice a dead target in a timely manner?[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#how-do-i-get-ansible-to-notice-a-dead-target-in-a-timely-manner "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can add `-o ServerAliveInterval=NumberOfSeconds` with the `ssh_args` parameter in [SSH connection plugin](https://docs.ansible.com/ansible-core/devel/collections/ansible/builtin/ssh_connection.html#parameter-ssh_args) . Without this option, SSH and therefore Ansible will wait until the TCP connection times out. Another solution is to add `ServerAliveInterval` into your global SSH configuration. A good value for `ServerAliveInterval` is up to you to decide; keep in mind that `ServerAliveCountMax=3` is the SSH default so any value you set will be tripled before terminating the SSH session. How do I speed up run of ansible for servers from cloud providers (EC2, openstack,.. )?[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#how-do-i-speed-up-run-of-ansible-for-servers-from-cloud-providers-ec2-openstack "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Don’t try to manage a fleet of machines of a cloud provider from your laptop. Rather connect to a management node inside this cloud provider first and run Ansible from there. How do I handle not having a Python interpreter at /usr/bin/python on a remote machine?[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#how-do-i-handle-not-having-a-python-interpreter-at-usr-bin-python-on-a-remote-machine "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- While you can write Ansible modules in any language, most Ansible modules are written in Python, including the ones central to letting Ansible work. By default, Ansible assumes it can find a **/usr/bin/python** on your remote system that is either Python2, version 2.6 or higher or Python3, 3.5 or higher. Setting the inventory variable `ansible_python_interpreter` on any host will tell Ansible to auto-replace the Python interpreter with that value instead. Thus, you can point to any Python you want on the system if **/usr/bin/python** on your system does not point to a compatible Python interpreter. Some platforms may only have Python 3 installed by default. If it is not installed as **/usr/bin/python**, you will need to configure the path to the interpreter through `ansible_python_interpreter`. Although most core modules will work with Python 3, there may be some special purpose ones which do not or you may encounter a bug in an edge case. As a temporary workaround you can install Python 2 on the managed host and configure Ansible to use that Python through `ansible_python_interpreter`. If there’s no mention in the module’s documentation that the module requires Python 2, you can also report a bug on our [bug tracker](https://github.com/ansible/ansible/issues) so that the incompatibility can be fixed in a future release. Do not replace the shebang lines of your python modules. Ansible will do this for you automatically at deploy time. Also, this works for ANY interpreter, for example ruby: `ansible_ruby_interpreter`, perl: `ansible_perl_interpreter`, and so on, so you can use this for custom modules written in any scripting language and control the interpreter location. Keep in mind that if you put `env` in your module shebang line (`#!/usr/bin/env `), this won’t work and will be evaluated as one string (including the space between `env` and `` space). Arguments are neither intended nor supported. How do I handle the package dependencies required by Ansible package dependencies during Ansible installation ?[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#how-do-i-handle-the-package-dependencies-required-by-ansible-package-dependencies-during-ansible-installation "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- While installing Ansible, sometimes you may encounter errors such as No package ‘libffi’ found or fatal error: Python.h: No such file or directory These errors are generally caused by the missing packages, which are dependencies of the packages required by Ansible. For example, libffi package is dependency of pynacl and paramiko (Ansible -> paramiko -> pynacl -> libffi). In order to solve these kinds of dependency issues, you might need to install required packages using the OS native package managers, such as yum, dnf, or apt, or as mentioned in the package installation guide. Refer to the documentation of the respective package for such dependencies and their installation methods. Common System Issues[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#common-system-issues "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------- ### Running in a virtualenv[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#running-in-a-virtualenv "Link to this heading") You can install Ansible into a virtualenv on the control node quite simply: $ virtualenv ansible $ source ./ansible/bin/activate $ pip install ansible If you want to run under Python 3 instead of Python 2 you may want to change that slightly: $ virtualenv \-p python3 ansible $ source ./ansible/bin/activate $ pip install ansible If you need to use any libraries which are not available through pip (for example, SELinux Python bindings on systems such as Red Hat Enterprise Linux or Fedora that have SELinux enabled), then you need to install them into the virtualenv. There are two methods: * When you create the virtualenv, specify `--system-site-packages` to make use of any libraries installed in the system’s Python: $ virtualenv ansible \--system-site-packages * Copy those files in manually from the system. For example, for SELinux bindings you might do: $ virtualenv ansible \--system-site-packages $ cp \-r \-v /usr/lib64/python3.\*/site-packages/selinux/ ./py3-ansible/lib64/python3.\*/site-packages/ $ cp \-v /usr/lib64/python3.\*/site-packages/\*selinux\*.so ./py3-ansible/lib64/python3.\*/site-packages/ ### Running on macOS as a control node[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#running-on-macos-as-a-control-node "Link to this heading") When executing Ansible on a system with macOS as a control node machine one might encounter the following error: > Error > > +\[\_\_NSCFConstantString initialize\] may have been in progress in another thread when fork() was called. We cannot safely call it or ignore it in the fork() child process. Crashing instead. Set a breakpoint on objc\_initializeAfterForkError to debug. ERROR! A worker was found in a dead state In general the recommended workaround is to set the following environment variable in your shell: > $ export OBJC\_DISABLE\_INITIALIZE\_FORK\_SAFETY\=YES ### Running on macOS as a target[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#running-on-macos-as-a-target "Link to this heading") When managing a system with macOS Monterey 12, macOS Ventura 13 or above over SSH, the following error can occur: > Error > > “eDSPermissionError” DS Error: -14120 (eDSPermissionError) This is a good indication that _Allow full disk access for remote users_ has not been enabled. See also For more details, check out [the official Apple user guide article](https://support.apple.com/guide/mac-help/mchlp1066/mac#mchlp1b6a98a) . ### Running on BSD[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#running-on-bsd "Link to this heading") See also [Managing BSD hosts with Ansible](https://docs.ansible.com/projects/ansible-core/devel/os_guide/intro_bsd.html#working-with-bsd) ### Running on Solaris[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#running-on-solaris "Link to this heading") By default, Solaris 10 and earlier run a non-POSIX shell which does not correctly expand the default tmp directory Ansible uses ( `~/.ansible/tmp`). If you see module failures on Solaris machines, this is likely the problem. There are several workarounds: * You can set `remote_tmp` to a path that will expand correctly with the shell you are using (see the plugin documentation for [C shell](https://docs.ansible.com/projects/ansible/2.9/plugins/shell/csh.html#csh-shell "(in Ansible v2.9)") , [fish shell](https://docs.ansible.com/projects/ansible/2.9/plugins/shell/fish.html#fish-shell "(in Ansible v2.9)") , and [Powershell](https://docs.ansible.com/projects/ansible-core/devel/collections/ansible/builtin/powershell_shell.html#powershell-shell) ). For example, in the ansible config file you can set: remote\_tmp\=$HOME/.ansible/tmp In Ansible 2.5 and later, you can also set it per-host in inventory like this: solaris1 ansible\_remote\_tmp\=$HOME/.ansible/tmp * You can set [ansible\_shell\_executable](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#ansible-shell-executable) to the path to a POSIX compatible shell. For instance, many Solaris hosts have a POSIX shell located at `/usr/xpg4/bin/sh` so you can set this in inventory like so: solaris1 ansible\_shell\_executable\=/usr/xpg4/bin/sh (bash, ksh, and zsh should also be POSIX compatible if you have any of those installed). ### Running on z/OS[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#running-on-z-os "Link to this heading") * Generally speaking, z/OS cannot be used as an Ansible control node. For more details, see [Using z/OS as a control node](https://docs.ansible.com/projects/ansible-core/devel/os_guide/intro_zos.html#zos-as-control-node) . * When the path to the Python interpreter is not found in the default location on the target host, the following error may result: Error /usr/bin/python: FSUM7351 not found Ansible requires a Python interpreter to execute modules on the remote host, and checks for it at the ‘default’ path `/usr/bin/python`. On z/OS, the Python 3 interpreter (from [IBM Open Enterprise SDK for Python](https://www.ibm.com/products/open-enterprise-python-zos) ) is often installed to a different path, typically something like: `/usr/lpp/cyp/v3r12/pyz`. The path to the python interpreter can be configured with the Ansible inventory variable `ansible_python_interpreter`. For example: zos1 ansible\_python\_interpreter:/usr/lpp/cyp/v3r12/pyz For more details, see: [How do I handle not having a Python interpreter at /usr/bin/python on a remote machine?](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#python-interpreters) . * When [ANSIBLE\_PIPELINING](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/config.html#ansible-pipelining) is not enabled or when Ansible pipelining is enabled but the `PYTHONSTDINENCODING` property is not correctly set, the following error may result. Error SyntaxError: Non-UTF-8 code starting with ‘\\x81’ in file on line 1, but no encoding declared; see [https://peps.python.org/pep-0263/](https://peps.python.org/pep-0263/) for details Note, the hex `'\x81'` below may vary depending source causing the error: When Ansible pipelining is enabled, Ansible passes all module code to the remote target through Python’s stdin pipe and runs it all in a single call. For more details on pipelining, see: [Pipelining](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_program_flow_modules.html#flow-pipelining) . Include the following in the environment for any tasks performed on z/OS managed nodes. PYTHONSTDINENCODING: "cp1047" * Certain language environment (LE) configurations enable automatic conversion and automatic file tagging functionality required by Python on z/OS systems ([IBM Open Enterprise SDK for Python](https://www.ibm.com/products/open-enterprise-python-zos) ). Include the following configurations when setting the remote environment for any z/OS managed nodes: \_BPXK\_AUTOCVT: "ON" \_CEE\_RUNOPTS: "FILETAG(AUTOCVT,AUTOTAG) POSIX(ON)" \_TAG\_REDIR\_ERR: "txt" \_TAG\_REDIR\_IN: "txt" \_TAG\_REDIR\_OUT: "txt" Ansible can be configured with remote environment variables in these options: > * inventory - inventory.yml, group\_vars/all.yml, or host\_vars/all.yml > > * playbook - `environment` variable at top of playbook. > > * block or task - `environment` key word. > For more details, see [Setting the remote environment](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_environment.html#playbooks-environment) . See also [Managing z/OS UNIX hosts with Ansible](https://docs.ansible.com/projects/ansible-core/devel/os_guide/intro_zos.html#working-with-zos) ### Running under fakeroot[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#running-under-fakeroot "Link to this heading") Some issues arise as `fakeroot` does not create a full nor POSIX compliant system by default. It is known that it will not correctly expand the default tmp directory Ansible uses (`~/.ansible/tmp`). If you see module failures, this is likely the problem. The simple workaround is to set `remote_tmp` to a path that will expand correctly (see documentation of the shell plugin you are using for specifics). For example, in the ansible config file (or through environment variable) you can set: remote\_tmp\=$HOME/.ansible/tmp What is the best way to make content reusable/redistributable?[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#what-is-the-best-way-to-make-content-reusable-redistributable "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- If you have not done so already, read all about “Roles” in the playbooks documentation. This helps you make playbook content self-contained, and works well with things like Git submodules for sharing content with others. If some of these plugin types look strange to you, see the API documentation for more details about ways Ansible can be extended. Where does the configuration file live and what can I configure in it?[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#where-does-the-configuration-file-live-and-what-can-i-configure-in-it "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- See [Configuring Ansible](https://docs.ansible.com/projects/ansible-core/devel/installation_guide/intro_configuration.html#intro-configuration) . How do I disable cowsay?[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#how-do-i-disable-cowsay "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------- If cowsay is installed, Ansible takes it upon itself to make your day happier when running playbooks. If you decide that you would like to work in a professional cow-free environment, you can either uninstall cowsay, set `nocows=1` in `ansible.cfg`, or set the [`ANSIBLE_NOCOWS`](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/config.html#envvar-ANSIBLE_NOCOWS) environment variable: export ANSIBLE\_NOCOWS=1 How do I see a list of all of the ansible\_ variables?[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#how-do-i-see-a-list-of-all-of-the-ansible-variables "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Ansible by default gathers “facts” about the machines under management, and these facts can be accessed in playbooks and in templates. To see a list of all of the facts that are available about a machine, you can run the `setup` module as an ad hoc action: ansible -m setup hostname This will print out a dictionary of all of the facts that are available for that particular host. You might want to pipe the output to a pager.This does NOT include inventory variables or internal ‘magic’ variables. See the next question if you need more than just ‘facts’. How do I see all the inventory variables defined for my host?[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#how-do-i-see-all-the-inventory-variables-defined-for-my-host "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- By running the following command, you can see inventory variables for a host: ansible-inventory --list --yaml How do I see all the variables specific to my host?[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#how-do-i-see-all-the-variables-specific-to-my-host "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- To see all host specific variables, which might include facts and other sources: ansible -m debug -a "var=hostvars\['hostname'\]" localhost Unless you are using a fact cache, you normally need to use a play that gathers facts first, for facts included in the task above. How do I loop over a list of hosts in a group, inside of a template?[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#how-do-i-loop-over-a-list-of-hosts-in-a-group-inside-of-a-template "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ A pretty common pattern is to iterate over a list of hosts inside of a host group, perhaps to populate a template configuration file with a list of servers. To do this, you can just access the “$groups” dictionary in your template, like this: {% for host in groups\['db\_servers'\] %} {{ host }} {% endfor %} If you need to access facts about these hosts, for example, the IP address of each hostname, you need to make sure that the facts have been populated. For example, make sure you have a play that talks to db\_servers: \- hosts: db\_servers tasks: \- debug: msg="doesn't matter what you do, just that they were talked to previously." Then you can use the facts inside your template, like this: {% for host in groups\['db\_servers'\] %} {{ hostvars\[host\]\['ansible\_eth0'\]\['ipv4'\]\['address'\] }} {% endfor %} How do I access a variable name programmatically?[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#how-do-i-access-a-variable-name-programmatically "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- An example may come up where we need to get the ipv4 address of an arbitrary interface, where the interface to be used may be supplied through a role parameter or other input. Variable names can be built by adding strings together using “~”, like so: {{ hostvars\[inventory\_hostname\]\['ansible\_' ~ which\_interface\]\['ipv4'\]\['address'\] }} The trick about going through hostvars is necessary because it is a dictionary of the entire namespace of variables. `inventory_hostname` is a magic variable that indicates the current host you are looping over in the host loop. In the example above, if your interface names have dashes, you must replace them with underscores: {{ hostvars\[inventory\_hostname\]\['ansible\_' ~ which\_interface | replace('\_', '-') \]\['ipv4'\]\['address'\] }} Also see [dynamic\_variables](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#dynamic-variables) . How do I access a group variable?[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#how-do-i-access-a-group-variable "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Technically, you don’t, Ansible does not really use groups directly. Groups are labels for host selection and a way to bulk assign variables, they are not a first class entity, Ansible only cares about Hosts and Tasks. That said, you could just access the variable by selecting a host that is part of that group, see [first\_host\_in\_a\_group](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#first-host-in-a-group) below for an example. How do I access a variable of the first host in a group?[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#how-do-i-access-a-variable-of-the-first-host-in-a-group "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- What happens if we want the ip address of the first webserver in the webservers group? Well, we can do that too. Note that if we are using dynamic inventory, which host is the ‘first’ may not be consistent, so you wouldn’t want to do this unless your inventory is static and predictable. (If you are using AWX or the [Red Hat Ansible Automation Platform](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/tower.html#ansible-platform) , it will use database order, so this isn’t a problem even if you are using cloud based inventory scripts). Anyway, here’s the trick: {{ hostvars\[groups\['webservers'\]\[0\]\]\['ansible\_eth0'\]\['ipv4'\]\['address'\] }} Notice how we’re pulling out the hostname of the first machine of the webservers group. If you are doing this in a template, you could use the Jinja2 ‘#set’ directive to simplify this, or in a playbook, you could also use set\_fact: \- set\_fact: headnode={{ groups\['webservers'\]\[0\] }} \- debug: msg={{ hostvars\[headnode\].ansible\_eth0.ipv4.address }} Notice how we interchanged the bracket syntax for dots – that can be done anywhere. How do I copy files recursively onto a target host?[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#how-do-i-copy-files-recursively-onto-a-target-host "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The `copy` module has a recursive parameter. However, take a look at the `synchronize` module if you want to do something more efficient for a large number of files. The `synchronize` module wraps rsync. See the module index for info on both of these modules. How do I access shell environment variables?[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#how-do-i-access-shell-environment-variables "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- **On control node machine :** Access existing variables from control node use the `env` lookup plugin. For example, to access the value of the HOME environment variable on the management machine: \--- \# ... vars: local\_home: "{{ lookup('env','HOME') }}" **On target machines :** Environment variables are available through facts in the `ansible_env` variable: {{ ansible\_env.HOME }} If you need to set environment variables for TASK execution, see [Setting the remote environment](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_environment.html#playbooks-environment) in the [Advanced Playbooks](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_special_topics.html#playbooks-special-topics) section. There are several ways to set environment variables on your target machines. You can use the [template](https://docs.ansible.com/projects/ansible-core/devel/collections/ansible/builtin/template_module.html#template-module) , [replace](https://docs.ansible.com/projects/ansible-core/devel/collections/ansible/builtin/replace_module.html#replace-module) , or [lineinfile](https://docs.ansible.com/projects/ansible-core/devel/collections/ansible/builtin/lineinfile_module.html#lineinfile-module) modules to introduce environment variables into files. The exact files to edit vary depending on your OS and distribution and local configuration. How do I generate encrypted passwords for the user module?[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#how-do-i-generate-encrypted-passwords-for-the-user-module "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Ansible ad hoc command is the easiest option: ansible all -i localhost, -m debug -a "msg={{ 'mypassword' | password\_hash('sha512', 'mysecretsalt') }}" The `mkpasswd` utility that is available on most Linux systems is also a great option: mkpasswd --method=sha-512 If this utility is not installed on your system (for example, you are using macOS) then you can still easily generate these passwords using Python. First, ensure that the [Passlib](https://foss.heptapod.net/python-libs/passlib/-/wikis/home) password hashing library is installed: pip install passlib Once the library is ready, SHA512 password values can then be generated as follows: python -c "from passlib.hash import sha512\_crypt; import getpass; print(sha512\_crypt.using(rounds=5000).hash(getpass.getpass()))" Use the integrated [Hashing and encrypting strings and passwords](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_filters.html#hash-filters) to generate a hashed version of a password. You shouldn’t put plaintext passwords in your playbook or host\_vars; instead, use [Using encrypted variables and files](https://docs.ansible.com/projects/ansible-core/devel/vault_guide/vault_using_encrypted_content.html#playbooks-vault) to encrypt sensitive data. In OpenBSD, a similar option is available in the base system called `encrypt (1)` Ansible allows dot notation and array notation for variables. Which notation should I use?[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#ansible-allows-dot-notation-and-array-notation-for-variables-which-notation-should-i-use "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The dot notation comes from Jinja and works fine for variables without special characters. If your variable contains dots (.), colons (:), or dashes (-), if a key begins and ends with two underscores, or if a key uses any of the known public attributes, it is safer to use the array notation. See [Using variables](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_variables.html#playbooks-variables) for a list of the known public attributes. item\[0\]\['checksum:md5'\] item\['section'\]\['2.1'\] item\['region'\]\['Mid-Atlantic'\] It is {{ temperature\['Celsius'\]\['-3'\] }} outside. Also array notation allows for dynamic variable composition, see [dynamic\_variables](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#dynamic-variables) . Another problem with ‘dot notation’ is that some keys can cause problems because they collide with attributes and methods of python dictionaries. * Example of incorrect syntax when `item` is a dictionary: item.update This variant causes a syntax error because `update()` is a Python method for dictionaries. * Example of correct syntax: item\['update'\] When is it unsafe to bulk-set task arguments from a variable?[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#when-is-it-unsafe-to-bulk-set-task-arguments-from-a-variable "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can set all of a task’s arguments from a dictionary-typed variable. This technique can be useful in some dynamic execution scenarios. However, it introduces a security risk. We do not recommend it, so Ansible issues a warning when you do something like this: #... vars: usermod\_args: name: testuser state: present update\_password: always tasks: \- user: '{{ usermod\_args }}' This particular example is safe. However, constructing tasks like this is risky because the parameters and values passed to `usermod_args` could be overwritten by malicious values in the `host facts` on a compromised target machine. To mitigate this risk: * set bulk variables at a level of precedence greater than `host facts` in the order of precedence found in [Variable precedence: where should I put a variable?](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_variables.html#ansible-variable-precedence) (the example above is safe because play vars take precedence over facts) * disable the [INJECT\_FACTS\_AS\_VARS](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/config.html#inject-facts-as-vars) configuration setting to prevent fact values from colliding with variables (this will also disable the original warning) Can I get training on Ansible?[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#can-i-get-training-on-ansible "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Yes! See our [services page](https://www.ansible.com/products/consulting) for information on our services and training offerings. Email [info@ansible.com](mailto:info%40ansible.com) for further details. We also offer free web-based training classes on a regular basis. See our [webinar page](https://www.ansible.com/resources/webinars-training) for more info on upcoming webinars. Is there a web interface / REST API / GUI?[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#is-there-a-web-interface-rest-api-gui "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Yes! The open-source web interface is Ansible AWX. The supported Red Hat product that makes Ansible even more powerful and easy to use is [Red Hat Ansible Automation Platform](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/tower.html#ansible-platform) . How do I keep secret data in my playbook?[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#how-do-i-keep-secret-data-in-my-playbook "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- If you would like to keep secret data in your Ansible content and still share it publicly or keep things in source control, see [Using encrypted variables and files](https://docs.ansible.com/projects/ansible-core/devel/vault_guide/vault_using_encrypted_content.html#playbooks-vault) . If you have a task that you don’t want to show the results or command given to it when using -v (verbose) mode, the following task or playbook attribute can be useful: \- name: secret task shell: /usr/bin/do\_something --value={{ secret\_value }} no\_log: True This can be used to keep verbose output but hide sensitive information from others who would otherwise like to be able to see the output. The `no_log` attribute can also apply to an entire play: \- hosts: all no\_log: True Though this will make the play somewhat difficult to debug. It is recommended that this be applied to single tasks only, once a playbook is completed. Note that the use of the `no_log` attribute does not prevent data from being shown when debugging Ansible itself through the [`ANSIBLE_DEBUG`](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/config.html#envvar-ANSIBLE_DEBUG) environment variable. When should I use {{ }}? Also, how to interpolate variables or dynamic variable names[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#when-should-i-use-also-how-to-interpolate-variables-or-dynamic-variable-names "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- A steadfast rule is ‘always use `{{ }}` except when `when:`’. Conditionals are always run through Jinja2 as to resolve the expression, so `when:`, `failed_when:` and `changed_when:` are always templated and you should avoid adding `{{ }}`. In most other cases you should always use the brackets, even if previously you could use variables without specifying (like `loop` or `with_` clauses), as this made it hard to distinguish between an undefined variable and a string. Another rule is ‘moustaches don’t stack’. We often see this: {{ somevar\_{{other\_var}} }} The above DOES NOT WORK as you expect, if you need to use a dynamic variable use the following as appropriate: {{ hostvars\[inventory\_hostname\]\['somevar\_' ~ other\_var\] }} For ‘non host vars’ you can use the [vars lookup](https://docs.ansible.com/projects/ansible-core/devel/collections/ansible/builtin/vars_lookup.html#vars-lookup) plugin: {{ lookup('vars', 'somevar\_' ~ other\_var) }} To determine if a keyword requires `{{ }}` or even supports templating, use `ansible-doc -t keyword `, this will return documentation on the keyword including a `template` field with the values `explicit` (requires `{{ }}`), `implicit` (assumes `{{ }}`, so no needed) or `static` (no templating supported, all characters will be interpreted literally) How do I get the original ansible\_host when I delegate a task?[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#how-do-i-get-the-original-ansible-host-when-i-delegate-a-task "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- As the documentation states, connection variables are taken from the `delegate_to` host so `ansible_host` is overwritten, but you can still access the original through `hostvars`: original\_host: "{{ hostvars\[inventory\_hostname\]\['ansible\_host'\] }}" This works for all overridden connection variables, like `ansible_user`, `ansible_port`, and so on. How do I fix ‘protocol error: file name does not match request’ when fetching a file?[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#how-do-i-fix-protocol-error-file-name-does-not-match-request-when-fetching-a-file "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Since release `7.9p1` of OpenSSH there is a [bug](https://bugzilla.mindrot.org/show_bug.cgi?id=2966) in the SCP client that can trigger this error on the Ansible control node when using SCP as the file transfer mechanism: Error failed to transfer file to /tmp/ansible/file.txtrnprotocol error: file name does not match request In these releases, SCP tries to validate that the path of the file to fetch matches the requested path. The validation fails if the remote file name requires quotes to escape spaces or non-ascii characters in its path. To avoid this error: * Ensure you are using SFTP, which is the optimal transfer method for security, speed and reliability. Check that you are doing one of the following: * Rely on the default setting, which is `smart` — this works if `ssh_transfer_method` is not explicitly set anywhere * Set a [host variable](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#host-variables) or [group variable](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#group-variables) in inventory: `ansible_ssh_transfer_method: smart` * Set an environment variable on your control node: `export ANSIBLE_SSH_TRANSFER_METHOD=smart` * Pass an environment variable when you run Ansible: `ANSIBLE_SSH_TRANSFER_METHOD=smart ansible-playbook` * Modify your `ansible.cfg` file: add `ssh_transfer_method=smart` to the `[ssh_connection]` section. The `smart` setting attempts to use `sftp` for the transfer, then falls back to `scp` and then `dd`. If you want the transfer to fail if SFTP is not available, add `ssh_transfer_method=sftp` to the `[ssh_connection]` section. * If you must use SCP, set the `-T` arg to tell the SCP client to ignore path validation. You can do this in one of three ways: * Set a [host variable](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#host-variables) or [group variable](https://docs.ansible.com/projects/ansible-core/devel/inventory_guide/intro_inventory.html#group-variables) : `ansible_scp_extra_args=-T`, * Export or pass an environment variable: `ANSIBLE_SCP_EXTRA_ARGS=-T` * Modify your `ansible.cfg` file: add `scp_extra_args=-T` to the `[ssh_connection]` section Note If you see an `invalid argument` error when using `-T`, then your SCP client is not performing file name validation and will not trigger this error. Does Ansible support multiple factor authentication 2FA/MFA/biometrics/finterprint/usbkey/OTP/…[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#does-ansible-support-multiple-factor-authentication-2fa-mfa-biometrics-finterprint-usbkey-otp "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ No, Ansible is designed to execute multiple tasks against multiple targets, minimizing user interaction. As with most automation tools, it is not compatible with interactive security systems designed to handle human interaction. Most of these systems require a secondary prompt per target, which prevents scaling to thousands of targets. They also tend to have very short expiration periods so it requires frequent reauthorization, also an issue with many hosts and/or a long set of tasks. In such environments we recommend securing around Ansible’s execution but still allowing it to use an ‘automation user’ that does not require such measures. With AWX or the [Red Hat Ansible Automation Platform](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/tower.html#ansible-platform) , administrators can set up RBAC access to inventory, along with managing credentials and job execution. The ‘validate’ option is not enough for my needs, what do I do?[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#the-validate-option-is-not-enough-for-my-needs-what-do-i-do "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ Many Ansible modules that create or update files have a `validate` option that allows you to abort the update if the validation command fails. This uses the temporary file Ansible creates before doing the final update. In many cases this does not work since the validation tools for the specific application require either specific names, multiple files or some other factor that is not present in this simple feature. For these cases you have to handle the validation and restoration yourself. The following is a simple example of how to do this with block/rescue and backups, which most file based modules also support: \- name: maintain config and backout if validation after change fails block: \- name: do the actual update, works with copy, lineinfile and any action that allows for \`backup\`. template: src=template.j2 dest=/x/y/z backup=yes moreoptions=stuff register: updated \- name: run validation, this will change a lot as needed. We assume it returns an error when not passing, use \`failed\_when\` if otherwise. shell: run\_validation\_commmand become: true become\_user: requiredbyapp environment: WEIRD\_REQUIREMENT: 1 when: updated is changed rescue: \- name: restore backup file to original, in the hope the previous configuration was working. copy: remote\_src: true dest: /x/y/z src: "{{ updated\['backup\_file'\] }}" when: updated is changed always: \- name: We choose to always delete backup, but could copy or move, or only delete in rescue. file: path: "{{ updated\['backup\_file'\] }}" state: absent when: updated is changed How do I submit a change to the documentation?[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#how-do-i-submit-a-change-to-the-documentation "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Documentation for Ansible is kept in the [ansible/ansible-documentation](https://github.com/ansible/ansible-documentation) project Git repository. See [Contributing to the Ansible Documentation](https://docs.ansible.com/projects/ansible-core/devel/community/documentation_contributions.html#community-documentation-contributions) for details. What is the difference between `ansible.legacy` and `ansible.builtin` collections?[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#what-is-the-difference-between-ansible-legacy-and-ansible-builtin-collections "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Neither is a real collection. They are virtually constructed by the core engine (synthetic collections). The `ansible.builtin` collection only refers to plugins that ship with `ansible-core`. The `ansible.legacy` collection is a superset of `ansible.builtin` (you can reference the plugins from builtin through `ansible.legacy`). You also get the ability to add ‘custom’ plugins in the [configured paths and adjacent directories](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/overview_architecture.html#ansible-search-path) , with the ability to override the builtin plugins that have the same name. Also, `ansible.legacy` is what you get by default when you do not specify an FQCN. So this: > \- shell: echo hi Is really equivalent to: > \- ansible.legacy.shell: echo hi Though, if you do not override the `shell` module, you can also just write it as `ansible.builtin.shell`, since legacy will resolve to the builtin collection. I don’t see my question here[](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/faq.html#i-don-t-see-my-question-here "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ If you have not found an answer to your questions, ask the community! Visit the [Ansible communication guide](https://docs.ansible.com/projects/ansible-core/devel/community/communication.html#communication) for details. See also [Working with playbooks](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks.html#working-with-playbooks) An introduction to playbooks [Ansible tips and tricks](https://docs.ansible.com/projects/ansible-core/devel/tips_tricks/index.html#playbooks-best-practices) Tips and tricks for playbooks [Communication](https://docs.ansible.com/projects/ansible-core/devel/community/communication.html#communication) Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide --- # Protecting sensitive data with Ansible vault — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * Protecting sensitive data with Ansible vault * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/vault_guide/index.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Protecting sensitive data with Ansible vault[](https://docs.ansible.com/projects/ansible/latest/vault_guide/index.html#protecting-sensitive-data-with-ansible-vault "Link to this heading") ============================================================================================================================================================================================= Note **Making Open Source More Inclusive** 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) . Welcome to the Ansible vault documentation. Ansible vault provides a way to encrypt and manage sensitive data such as passwords. This guide introduces you to Ansible vault and covers the following topics: * Managing vault passwords. * Encrypting content and files with Ansible vault. * Using encrypted variables and files. * [Ansible Vault](https://docs.ansible.com/projects/ansible/latest/vault_guide/vault.html) * [Managing vault passwords](https://docs.ansible.com/projects/ansible/latest/vault_guide/vault_managing_passwords.html) * [Choosing between a single password and multiple passwords](https://docs.ansible.com/projects/ansible/latest/vault_guide/vault_managing_passwords.html#choosing-between-a-single-password-and-multiple-passwords) * [Managing multiple passwords with vault IDs](https://docs.ansible.com/projects/ansible/latest/vault_guide/vault_managing_passwords.html#managing-multiple-passwords-with-vault-ids) * [Storing and accessing vault passwords](https://docs.ansible.com/projects/ansible/latest/vault_guide/vault_managing_passwords.html#storing-and-accessing-vault-passwords) * [Encrypting content with Ansible Vault](https://docs.ansible.com/projects/ansible/latest/vault_guide/vault_encrypting_content.html) * [Encrypting individual variables with Ansible Vault](https://docs.ansible.com/projects/ansible/latest/vault_guide/vault_encrypting_content.html#encrypting-individual-variables-with-ansible-vault) * [Encrypting files with Ansible Vault](https://docs.ansible.com/projects/ansible/latest/vault_guide/vault_encrypting_content.html#encrypting-files-with-ansible-vault) * [Using encrypted variables and files](https://docs.ansible.com/projects/ansible/latest/vault_guide/vault_using_encrypted_content.html) * [Passing a single password](https://docs.ansible.com/projects/ansible/latest/vault_guide/vault_using_encrypted_content.html#passing-a-single-password) * [Passing vault IDs](https://docs.ansible.com/projects/ansible/latest/vault_guide/vault_using_encrypted_content.html#passing-vault-ids) * [Passing multiple vault passwords](https://docs.ansible.com/projects/ansible/latest/vault_guide/vault_using_encrypted_content.html#passing-multiple-vault-passwords) * [Using `--vault-id` without a vault ID](https://docs.ansible.com/projects/ansible/latest/vault_guide/vault_using_encrypted_content.html#using-vault-id-without-a-vault-id) * [Configuring defaults for using encrypted content](https://docs.ansible.com/projects/ansible/latest/vault_guide/vault_using_encrypted_content.html#configuring-defaults-for-using-encrypted-content) * [Setting a default vault ID](https://docs.ansible.com/projects/ansible/latest/vault_guide/vault_using_encrypted_content.html#setting-a-default-vault-id) * [Setting a default password source](https://docs.ansible.com/projects/ansible/latest/vault_guide/vault_using_encrypted_content.html#setting-a-default-password-source) * [When are encrypted files made visible?](https://docs.ansible.com/projects/ansible/latest/vault_guide/vault_using_encrypted_content.html#when-are-encrypted-files-made-visible) * [Format of files encrypted with Ansible Vault](https://docs.ansible.com/projects/ansible/latest/vault_guide/vault_using_encrypted_content.html#format-of-files-encrypted-with-ansible-vault) * [Ansible Vault payload format 1.1 - 1.2](https://docs.ansible.com/projects/ansible/latest/vault_guide/vault_using_encrypted_content.html#ansible-vault-payload-format-1-1-1-2) --- # Using Ansible command line tools — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * Using Ansible command line tools * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/command_guide/index.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Using Ansible command line tools[](https://docs.ansible.com/projects/ansible/latest/command_guide/index.html#using-ansible-command-line-tools "Link to this heading") ======================================================================================================================================================================= Note **Making Open Source More Inclusive** 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) . Welcome to the guide for using Ansible command line tools. Ansible provides ad hoc commands and several utilities for performing various operations and automation tasks. * [Introduction to ad hoc commands](https://docs.ansible.com/projects/ansible/latest/command_guide/intro_adhoc.html) * [Why use ad hoc commands?](https://docs.ansible.com/projects/ansible/latest/command_guide/intro_adhoc.html#why-use-ad-hoc-commands) * [Use cases for ad hoc tasks](https://docs.ansible.com/projects/ansible/latest/command_guide/intro_adhoc.html#use-cases-for-ad-hoc-tasks) * [Working with command line tools](https://docs.ansible.com/projects/ansible/latest/command_guide/command_line_tools.html) * [ansible](https://docs.ansible.com/projects/ansible/latest/cli/ansible.html) * [ansible-config](https://docs.ansible.com/projects/ansible/latest/cli/ansible-config.html) * [ansible-console](https://docs.ansible.com/projects/ansible/latest/cli/ansible-console.html) * [ansible-doc](https://docs.ansible.com/projects/ansible/latest/cli/ansible-doc.html) * [ansible-galaxy](https://docs.ansible.com/projects/ansible/latest/cli/ansible-galaxy.html) * [ansible-inventory](https://docs.ansible.com/projects/ansible/latest/cli/ansible-inventory.html) * [ansible-playbook](https://docs.ansible.com/projects/ansible/latest/cli/ansible-playbook.html) * [ansible-pull](https://docs.ansible.com/projects/ansible/latest/cli/ansible-pull.html) * [ansible-vault](https://docs.ansible.com/projects/ansible/latest/cli/ansible-vault.html) * [Ansible CLI cheatsheet](https://docs.ansible.com/projects/ansible/latest/command_guide/cheatsheet.html) * [ansible-playbook](https://docs.ansible.com/projects/ansible/latest/command_guide/cheatsheet.html#ansible-playbook) * [ansible-galaxy](https://docs.ansible.com/projects/ansible/latest/command_guide/cheatsheet.html#ansible-galaxy) * [ansible](https://docs.ansible.com/projects/ansible/latest/command_guide/cheatsheet.html#ansible) * [ansible-doc](https://docs.ansible.com/projects/ansible/latest/command_guide/cheatsheet.html#ansible-doc) See also [Ansible Navigator](https://ansible.readthedocs.io/projects/navigator/) A command-line tool and a TUI that provides a convenient user interface for most of the native Ansible command-line utilities and allows to run Ansible automation content inside containers ([Execution Environments](https://docs.ansible.com/projects/ansible/latest/getting_started_ee/index.html#getting-started-ee-index) ) --- # Maintainer responsibilities — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * [Ansible Collections Contributor Guide](https://docs.ansible.com/projects/ansible/latest/community/contributions_collections.html) * [Guidelines for collection maintainers](https://docs.ansible.com/projects/ansible/latest/community/maintainers.html) * Maintainer responsibilities * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/community/maintainers_guidelines.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Maintainer responsibilities[](https://docs.ansible.com/projects/ansible/latest/community/maintainers_guidelines.html#maintainer-responsibilities "Link to this heading") ========================================================================================================================================================================== This document provides guidance for: * Contributors to collections who want to join maintainer teams. * Collection maintainers seeking to understand their roles better. This document defines the role of an Ansible collection maintainer, outlines their responsibilities, and describes the process for becoming one. [Collection maintainer definition](https://docs.ansible.com/projects/ansible/latest/community/maintainers_guidelines.html#id2) [](https://docs.ansible.com/projects/ansible/latest/community/maintainers_guidelines.html#collection-maintainer-definition "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- An Ansible collection maintainer, or simply maintainer, is a contributor who: * Makes significant and regular contributions to a project. * Demonstrates expertise in the area the collection automates. * Earns the community’s trust. To fulfill their duties, maintainers have `write` or higher access to the collection. [Maintainer responsibilities](https://docs.ansible.com/projects/ansible/latest/community/maintainers_guidelines.html#id3) [](https://docs.ansible.com/projects/ansible/latest/community/maintainers_guidelines.html#id1 "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Collection maintainers perform the following tasks: * Act in accordance with the [Community Code of Conduct](https://docs.ansible.com/projects/ansible/latest/community/code_of_conduct.html#code-of-conduct) . * Subscribe to the repository they maintain. In GitHub, click Watch > All activity. * Keep the `README`, development guidelines, and other general [Maintaining good collection documentation](https://docs.ansible.com/projects/ansible/latest/community/maintainers_guidelines.html#maintainer-documentation) current. * Review and commit changes from other contributors using the [Review checklist for collection PRs](https://docs.ansible.com/projects/ansible/latest/community/collection_contributors/collection_reviewing.html#review-checklist) . * [Backport](https://docs.ansible.com/projects/ansible/latest/community/maintainers_workflow.html#backporting) changes to stable branches. * [Plan and perform releases](https://docs.ansible.com/projects/ansible/latest/community/collection_contributors/collection_releasing.html#releasing) . * Ensure the collection adheres to the [Ansible community package collections requirements](https://docs.ansible.com/projects/ansible/latest/community/collection_contributors/collection_requirements.html#collections-requirements) . * Track changes announced through the [news-for-maintainers](https://forum.ansible.com/tag/news-for-maintainers) forum tag. Click the `Bell` button to subscribe. Update the collection accordingly. * [Build a healthy community](https://docs.ansible.com/projects/ansible/latest/community/maintainers_guidelines.html#expanding-community) to increase the number of active contributors and maintainers for collections. Multiple maintainers can divide these responsibilities among themselves. [Becoming a maintainer](https://docs.ansible.com/projects/ansible/latest/community/maintainers_guidelines.html#id4) [](https://docs.ansible.com/projects/ansible/latest/community/maintainers_guidelines.html#becoming-a-maintainer "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- If you are interested in becoming a maintainer and meet the [requirements](https://docs.ansible.com/projects/ansible/latest/community/maintainers_guidelines.html#maintainer-requirements) , nominate yourself. You can also nominate another person by following these steps: 1. Create a GitHub issue in the relevant repository. 2. If you receive no response, message the [Red Hat Ansible Community Engineering Team](https://forum.ansible.com/g/CommunityEngTeam) on the [Ansible forum](https://forum.ansible.com/) . [Communicating as a maintainer](https://docs.ansible.com/projects/ansible/latest/community/maintainers_guidelines.html#id5) [](https://docs.ansible.com/projects/ansible/latest/community/maintainers_guidelines.html#communicating-as-a-maintainer "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Maintainers communicate with the community through the channels listed in the [Ansible communication guide](https://docs.ansible.com/projects/ansible/latest/community/communication.html#communication) . [Establishing working group communication](https://docs.ansible.com/projects/ansible/latest/community/maintainers_guidelines.html#id6) [](https://docs.ansible.com/projects/ansible/latest/community/maintainers_guidelines.html#establishing-working-group-communication "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Working groups rely on efficient communication. As a maintainer, you can establish communication for your working groups using these techniques: * Find and join an existing [forum group](https://forum.ansible.com/g) and use tags that suit your project. * If no suitable options exist, [request them](https://forum.ansible.com/t/working-groups-things-you-can-ask-for/175) . * Provide working group details and chat room links in the contributor section of your project’s `README.md`. * Encourage contributors to join the forum group and use appropriate tags. [Participating in community topics](https://docs.ansible.com/projects/ansible/latest/community/maintainers_guidelines.html#id7) [](https://docs.ansible.com/projects/ansible/latest/community/maintainers_guidelines.html#participating-in-community-topics "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The Community and the [Steering Committee](https://docs.ansible.com/projects/ansible/latest/community/steering/community_steering_committee.html#steering-responsibilities) discuss and vote on [community topics](https://docs.ansible.com/projects/ansible/latest/community/steering/community_steering_committee.html#creating-community-topic) asynchronously. These topics impact the entire project or its components, including collections and packaging. Share your opinion and vote on the topics to help the community make informed decisions. Expanding the collection community[](https://docs.ansible.com/projects/ansible/latest/community/maintainers_guidelines.html#expanding-the-collection-community "Link to this heading") ======================================================================================================================================================================================== You can expand the community around your collection in the following ways: * Explicitly state in your `README` that the collection welcomes new maintainers and contributors. * Give newcomers a positive first experience. * Invite contributors to join forum groups and subscribe to tags related to your project. * Maintain [good documentation](https://docs.ansible.com/projects/ansible/latest/community/maintainers_guidelines.html#maintainer-documentation) with guidelines for new contributors. * Make people feel welcome personally and individually. Greet and thank them. * Use labels to identify easy fixes and leave non-critical easy fixes to newcomers. * Offer help explicitly. * Include quick ways contributors can help and provide contributor documentation references in your `README`. * Be responsive in issues, pull requests (PRs), and other communication channels. * Conduct PR days regularly. * Maintain a zero-tolerance policy toward behavior that violates the [Community Code of Conduct](https://docs.ansible.com/projects/ansible/latest/community/code_of_conduct.html#code-of-conduct) . \* Include information about how people can report code of conduct violations in your `README` and `CONTRIBUTING` files. * Look for new maintainers among active contributors. Maintaining good collection documentation[](https://docs.ansible.com/projects/ansible/latest/community/maintainers_guidelines.html#maintaining-good-collection-documentation "Link to this heading") ====================================================================================================================================================================================================== Ensure the collection documentation meets these criteria: * It is up-to-date. * It matches the [Ansible documentation style guide](https://docs.ansible.com/projects/ansible/latest/dev_guide/style_guide/index.html#style-guide) . * Collection module and plugin documentation adheres to the [Ansible documentation format](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_documenting.html#module-documenting) . * Collection user guides follow the [Collection documentation format](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_collections_structure.html#collections-doc-dir) . * Repository files include at least a `README` and `CONTRIBUTING` file. * The `README` file contains all sections from [collection\_template/README.md](https://github.com/ansible-collections/collection_template/blob/main/README.md) . * The `CONTRIBUTING` file includes all details or links to details on how new or continuing contributors can contribute to your collection. --- # Using Ansible collections — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * Using Ansible collections * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/collections_guide/index.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Using Ansible collections[](https://docs.ansible.com/projects/ansible/latest/collections_guide/index.html#using-ansible-collections "Link to this heading") ============================================================================================================================================================= Note **Making Open Source More Inclusive** 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) . Welcome to the Ansible guide for working with collections. Collections are a distribution format for Ansible content that can include playbooks, roles, modules, and plugins. You can install and use collections through a distribution server, such as Ansible Galaxy, or a Pulp 3 Galaxy server. * [Installing collections](https://docs.ansible.com/projects/ansible/latest/collections_guide/collections_installing.html) * [Installing collections in containers](https://docs.ansible.com/projects/ansible/latest/collections_guide/collections_installing.html#installing-collections-in-containers) * [Installing collections with `ansible-galaxy`](https://docs.ansible.com/projects/ansible/latest/collections_guide/collections_installing.html#installing-collections-with-ansible-galaxy) * [Installing collections with signature verification](https://docs.ansible.com/projects/ansible/latest/collections_guide/collections_installing.html#installing-collections-with-signature-verification) * [Installing an older version of a collection](https://docs.ansible.com/projects/ansible/latest/collections_guide/collections_installing.html#installing-an-older-version-of-a-collection) * [Install multiple collections with a requirements file](https://docs.ansible.com/projects/ansible/latest/collections_guide/collections_installing.html#install-multiple-collections-with-a-requirements-file) * [Downloading a collection for offline use](https://docs.ansible.com/projects/ansible/latest/collections_guide/collections_installing.html#downloading-a-collection-for-offline-use) * [Installing collections adjacent to playbooks](https://docs.ansible.com/projects/ansible/latest/collections_guide/collections_installing.html#installing-collections-adjacent-to-playbooks) * [Installing a collection from source files](https://docs.ansible.com/projects/ansible/latest/collections_guide/collections_installing.html#installing-a-collection-from-source-files) * [Installing a collection from a Git repository](https://docs.ansible.com/projects/ansible/latest/collections_guide/collections_installing.html#installing-a-collection-from-a-git-repository) * [Configuring the `ansible-galaxy` client](https://docs.ansible.com/projects/ansible/latest/collections_guide/collections_installing.html#configuring-the-ansible-galaxy-client) * [Removing a collection](https://docs.ansible.com/projects/ansible/latest/collections_guide/collections_installing.html#removing-a-collection) * [Downloading collections](https://docs.ansible.com/projects/ansible/latest/collections_guide/collections_downloading.html) * [Listing collections](https://docs.ansible.com/projects/ansible/latest/collections_guide/collections_listing.html) * [Verifying collections](https://docs.ansible.com/projects/ansible/latest/collections_guide/collections_verifying.html) * [Verifying collections with `ansible-galaxy`](https://docs.ansible.com/projects/ansible/latest/collections_guide/collections_verifying.html#verifying-collections-with-ansible-galaxy) * [Verifying signed collections](https://docs.ansible.com/projects/ansible/latest/collections_guide/collections_verifying.html#verifying-signed-collections) * [Using collections in a playbook](https://docs.ansible.com/projects/ansible/latest/collections_guide/collections_using_playbooks.html) * [Simplifying module names with the `collections` keyword](https://docs.ansible.com/projects/ansible/latest/collections_guide/collections_using_playbooks.html#simplifying-module-names-with-the-collections-keyword) * [Using `collections` in roles](https://docs.ansible.com/projects/ansible/latest/collections_guide/collections_using_playbooks.html#using-collections-in-roles) * [Using `collections` in playbooks](https://docs.ansible.com/projects/ansible/latest/collections_guide/collections_using_playbooks.html#using-collections-in-playbooks) * [Using a playbook from a collection](https://docs.ansible.com/projects/ansible/latest/collections_guide/collections_using_playbooks.html#using-a-playbook-from-a-collection) * [Collections index](https://docs.ansible.com/projects/ansible/latest/collections_guide/collections_index.html) --- # Ansible-core 2.19 Porting Guide — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * [Ansible Core Porting Guides](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/core_porting_guides.html) * Ansible-core 2.19 Porting Guide * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/porting_guides/porting_guide_core_2.19.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * [Ansible-core 2.19 Porting Guide](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id3) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#ansible-core-2-19-porting-guide "Link to this heading") ===================================================================================================================================================================================================================================================================================================== This section discusses the behavioral changes between `ansible-core` 2.18 and `ansible-core` 2.19. It is intended to assist in updating your playbooks, plugins, and other parts of your Ansible infrastructure so they will work with this version of Ansible. Review this page and the [ansible-core Changelog for 2.19](https://github.com/ansible/ansible/blob/stable-2.19/changelogs/CHANGELOG-v2.19.rst) to understand necessary changes. This document is part of a collection on porting. The complete list of porting guides can be found at [porting guides](https://docs.ansible.com/projects/ansible/2.9/porting_guides/porting_guides.html#porting-guides "(in Ansible v2.9)") . [Introduction](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id4) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#introduction "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- This release includes an overhaul of the templating system and a new feature dubbed Data Tagging. These changes enable reporting of numerous problematic behaviors that went undetected in previous releases, with wide-ranging positive effects on security, performance, and user experience. Backward compatibility has been preserved where practical, but some breaking changes were necessary. This guide describes some common problem scenarios with example content, error messages, and suggested solutions. We recommend you test your playbooks and roles in a staging environment with this release to determine where you may need to make changes. [Playbook](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id5) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#playbook "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [Broken Conditionals](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id6) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#broken-conditionals "Link to this heading") Broken conditionals occur when the input expression or template is not a string, or the result is not a boolean. Python and Jinja provide implicit “truthy” evaluation of most non-empty non-boolean values in conditional expressions. While sometimes desirable for brevity, truthy conditional evaluation often masks serious logic errors in playbooks that could not be reliably detected by previous versions of `ansible-core`. Changes to templating in this release detects non-boolean conditionals during expression evaluation and reports an error by default. The error can be temporarily reduced to a warning with the `ALLOW_BROKEN_CONDITIONALS` config setting. The following examples are derived from broken conditionals that masked logic errors in actual playbooks. #### [Example - implicit boolean conversion](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id7) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#example-implicit-boolean-conversion "Link to this heading") This expression relies on an implicit truthy evaluation of `inventory_hostname`. An explicit predicate with a boolean result, such as `| length > 0` or `is truthy`, should be used instead. \- assert: that: inventory\_hostname The error reported is: Conditional result was 'localhost' of type 'str', which evaluates to True. Conditionals must have a boolean result. This can be resolved by using an explicit boolean conversion: \- assert: that: inventory\_hostname | length > 0 #### [Example - unintentional truthy conditional](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id8) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#example-unintentional-truthy-conditional "Link to this heading") The second part of this conditional is erroneously quoted. The quoted part becomes the expression result (evaluated as truthy), so the expression can never be `False`. \- assert: that: inventory\_hostname is defined and 'inventory\_hostname | length > 0' The error reported is: Conditional result was 'inventory\_hostname | length > 0' of type 'str', which evaluates to True. Conditionals must have a boolean result. This can be resolved by removing the erroneous quotes: \- assert: that: inventory\_hostname is defined and inventory\_hostname | length > 0 #### [Example - expression syntax error](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id9) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#example-expression-syntax-error "Link to this heading") Previous Ansible releases could mask some expression syntax errors as a truthy result. \- assert: that: 1 == 2, \# ^ invalid comma The error reported is: Syntax error in expression: chunk after expression This can be resolved by removing the invalid comma after the expression. #### [Example - Jinja order of operations](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id10) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#example-jinja-order-of-operations "Link to this heading") This expression uses the `~` concatenation operator, which is evaluated after the `contains` test. The result is always a non-empty string, which is truthy. \- assert: that: inventory\_hostname is contains "local" ~ "host" The error reported is: Conditional result was 'Truehost' of type 'str', which evaluates to True. Conditionals must have a boolean result. This can be resolved by inserting parentheses to resolve the concatenation operation before the `contains` test: \- assert: that: inventory\_hostname is contains("local" ~ "host") #### [Example - dictionary as conditional](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id11) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#example-dictionary-as-conditional "Link to this heading") This conditional should have been quoted. In a YAML list element, an unquoted string with a space after a colon is interpreted by the YAML parser as a mapping. Non-empty mappings are always truthy. \- assert: that: \- result.msg == "some\_key: some\_value" \# ^^ colon+space == problem The error reported is: Conditional expressions must be strings. This can be resolved by quoting the entire assertion expression: \- assert: that: \- 'result.msg \== "some\_key: some\_value"' ### [Multi-pass templating](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id12) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#multi-pass-templating "Link to this heading") Embedding templates within other templates or expressions could previously result in untrusted templates being executed. The overhauled templating engine in this release no longer supports this insecure behavior. #### [Example - unnecessary template in expression](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id13) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#example-unnecessary-template-in-expression "Link to this heading") This conditional references a variable using a template instead of using the variable directly in the expression. \- assert: that: 1 + {{ value }} == 2 vars: value: 1 The error reported is: Syntax error in expression. Template delimiters are not supported in expressions: expected token ':', got '}' This can be resolved by referencing the variable without a template: \- assert: that: 1 + value == 2 vars: value: 1 #### [Example - dynamic expression construction](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id14) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#example-dynamic-expression-construction "Link to this heading") This conditional is dynamically created using a template, which is expected to be evaluated as an expression. Previously, the template was rendered by task argument templating, resulting in a plain string, which was later evaluated by the `assert` action. \- assert: that: inventory\_hostname {{ comparison }} 'localhost' vars: comparison: \== The error reported is: Syntax error in expression. Template delimiters are not supported in expressions: chunk after expression Dynamic expression construction from playbooks is insecure and unsupported. ### [Troubleshooting untrusted templates](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id15) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#troubleshooting-untrusted-templates "Link to this heading") By default, untrusted templates are silently ignored. Troubleshooting trust issues with templates can be aided by enabling warnings or errors for untrusted templates. The environment variable `_ANSIBLE_TEMPLAR_UNTRUSTED_TEMPLATE_BEHAVIOR` can be used to control this behavior. Valid options are: * `warning` - A warning will be issued when an untrusted template is encountered. * `error` - An error will be raised when an untrusted template is encountered. * `ignore` - Untrusted templates are silently ignored and used as-is. This is the default behavior. Note This optional warning and failure behavior is experimental and subject to change in future versions. ### [Loops no longer leak omit placeholders](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id16) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#loops-no-longer-leak-omit-placeholders "Link to this heading") Omit placeholders no longer leak between loop item templating and task templating. Previously, `omit` placeholders could remain embedded in loop items after templating and be used as an `omit` for task templating. Now, values resolving to `omit` are dropped immediately when loop items are templated. To turn missing values into an `omit` for task templating, use `| default(omit)`. This solution is backward compatible with previous versions of `ansible-core`. #### [Example - missing default(omit)](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id17) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#example-missing-default-omit "Link to this heading") The following task tries to pass `omit` from a loop to the task, but the value is undefined since it was omitted: \- debug: msg: "{{ item.msg }}" \# 'msg' is undefined loop: \- msg: "{{ omit }}" \# 'msg' will be omitted from the loop item This updated task uses `default(omit)` on the missing value to ensure it is omitted for the task: \- debug: msg: "{{ item.msg | default(omit) }}" \# 'msg' is undefined, use 'default(omit)' to turn it into an omit loop: \- msg: "{{ omit }}" \# passed through in earlier versions, this value is now omitted from the loop item ### [Privilege escalation timeouts](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id18) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#privilege-escalation-timeouts "Link to this heading") Timeout waiting on privilege escalation (`become`) is now an unreachable error instead of a task error. Existing playbooks should be changed to replace `ignore_errors` with `ignore_unreachable` on tasks where timeout on `become` should be ignored. [Engine](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id19) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#engine "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [Templating](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id20) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#templating "Link to this heading") #### [Template trust model inversion](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id21) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#template-trust-model-inversion "Link to this heading") Previously, `ansible-core` implicitly trusted all string values to be rendered as Jinja templates, but applied an “unsafe” wrapper object around strings obtained from untrusted sources (for example, module results). Unsafe-wrapped strings were silently ignored by the template engine, as many templating operations can execute arbitrary code on the control host as the user running ansible-core. This required any code that operated on strings to correctly propagate the wrapper object, which resulted in numerous CVE-worthy RCE (remote code execution) vulnerabilities. This release inverts the previous trust model. Only strings marked as loaded from a trusted source are eligible to be rendered as templates. Untrusted values can (as before) be referenced by templates, but the template expression itself must always be trusted. While this change still requires consideration for propagation of trust markers when manipulating strings, failure to do so now results in a loss of templating ability instead of a potentially high-severity security issue. Attempts to render a template appearing in an untrusted string will (as before) return the original string unmodified. By default, attempting to render an untrusted template fails silently, though such failures can be elevated to a warning or error via configuration. Newly-created string results from template operations will never have trust automatically applied, though templates that return existing trusted string values unmodified will not strip their trust. It is also possible for plugins to explicitly apply trust. Backward-compatible template trust behavior is applied automatically in most cases; for example, templates appearing in playbooks, roles, variable files, and most built-in inventory plugins will yield trusted template strings. Custom plugins that source template strings will be required to use new public APIs to apply trust where appropriate. See [Plugin API](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#plugin-api) and [Troubleshooting untrusted templates](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#untrusted-templates) for additional information. #### [Native Jinja mode required](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id22) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#native-jinja-mode-required "Link to this heading") Previous versions supported templating in two different modes: * Jinja’s original string templating mode converted the result of each templating operation to a string. * Jinja’s native mode _usually_ preserved variable types in template results. In both modes, `ansible-core` evaluated the final template string results as Python literals, falling back to the original string if the evaluation resulted in an error. Selection of the templating mode was controlled by configuration, defaulting to Jinja’s original string templating. Jinja’s native templating mode is now used exclusively. The configuration option for setting the templating mode is deprecated and no longer has any effect. Preservation of native types in templating has been improved to correct gaps in the previous implementation, entirely eliminating the final literal evaluation pass (a frequent source of confusion, errors, and performance issues). In rare cases where playbooks relied on implicit object conversion from strings, an explicit conversion will be required. Some existing templates may unintentionally convert non-strings to strings. In previous versions this conversion could be masked by the evaluation of strings as Python literals. ##### [Example - unintentional string conversion](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id23) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#example-unintentional-string-conversion "Link to this heading") This expression erroneously passes a list to the `replace` filter, which operates only on strings. The filter silently converts the list input to a string. Due to some string results previously parsing as lists, this mistake often went undetected in earlier versions. \- debug: msg: "{{ \['test1', 'test2'\] | replace('test', 'prod') }}" The result of this template becomes a string: ok: \[localhost\] \=> { "msg": "\['prod1', 'prod2'\]" } This can be resolved by using the `map` filter to apply the `replace` filter to each list element: \- debug: msg: "{{ \['test1', 'test2'\] | map('replace', 'test', 'prod') }}" The result of the corrected template remains a list: ok: \[localhost\] \=> { "msg": \[\ "prod1",\ "prod2"\ \] } ##### [Example - unintentional `None` result](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id24) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#example-unintentional-none-result "Link to this heading") If a template evaluated to `None`, it was implicitly converted to an empty string in previous versions of ansible-core. This can now result in the template evaluating to the _value_ `None`. The following example shows a case where this happens: \- set\_fact: \# If 'foo' is not defined, the else branch basically evaluates to None. \# So value\_none will not be an empty string, but None: value\_none: |- {% if foo is defined %}foo is defined{% endif %} This example can be fixed as follows: \- set\_fact: \# Explicitly return an empty string in the 'else' branch. \# The value is always a string: either "foo is defined" or "". value\_none: |- {% if foo is defined %}foo is defined{% else %}{{ "" }}{% endif %} This adjustment is backward-compatible with older ansible-core versions. Note Since ansible-core 2.19.1, module options of type string accept `None` and convert it to an empty string. Before ansible-core 2.18, passing `None` to such options resulted in an error. This means that in most cases, expressions in roles and playbooks do not need to be adjusted because of unintentional `None` results. #### [Lazy templating](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id25) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#lazy-templating "Link to this heading") Ansible’s interface with the Jinja templating engine has been heavily refined, yielding significant performance improvements for many complex templating operations. Previously, deeply-nested, recursive, or self-referential templating operations were always resolved to their full depth and breadth on every access, including repeated access to the same data within a single templating operation. This resulted in expensive and repetitive evaluation of the same templates within a single logical template operation, even for templates deep inside nested data structures that were never directly accessed. The new template engine lazily defers nearly all recursion and templating until values are accessed, or known to be exiting the template engine, and intermediate nested or indirected templated results are cached for the duration of the template operation, reducing repetitive templating. These changes have shown exponential performance improvements for many real-world complex templating scenarios. #### [Consistent handling of range](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id26) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#consistent-handling-of-range "Link to this heading") The result of using the Jinja global function `range()` was heavily dependent on the context in which it was used and whether Jinja’s native mode was enabled. To preserve the ability to use very large ranges in filter chains the result is now always a range object, which means it cannot be returned from a template unless you convert it to a returnable type. ##### [Example - intentional list conversion](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id27) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#example-intentional-list-conversion "Link to this heading") \- debug: loop: "{{ range(0, 2) }}" Ranges not embedded in containers would usually be converted to lists during template finalization. They will now result in this error: Error rendering template: Type 'range' is unsupported for variable storage. This can be resolved by making the conversion explicit: \- debug: loop: "{{ range(0, 2) | list }}" ##### [Example - unintentional string conversion](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id28) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id1 "Link to this heading") \- debug: msg: "{{ \[range(0,2), range(7,10)\] }}" Ranges embedded in containers would usually be converted to string representations of the range object. ok: \[localhost\] \=> { "msg": "\[range(0, 2), range(7, 10)\]" } Attempting to do this will now result in an error; you can mimic the old behaviour by explicitly converting the container to a string, or convert the ranges to lists if you actually want to do something useful with them. \- debug: msg: "{{ \[range(0,2), range(7,10)\] | string }}" \- debug: msg: "{{ \[range(0,2), range(7,10)\] | map('list') }}" ### [Error handling](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id29) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#error-handling "Link to this heading") #### [Contextual warnings and errors](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id30) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#contextual-warnings-and-errors "Link to this heading") Changes to internal error handling in `ansible-core` will be visible in many situations that result in a warning or error. In most cases, the operational context (what was happening when the error or warning was generated) and data element(s) involved are captured and included in user-facing messages. Errors and warnings that occur during task execution are more consistently included in the task result, with the full details accessible to callbacks and (in the case of errors), a minimal error message in the `msg` field of the result. Due to the standardized nature of this error handling, seemingly redundant elements may appear in some error messages. These will improve over time as other error handling improvements are made but are currently necessary to ensure proper context is available in all error situations. Error message contents are not considered stable, so automation that relies on them should be avoided when possible. #### [Variable provenance tracking](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id31) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#variable-provenance-tracking "Link to this heading") The new Data Tagging feature expands provenance tracking on variables to nearly every source. This allows for much more descriptive error messaging, as the entire chain of execution can be consulted to include contextual information about what was happening when an error occurred. In most cases, this includes file path, source lines, and column markers. Non-file variable sources such as CLI arguments, inventory plugins and environment are also supported. #### [Deprecation warnings on value access](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id32) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#deprecation-warnings-on-value-access "Link to this heading") New features allow most `ansible-core` variables and values to be tagged as deprecated. Plugins and modules can apply these tags to augment deprecated elements of their return values with a description and help text to suggest alternatives, which will be displayed in a runtime warning when the tagged value is accessed by, for example, a playbook or template. This allows for easier evolution and removal of module and fact results, and obsolete core behaviors. For example, accessing the deprecated `play_hosts` magic variable will trigger a deprecation warning that suggests the use of the `ansible_play_batch` variable instead. #### [Improved Ansible module error handling](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id33) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#improved-ansible-module-error-handling "Link to this heading") Ansible modules implemented in Python now have exception handling provided by the AnsiballZ wrapper. In previous versions of `ansible-core`, unhandled exceptions in an Ansible module simply printed a traceback and exited without providing a standard module response, which caused the task result to contain a generic `MODULE FAILURE` message and any raw output text produced by the module. To address this, modules often implemented unnecessary `try/except` blocks around most code where specific error handling was not possible, only to call `AnsibleModule.fail_json` with a generic failure message. This pattern is no longer necessary, as all unhandled exceptions in Ansible Python modules are now captured by the AnsiballZ wrapper and returned as a structured module result, with automatic inclusion of traceback information when enabled by the controller. #### [Improved handling of undefined](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id34) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#improved-handling-of-undefined "Link to this heading") Undefined handling has been improved to avoid situations where a Jinja plugin silently ignores undefined values. This commonly occurs when a Jinja plugin, such as a filter or test, checks the type of a variable without accounting for the possibility of an undefined value being present. ##### [Example - missing attribute](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id35) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#example-missing-attribute "Link to this heading") This task incorrectly references an undefined `exists` attribute from a `stat` result in a conditional. The undefined value was not detected in previous versions because it is passed to the `false` Jinja test plugin, which silently ignores undefined values. As a result, this conditional could never be `True` in earlier versions of ansible-core, and there was no indication that the `failed_when` expression was invalid. \- stat: path: /does-not-exist register: result failed\_when: result.exists is false \# ^ missing reference to stat In the current release the faulty expression is detected and results in an error. This can be corrected by adding the missing `stat` attribute to the conditional: \- stat: path: /does-not-exist register: result failed\_when: result.stat.exists is false #### [Displaying tracebacks](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id36) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#displaying-tracebacks "Link to this heading") In previous `ansible-core` versions, tracebacks from some controller-side errors were available by increasing verbosity with the `-vvv` option, but the availability and behavior was inconsistent. This feature was also limited to errors. Handling of errors, warnings and deprecations throughout much of the `ansible-core` codebase has now been standardized. Tracebacks can be optionally collected and displayed for all exceptions, as well as at the call site of errors, warnings, or deprecations (even in module code) using the `ANSIBLE_DISPLAY_TRACEBACK` environment variable. Valid options are: * `always` - Tracebacks will always be displayed. This option takes precedence over others below. * `never` - Tracebacks will never be displayed. This option takes precedence over others below. * `error` - Tracebacks will be displayed for errors. * `warning` - Tracebacks will be displayed for warnings other than deprecation warnings. * `deprecated` - Tracebacks will be displayed for deprecation warnings. Multiple options can be combined by separating them with commas. #### [Displaying warning when undefined variables in vars\_files](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id37) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#displaying-warning-when-undefined-variables-in-vars-files "Link to this heading") In previous versions of `ansible-core`, undefined variables used while specifying file paths in `vars_files` were silently ignored and did not trigger warning. This is now changed and a warning will be displayed when undefined variables are encountered while specifying file paths in `vars_files`. \- hosts: all vars\_files: \- "{{ inventory\_dir }}/vars\_files/bar.yml" PLAYBOOK: foo.yml \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\* 1 plays in foo.yml \[WARNING\]: skipping vars\_file item due to an undefined variable Origin: /examples/foo.yml:6:7 4 5 vars\_files: 6 - "{{ inventory\_dir }}/vars\_files/bar.yml" ^ column 7 In the preceding example, the warning is displayed because `inventory_dir` is a host-scoped variable that is evaluated at the task level, not at the play level where `vars_files` is processed. While `inventory_dir` does not work in `vars_files`, it can be used in task-level variables where the vars from `vars_files` are already available. [Plugin API](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id38) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#plugin-api "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ ### [Deprecating values](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id39) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#deprecating-values "Link to this heading") Plugins and Python modules can tag returned values as deprecated with the new `deprecate_value` function from `ansible.module_utils.datatag`. A description of the deprecated feature, optional help text, and removal timeframes can be attached to the value, which will appear in a runtime warning if the deprecated value is referenced in an expression. The warning message will include information about the module/plugin that applied the deprecation tag and the location of the expression that accessed it. from ansible.module\_utils.datatag import deprecate\_value ... module.exit\_json( color\_name\=deprecate\_value( value\="blue", msg\="The \`color\_name\` return value is deprecated.", help\_text\="Use \`color\_code\` instead.", ), color\_code\="#0000ff", ) When accessing the color\_name from the module result, the following warning will be shown \[DEPRECATION WARNING\]: The \`color\_name\` return value is deprecated. This feature will be removed from the 'ns.collection.paint' module in a future release. Origin: /examples/use\_deprecated.yml:8:14 6 7 - debug: 8 var: result.color\_name ^ column 14 Use \`color\_code\` instead. ### [Applying template trust to individual values](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id40) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#applying-template-trust-to-individual-values "Link to this heading") String values are no longer trusted to be rendered as templates by default. Strings loaded from playbooks, vars files, and other built-in trusted sources are usually marked trusted by default. Plugins that create new string instances with embedded templates must use the new `trust_as_template` function from `ansible.template` to tag those values as originating from a trusted source to allow the templates to be rendered. Warning This section and the associated public API are currently incomplete. ### [Applying template trust in inventory and vars plugins](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id41) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#applying-template-trust-in-inventory-and-vars-plugins "Link to this heading") Inventory plugins can set group and host variables. In most cases, these variables are static values from external sources and do not require trust. Values that can contain templates will require explicit trust via `trust_as_template` to be allowed to render, but trust should not be applied to variable values from external sources that could be maliciously altered to include templates. Warning This section and the associated public API are currently incomplete. ### [Raising exceptions](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id42) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#raising-exceptions "Link to this heading") When raising exceptions in an exception handler, be sure to use `raise ... from` as appropriate. This supersedes the use of the `AnsibleError` arg `orig_exc` to represent the cause. Specifying `orig_exc` as the cause is still permitted for backward compatibility. Failure to use `raise ... from` when `orig_exc` is set will result in a warning. Additionally, if the two cause exceptions do not match, a warning will be issued. ### [Overly-broad exception handling in Jinja plugins](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id43) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#overly-broad-exception-handling-in-jinja-plugins "Link to this heading") Jinja plugins with overly broad exception handling, such as `except Exception`, may behave incorrectly when accessing the contents of variables which are containers (`dict`, `list`). This can occur when a templated value from a variable is undefined, is an undecryptable vaulted value, or another value which triggers lazily reported fault conditions. Jinja plugins should catch more specific exception types where possible, and do so around the smallest reasonable portion of code. Be especially careful to avoid broad exception handling around code which accesses the contents of container variables. ### [Ansible custom data types](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id44) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#ansible-custom-data-types "Link to this heading") Many variable objects in `ansible-core` are represented by custom types. In previous versions these could be seen as types such as: * `AnsibleUnicode` (a subclass of `str`) * `AnsibleSequence` (a subclass of `list`) * `AnsibleMapping` (a subclass of `dict`) These types, and more, now have new subclasses derived from their native Python types. In most cases these types behave indistinguishably from the types they extend, and existing code should function normally. However, some Python libraries do not handle builtin object subclasses properly. Custom plugins that interact with such libraries may require changes to convert and pass the native types. Warning This section and the associated public API are currently incomplete. ### [AnsibleVaultEncryptedUnicode replaced by EncryptedString](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id45) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#ansiblevaultencryptedunicode-replaced-by-encryptedstring "Link to this heading") The `AnsibleVaultEncryptedUnicode` type has been replaced by `EncryptedString`. Plugins which create `AnsibleVaultEncryptedUnicode` will now receive `EncryptedString` instances instead. This feature ensures backward compatibility with previous versions of `ansible-core`. Plugins which perform `isinstance` checks, looking for `AnsibleVaultEncryptedUnicode`, will no longer encounter these types. Values formerly represented by that type will now appear as a tagged `str` instead. Special handling in plugins is no longer required to access the contents of these values. ### [No implicit conversion of non-string dict keys](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id46) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#no-implicit-conversion-of-non-string-dict-keys "Link to this heading") In previous versions, `ansible-core` relied on Python’s `json.dumps` to implicitly convert `int`, `float`, `bool` and `None` dictionary keys to strings in various scenarios, including returning of module results. For example, a module was allowed to contain the following code: oid \= 123 d \= {oid: "value"} module.exit\_json(return\_value\=d) Starting with this release, modules must explicitly convert any non-string keys to strings (for example, by using the `str()` Python function) before passing dictionaries to the `AnsibleModule.exit_json()` method of `ansible-core`. The above code must be changed as follows: oid \= 123 d \= {str(oid): "value"} module.exit\_json(return\_value\=d) If you encounter `"[ERROR]: Task failed: Module failed: Key of type '' is not JSON serializable by the 'module_legacy_m2c' profile.`, it indicates that the module that is used in the task does not perform the required key conversion. [Command Line](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id47) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#command-line "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- No notable changes [Deprecated](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id48) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#deprecated "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ No notable changes [Modules](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id49) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#modules "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ * With the changes to the templating system it is no longer possible to use the `async_status` module’s `started` and `finished` integer properties as values in conditionals as booleans are required. It is recommended to use `started` and `finished` test plugins instead, for example: \- async\_status: jid: '{{ registered\_task\_result.ansible\_job\_id }}' register: job\_result until: job\_result is finished retries: 5 delay: 10 ### [Modules removed](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id50) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#modules-removed "Link to this heading") The following modules no longer exist: * No notable changes ### [Deprecation notices](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id51) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#deprecation-notices "Link to this heading") No notable changes ### [Noteworthy module changes](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id52) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#noteworthy-module-changes "Link to this heading") No notable changes [Plugins](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id53) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#plugins "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ ### [Noteworthy plugin changes](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id54) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#noteworthy-plugin-changes "Link to this heading") * The `ssh` connection plugin now supports using `SSH_ASKPASS` to supply passwords for authentication as an alternative to the `sshpass` program. The default is to use `SSH_ASKPASS` instead of `sshpass`. This is controlled by the `password_mechanism` configuration for the `ssh` connection plugin. To switch back to using `sshpass` make one of the following changes: To your `ansible.cfg` file: \[ssh\_connection\] password\_mechanism \= sshpass By exporting an environment variable: export ANSIBLE\_SSH\_PASSWORD\_MECHANISM\=sshpass By setting the following variable: ansible\_ssh\_password\_mechanism: sshpass * Coercing unrecognized input values in the `bool` filter is deprecated. The `bool` filter now returns only `True` or `False`, depending on the input: * `True` - Returned for `True`, `1` and case-insensitive matches on the strings: “yes”, “on”, “true”, “1” * `False` - Returned for `False`, `0` and case-insensitive matches on the strings: “no”, “off”, “false”, “0” Any other input will result in a deprecation warning. This warning will become an error in `ansible-core` 2.23. When a deprecation warning is issued, the return value is `False` unless the input equals `1`, which can occur when the input is the `float` value of `1.0`. This filter now returns `False` instead of `None` when the input is `None`. The aforementioned deprecation warning is also issued in this case. * Passing nested non-scalars with embedded templates that may resolve to `Undefined` to Jinja2 filter plugins, such as `default` and `mandatory`, and test plugins including `defined` and `undefined` no longer evaluate as they did in previous versions because nested non-scalars with embedded templates are templated on use only. In 2.19, this assertion passes: \- assert: that: \# Unlike earlier versions, complex\_var is defined even though complex\_var.nested is not. \- complex\_var is defined \# Unlike earlier versions, the default value is not applied because complex\_var is defined. \- (complex\_var | default(unused)).nested is undefined \# Like earlier versions, directly accessing complex\_var.nested evaluates as undefined. \- complex\_var.nested is undefined vars: complex\_var: \# Before 2.19, complex\_var.nested is evaluated immediately when complex\_var is accessed. \# In 2.19, complex\_var.nested is evaluated only when it is accessed. nested: "{{ undefined\_variable }}" unused: \# This variable is used only if complex\_var is undefined. \# This only happens in ansible-core before 2.19. nested: default [Porting custom scripts](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id55) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#porting-custom-scripts "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ No notable changes [Networking](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#id56) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.19.html#networking "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ No notable changes --- # ansible-core Roadmaps — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * ansible-core Roadmaps * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/roadmap/ansible_core_roadmap_index.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * ansible-core Roadmaps[](https://docs.ansible.com/projects/ansible-core/devel/roadmap/ansible_core_roadmap_index.html#ansible-core-roadmaps "Link to this heading") ==================================================================================================================================================================== The `ansible-core` team develops a roadmap for each major and minor `ansible-core` release. The latest roadmap shows current work; older roadmaps provide a history of the project. We don’t publish roadmaps for subminor versions. So 2.10 and 2.11 have roadmaps, but 2.10.1 does not. We incorporate team and community feedback in each roadmap, and aim for further transparency and better inclusion of both community desires and submissions. Each roadmap offers a _best guess_, based on the `ansible-core` team’s experience and on requests and feedback from the community, of what will be included in a given release. However, some items on the roadmap may be dropped due to time constraints, lack of community maintainers, and so on. Each roadmap is published both as an idea of what is upcoming in `ansible-core`, and as a medium for seeking further feedback from the community. You can submit feedback on the current roadmap by creating a topic on the [Ansible Forum](https://docs.ansible.com/projects/ansible-core/devel/community/communication.html#ansible-forum) tagged with `ansible-core`. ansible-core Roadmaps * [Ansible-core 2.21](https://docs.ansible.com/projects/ansible-core/devel/roadmap/ROADMAP_2_21.html) * [Ansible-core 2.20](https://docs.ansible.com/projects/ansible-core/devel/roadmap/ROADMAP_2_20.html) * [Ansible-core 2.19](https://docs.ansible.com/projects/ansible-core/devel/roadmap/ROADMAP_2_19.html) * [Ansible-core 2.18](https://docs.ansible.com/projects/ansible-core/devel/roadmap/ROADMAP_2_18.html) * [Ansible-core 2.17](https://docs.ansible.com/projects/ansible-core/devel/roadmap/ROADMAP_2_17.html) * [Ansible-core 2.16](https://docs.ansible.com/projects/ansible-core/devel/roadmap/ROADMAP_2_16.html) * [Ansible-core 2.15](https://docs.ansible.com/projects/ansible-core/devel/roadmap/ROADMAP_2_15.html) * [Ansible-core 2.14](https://docs.ansible.com/projects/ansible-core/devel/roadmap/ROADMAP_2_14.html) * [Ansible-core 2.13](https://docs.ansible.com/projects/ansible-core/devel/roadmap/ROADMAP_2_13.html) * [Ansible-core 2.12](https://docs.ansible.com/projects/ansible-core/devel/roadmap/ROADMAP_2_12.html) * [Ansible-core 2.11](https://docs.ansible.com/projects/ansible-core/devel/roadmap/ROADMAP_2_11.html) * [Ansible-base 2.10](https://docs.ansible.com/projects/ansible-core/devel/roadmap/ROADMAP_2_10.html) --- # Using Ansible collections — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * Using Ansible collections * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/collections_guide/index.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Using Ansible collections[](https://docs.ansible.com/projects/ansible-core/devel/collections_guide/index.html#using-ansible-collections "Link to this heading") ================================================================================================================================================================= Note **Making Open Source More Inclusive** 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) . Welcome to the Ansible guide for working with collections. Collections are a distribution format for Ansible content that can include playbooks, roles, modules, and plugins. You can install and use collections through a distribution server, such as Ansible Galaxy, or a Pulp 3 Galaxy server. * [Installing collections](https://docs.ansible.com/projects/ansible-core/devel/collections_guide/collections_installing.html) * [Installing collections in containers](https://docs.ansible.com/projects/ansible-core/devel/collections_guide/collections_installing.html#installing-collections-in-containers) * [Installing collections with `ansible-galaxy`](https://docs.ansible.com/projects/ansible-core/devel/collections_guide/collections_installing.html#installing-collections-with-ansible-galaxy) * [Installing collections with signature verification](https://docs.ansible.com/projects/ansible-core/devel/collections_guide/collections_installing.html#installing-collections-with-signature-verification) * [Installing an older version of a collection](https://docs.ansible.com/projects/ansible-core/devel/collections_guide/collections_installing.html#installing-an-older-version-of-a-collection) * [Install multiple collections with a requirements file](https://docs.ansible.com/projects/ansible-core/devel/collections_guide/collections_installing.html#install-multiple-collections-with-a-requirements-file) * [Downloading a collection for offline use](https://docs.ansible.com/projects/ansible-core/devel/collections_guide/collections_installing.html#downloading-a-collection-for-offline-use) * [Installing collections adjacent to playbooks](https://docs.ansible.com/projects/ansible-core/devel/collections_guide/collections_installing.html#installing-collections-adjacent-to-playbooks) * [Installing a collection from source files](https://docs.ansible.com/projects/ansible-core/devel/collections_guide/collections_installing.html#installing-a-collection-from-source-files) * [Installing a collection from a Git repository](https://docs.ansible.com/projects/ansible-core/devel/collections_guide/collections_installing.html#installing-a-collection-from-a-git-repository) * [Configuring the `ansible-galaxy` client](https://docs.ansible.com/projects/ansible-core/devel/collections_guide/collections_installing.html#configuring-the-ansible-galaxy-client) * [Removing a collection](https://docs.ansible.com/projects/ansible-core/devel/collections_guide/collections_installing.html#removing-a-collection) * [Downloading collections](https://docs.ansible.com/projects/ansible-core/devel/collections_guide/collections_downloading.html) * [Listing collections](https://docs.ansible.com/projects/ansible-core/devel/collections_guide/collections_listing.html) * [Verifying collections](https://docs.ansible.com/projects/ansible-core/devel/collections_guide/collections_verifying.html) * [Verifying collections with `ansible-galaxy`](https://docs.ansible.com/projects/ansible-core/devel/collections_guide/collections_verifying.html#verifying-collections-with-ansible-galaxy) * [Verifying signed collections](https://docs.ansible.com/projects/ansible-core/devel/collections_guide/collections_verifying.html#verifying-signed-collections) * [Using collections in a playbook](https://docs.ansible.com/projects/ansible-core/devel/collections_guide/collections_using_playbooks.html) * [Simplifying module names with the `collections` keyword](https://docs.ansible.com/projects/ansible-core/devel/collections_guide/collections_using_playbooks.html#simplifying-module-names-with-the-collections-keyword) * [Using `collections` in roles](https://docs.ansible.com/projects/ansible-core/devel/collections_guide/collections_using_playbooks.html#using-collections-in-roles) * [Using `collections` in playbooks](https://docs.ansible.com/projects/ansible-core/devel/collections_guide/collections_using_playbooks.html#using-collections-in-playbooks) * [Using a playbook from a collection](https://docs.ansible.com/projects/ansible-core/devel/collections_guide/collections_using_playbooks.html#using-a-playbook-from-a-collection) * [Collections index](https://docs.ansible.com/projects/ansible-core/devel/collections_guide/collections_index.html) --- # Indexes of all modules and plugins — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * Indexes of all modules and plugins * * * * Indexes of all modules and plugins[](https://docs.ansible.com/projects/ansible-core/devel/collections/all_plugins.html#indexes-of-all-modules-and-plugins "Link to this heading") =================================================================================================================================================================================== Plugin indexes * [Index of all Become Plugins](https://docs.ansible.com/projects/ansible-core/devel/collections/index_become.html) * [Index of all Cache Plugins](https://docs.ansible.com/projects/ansible-core/devel/collections/index_cache.html) * [Index of all Callback Plugins](https://docs.ansible.com/projects/ansible-core/devel/collections/index_callback.html) * [Index of all Connection Plugins](https://docs.ansible.com/projects/ansible-core/devel/collections/index_connection.html) * [Index of all Filter Plugins](https://docs.ansible.com/projects/ansible-core/devel/collections/index_filter.html) * [Index of all Inventory Plugins](https://docs.ansible.com/projects/ansible-core/devel/collections/index_inventory.html) * [Index of all Lookup Plugins](https://docs.ansible.com/projects/ansible-core/devel/collections/index_lookup.html) * [Index of all Modules](https://docs.ansible.com/projects/ansible-core/devel/collections/index_module.html) * [Index of all Shell Plugins](https://docs.ansible.com/projects/ansible-core/devel/collections/index_shell.html) * [Index of all Strategy Plugins](https://docs.ansible.com/projects/ansible-core/devel/collections/index_strategy.html) * [Index of all Test Plugins](https://docs.ansible.com/projects/ansible-core/devel/collections/index_test.html) * [Index of all Vars Plugins](https://docs.ansible.com/projects/ansible-core/devel/collections/index_vars.html) * [Index of all deprecated plugins](https://docs.ansible.com/projects/ansible-core/devel/collections/deprecations.html) --- # Frequently Asked Questions — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * Frequently Asked Questions * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/reference_appendices/faq.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Frequently Asked Questions[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#frequently-asked-questions "Link to this heading") ================================================================================================================================================================ Here are some commonly asked questions and their answers. Where did all the modules go?[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#where-did-all-the-modules-go "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------- In July, 2019, we announced that collections would be the [future of Ansible content delivery](https://www.ansible.com/blog/the-future-of-ansible-content-delivery) . A collection is a distribution format for Ansible content that can include playbooks, roles, modules, and plugins. In Ansible 2.9 we added support for collections. In Ansible 2.10 we [extracted most modules from the main ansible/ansible repository](https://access.redhat.com/solutions/5295121) and placed them in [collections](https://docs.ansible.com/projects/ansible/latest/collections/index.html#list-of-collections) . Collections may be maintained by the Ansible team, by the Ansible community, or by Ansible partners. The [ansible/ansible repository](https://github.com/ansible/ansible) now contains the code for basic features and functions, such as copying module code to managed nodes. This code is also known as `ansible-core` (it was briefly called `ansible-base` for version 2.10). * To learn more about using collections, see [Using Ansible collections](https://docs.ansible.com/projects/ansible/latest/collections_guide/index.html#collections) . * To learn more about developing collections, see [Developing collections](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_collections.html#developing-collections) . * To learn more about contributing to existing collections, see the individual collection repository for guidelines, or see [Contributing to Ansible-maintained Collections](https://docs.ansible.com/projects/ansible/latest/community/contributing_maintained_collections.html#contributing-maintained-collections) to contribute to one of the Ansible-maintained collections. Where did this specific module go?[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#where-did-this-specific-module-go "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- IF you are searching for a specific module, you can check the [runtime.yml](https://github.com/ansible/ansible/blob/devel/lib/ansible/config/ansible_builtin_runtime.yml) file, which lists the first destination for each module that we extracted from the main ansible/ansible repository. Some modules have moved again since then. You can also search on [Ansible Galaxy](https://galaxy.ansible.com/) or ask on one of our [chat channels](https://docs.ansible.com/projects/ansible/latest/community/communication.html#communication-irc) . How can I speed up Ansible on systems with slow disks?[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#how-can-i-speed-up-ansible-on-systems-with-slow-disks "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Ansible may feel sluggish on systems with slow disks, such as Raspberry PI. See [Ansible might be running slow if libyaml is not available](https://www.jeffgeerling.com/blog/2021/ansible-might-be-running-slow-if-libyaml-not-available) for hints on how to improve this. How can I set the PATH or any other environment variable for a task or entire play?[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#how-can-i-set-the-path-or-any-other-environment-variable-for-a-task-or-entire-play "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Setting environment variables can be done with the environment keyword. It can be used at the task or other levels in the play. shell: cmd: date environment: LANG=fr\_FR.UTF-8 hosts: servers environment: PATH: "{{ ansible\_env.PATH }}:/thingy/bin" SOME: value Note starting in 2.0.1 the setup task from `gather_facts` also inherits the environment directive from the play, you might need to use the `|default` filter to avoid errors if setting this at play level. How do I handle different machines needing different user accounts or ports to log in with?[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#how-do-i-handle-different-machines-needing-different-user-accounts-or-ports-to-log-in-with "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Setting inventory variables in the inventory file is the easiest way. For example, suppose these hosts have different usernames and ports: \[webservers\] asdf.example.com ansible\_port\=5000 ansible\_user=alice jkl.example.com ansible\_port\=5001 ansible\_user=bob You can also dictate the connection type to be used, if you want: \[testcluster\] localhost ansible\_connection\=local /path/to/chroot1 ansible\_connection\=chroot foo.example.com ansible\_connection\=paramiko You may also wish to keep these in group variables instead, or file them in a group\_vars/ file. See the rest of the documentation for more information about how to organize variables. How do I get ansible to reuse connections, enable Kerberized SSH, or have Ansible pay attention to my local SSH config file?[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#how-do-i-get-ansible-to-reuse-connections-enable-kerberized-ssh-or-have-ansible-pay-attention-to-my-local-ssh-config-file "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Switch your default connection type in the configuration file to `ssh`, or use `-c ssh` to use Native OpenSSH for connections instead of the python paramiko library. In Ansible 1.2.1 and later, `ssh` will be used by default if OpenSSH is new enough to support ControlPersist as an option. Paramiko is great for starting out, but the OpenSSH type offers many advanced options. You will want to run Ansible from a machine new enough to support ControlPersist, if you are using this connection type. You can still manage older clients. If you are using RHEL 6, CentOS 6, SLES 10 or SLES 11 the version of OpenSSH is still a bit old, so consider managing from a Fedora or openSUSE client even though you are managing older nodes, or just use paramiko. We keep paramiko as the default as if you are first installing Ansible on these enterprise operating systems, it offers a better experience for new users. How do I configure a jump host to access servers that I have no direct access to?[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#how-do-i-configure-a-jump-host-to-access-servers-that-i-have-no-direct-access-to "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can set a `ProxyCommand` in the `ansible_ssh_common_args` inventory variable. Any arguments specified in this variable are added to the sftp/scp/ssh command line when connecting to the relevant host(s). Consider the following inventory group: \[gatewayed\] foo ansible\_host\=192.0.2.1 bar ansible\_host\=192.0.2.2 You can create group\_vars/gatewayed.yml with the following contents: ansible\_ssh\_common\_args: '-o ProxyCommand="ssh \-W %h:%p \-q user@gateway.example.com"' Ansible will append these arguments to the command line when trying to connect to any hosts in the group `gatewayed`. (These arguments are used in addition to any `ssh_args` from `ansible.cfg`, so you do not need to repeat global `ControlPersist` settings in `ansible_ssh_common_args`.) Note that `ssh -W` is available only with OpenSSH 5.4 or later. With older versions, it is necessary to execute `nc %h:%p` or some equivalent command on the bastion host. With earlier versions of Ansible, it was necessary to configure a suitable `ProxyCommand` for one or more hosts in `~/.ssh/config`, or globally by setting `ssh_args` in `ansible.cfg`. How do I get Ansible to notice a dead target in a timely manner?[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#how-do-i-get-ansible-to-notice-a-dead-target-in-a-timely-manner "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can add `-o ServerAliveInterval=NumberOfSeconds` with the `ssh_args` parameter in [SSH connection plugin](https://docs.ansible.com/ansible-core/devel/collections/ansible/builtin/ssh_connection.html#parameter-ssh_args) . Without this option, SSH and therefore Ansible will wait until the TCP connection times out. Another solution is to add `ServerAliveInterval` into your global SSH configuration. A good value for `ServerAliveInterval` is up to you to decide; keep in mind that `ServerAliveCountMax=3` is the SSH default so any value you set will be tripled before terminating the SSH session. How do I speed up run of ansible for servers from cloud providers (EC2, openstack,.. )?[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#how-do-i-speed-up-run-of-ansible-for-servers-from-cloud-providers-ec2-openstack "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Don’t try to manage a fleet of machines of a cloud provider from your laptop. Rather connect to a management node inside this cloud provider first and run Ansible from there. How do I handle not having a Python interpreter at /usr/bin/python on a remote machine?[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#how-do-i-handle-not-having-a-python-interpreter-at-usr-bin-python-on-a-remote-machine "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- While you can write Ansible modules in any language, most Ansible modules are written in Python, including the ones central to letting Ansible work. By default, Ansible assumes it can find a **/usr/bin/python** on your remote system that is either Python2, version 2.6 or higher or Python3, 3.5 or higher. Setting the inventory variable `ansible_python_interpreter` on any host will tell Ansible to auto-replace the Python interpreter with that value instead. Thus, you can point to any Python you want on the system if **/usr/bin/python** on your system does not point to a compatible Python interpreter. Some platforms may only have Python 3 installed by default. If it is not installed as **/usr/bin/python**, you will need to configure the path to the interpreter through `ansible_python_interpreter`. Although most core modules will work with Python 3, there may be some special purpose ones which do not or you may encounter a bug in an edge case. As a temporary workaround you can install Python 2 on the managed host and configure Ansible to use that Python through `ansible_python_interpreter`. If there’s no mention in the module’s documentation that the module requires Python 2, you can also report a bug on our [bug tracker](https://github.com/ansible/ansible/issues) so that the incompatibility can be fixed in a future release. Do not replace the shebang lines of your python modules. Ansible will do this for you automatically at deploy time. Also, this works for ANY interpreter, for example ruby: `ansible_ruby_interpreter`, perl: `ansible_perl_interpreter`, and so on, so you can use this for custom modules written in any scripting language and control the interpreter location. Keep in mind that if you put `env` in your module shebang line (`#!/usr/bin/env `), this won’t work and will be evaluated as one string (including the space between `env` and `` space). Arguments are neither intended nor supported. How do I handle the package dependencies required by Ansible package dependencies during Ansible installation ?[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#how-do-i-handle-the-package-dependencies-required-by-ansible-package-dependencies-during-ansible-installation "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- While installing Ansible, sometimes you may encounter errors such as No package ‘libffi’ found or fatal error: Python.h: No such file or directory These errors are generally caused by the missing packages, which are dependencies of the packages required by Ansible. For example, libffi package is dependency of pynacl and paramiko (Ansible -> paramiko -> pynacl -> libffi). In order to solve these kinds of dependency issues, you might need to install required packages using the OS native package managers, such as yum, dnf, or apt, or as mentioned in the package installation guide. Refer to the documentation of the respective package for such dependencies and their installation methods. Common System Issues[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#common-system-issues "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------- ### Running in a virtualenv[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#running-in-a-virtualenv "Link to this heading") You can install Ansible into a virtualenv on the control node quite simply: $ virtualenv ansible $ source ./ansible/bin/activate $ pip install ansible If you want to run under Python 3 instead of Python 2 you may want to change that slightly: $ virtualenv \-p python3 ansible $ source ./ansible/bin/activate $ pip install ansible If you need to use any libraries which are not available through pip (for example, SELinux Python bindings on systems such as Red Hat Enterprise Linux or Fedora that have SELinux enabled), then you need to install them into the virtualenv. There are two methods: * When you create the virtualenv, specify `--system-site-packages` to make use of any libraries installed in the system’s Python: $ virtualenv ansible \--system-site-packages * Copy those files in manually from the system. For example, for SELinux bindings you might do: $ virtualenv ansible \--system-site-packages $ cp \-r \-v /usr/lib64/python3.\*/site-packages/selinux/ ./py3-ansible/lib64/python3.\*/site-packages/ $ cp \-v /usr/lib64/python3.\*/site-packages/\*selinux\*.so ./py3-ansible/lib64/python3.\*/site-packages/ ### Running on macOS as a control node[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#running-on-macos-as-a-control-node "Link to this heading") When executing Ansible on a system with macOS as a control node machine one might encounter the following error: > Error > > +\[\_\_NSCFConstantString initialize\] may have been in progress in another thread when fork() was called. We cannot safely call it or ignore it in the fork() child process. Crashing instead. Set a breakpoint on objc\_initializeAfterForkError to debug. ERROR! A worker was found in a dead state In general the recommended workaround is to set the following environment variable in your shell: > $ export OBJC\_DISABLE\_INITIALIZE\_FORK\_SAFETY\=YES ### Running on macOS as a target[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#running-on-macos-as-a-target "Link to this heading") When managing a system with macOS Monterey 12, macOS Ventura 13 or above over SSH, the following error can occur: > Error > > “eDSPermissionError” DS Error: -14120 (eDSPermissionError) This is a good indication that _Allow full disk access for remote users_ has not been enabled. See also For more details, check out [the official Apple user guide article](https://support.apple.com/guide/mac-help/mchlp1066/mac#mchlp1b6a98a) . ### Running on BSD[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#running-on-bsd "Link to this heading") See also [Managing BSD hosts with Ansible](https://docs.ansible.com/projects/ansible/latest/os_guide/intro_bsd.html#working-with-bsd) ### Running on Solaris[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#running-on-solaris "Link to this heading") By default, Solaris 10 and earlier run a non-POSIX shell which does not correctly expand the default tmp directory Ansible uses ( `~/.ansible/tmp`). If you see module failures on Solaris machines, this is likely the problem. There are several workarounds: * You can set `remote_tmp` to a path that will expand correctly with the shell you are using (see the plugin documentation for [C shell](https://docs.ansible.com/projects/ansible/2.9/plugins/shell/csh.html#csh-shell "(in Ansible v2.9)") , [fish shell](https://docs.ansible.com/projects/ansible/2.9/plugins/shell/fish.html#fish-shell "(in Ansible v2.9)") , and [Powershell](https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/powershell_shell.html#powershell-shell) ). For example, in the ansible config file you can set: remote\_tmp\=$HOME/.ansible/tmp In Ansible 2.5 and later, you can also set it per-host in inventory like this: solaris1 ansible\_remote\_tmp\=$HOME/.ansible/tmp * You can set [ansible\_shell\_executable](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#ansible-shell-executable) to the path to a POSIX compatible shell. For instance, many Solaris hosts have a POSIX shell located at `/usr/xpg4/bin/sh` so you can set this in inventory like so: solaris1 ansible\_shell\_executable\=/usr/xpg4/bin/sh (bash, ksh, and zsh should also be POSIX compatible if you have any of those installed). ### Running on z/OS[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#running-on-z-os "Link to this heading") * Generally speaking, z/OS cannot be used as an Ansible control node. For more details, see [Using z/OS as a control node](https://docs.ansible.com/projects/ansible/latest/os_guide/intro_zos.html#zos-as-control-node) . * When the path to the Python interpreter is not found in the default location on the target host, the following error may result: Error /usr/bin/python: FSUM7351 not found Ansible requires a Python interpreter to execute modules on the remote host, and checks for it at the ‘default’ path `/usr/bin/python`. On z/OS, the Python 3 interpreter (from [IBM Open Enterprise SDK for Python](https://www.ibm.com/products/open-enterprise-python-zos) ) is often installed to a different path, typically something like: `/usr/lpp/cyp/v3r12/pyz`. The path to the python interpreter can be configured with the Ansible inventory variable `ansible_python_interpreter`. For example: zos1 ansible\_python\_interpreter:/usr/lpp/cyp/v3r12/pyz For more details, see: [How do I handle not having a Python interpreter at /usr/bin/python on a remote machine?](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#python-interpreters) . * When [ANSIBLE\_PIPELINING](https://docs.ansible.com/projects/ansible/latest/reference_appendices/config.html#ansible-pipelining) is not enabled or when Ansible pipelining is enabled but the `PYTHONSTDINENCODING` property is not correctly set, the following error may result. Error SyntaxError: Non-UTF-8 code starting with ‘\\x81’ in file on line 1, but no encoding declared; see [https://peps.python.org/pep-0263/](https://peps.python.org/pep-0263/) for details Note, the hex `'\x81'` below may vary depending source causing the error: When Ansible pipelining is enabled, Ansible passes all module code to the remote target through Python’s stdin pipe and runs it all in a single call. For more details on pipelining, see: [Pipelining](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_program_flow_modules.html#flow-pipelining) . Include the following in the environment for any tasks performed on z/OS managed nodes. PYTHONSTDINENCODING: "cp1047" * Certain language environment (LE) configurations enable automatic conversion and automatic file tagging functionality required by Python on z/OS systems ([IBM Open Enterprise SDK for Python](https://www.ibm.com/products/open-enterprise-python-zos) ). Include the following configurations when setting the remote environment for any z/OS managed nodes: \_BPXK\_AUTOCVT: "ON" \_CEE\_RUNOPTS: "FILETAG(AUTOCVT,AUTOTAG) POSIX(ON)" \_TAG\_REDIR\_ERR: "txt" \_TAG\_REDIR\_IN: "txt" \_TAG\_REDIR\_OUT: "txt" Ansible can be configured with remote environment variables in these options: > * inventory - inventory.yml, group\_vars/all.yml, or host\_vars/all.yml > > * playbook - `environment` variable at top of playbook. > > * block or task - `environment` key word. > For more details, see [Setting the remote environment](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_environment.html#playbooks-environment) . See also [Managing z/OS UNIX hosts with Ansible](https://docs.ansible.com/projects/ansible/latest/os_guide/intro_zos.html#working-with-zos) ### Running under fakeroot[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#running-under-fakeroot "Link to this heading") Some issues arise as `fakeroot` does not create a full nor POSIX compliant system by default. It is known that it will not correctly expand the default tmp directory Ansible uses (`~/.ansible/tmp`). If you see module failures, this is likely the problem. The simple workaround is to set `remote_tmp` to a path that will expand correctly (see documentation of the shell plugin you are using for specifics). For example, in the ansible config file (or through environment variable) you can set: remote\_tmp\=$HOME/.ansible/tmp What is the best way to make content reusable/redistributable?[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#what-is-the-best-way-to-make-content-reusable-redistributable "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- If you have not done so already, read all about “Roles” in the playbooks documentation. This helps you make playbook content self-contained, and works well with things like Git submodules for sharing content with others. If some of these plugin types look strange to you, see the API documentation for more details about ways Ansible can be extended. Where does the configuration file live and what can I configure in it?[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#where-does-the-configuration-file-live-and-what-can-i-configure-in-it "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- See [Configuring Ansible](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_configuration.html#intro-configuration) . How do I disable cowsay?[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#how-do-i-disable-cowsay "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------- If cowsay is installed, Ansible takes it upon itself to make your day happier when running playbooks. If you decide that you would like to work in a professional cow-free environment, you can either uninstall cowsay, set `nocows=1` in `ansible.cfg`, or set the [`ANSIBLE_NOCOWS`](https://docs.ansible.com/projects/ansible/latest/reference_appendices/config.html#envvar-ANSIBLE_NOCOWS) environment variable: export ANSIBLE\_NOCOWS=1 How do I see a list of all of the ansible\_ variables?[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#how-do-i-see-a-list-of-all-of-the-ansible-variables "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Ansible by default gathers “facts” about the machines under management, and these facts can be accessed in playbooks and in templates. To see a list of all of the facts that are available about a machine, you can run the `setup` module as an ad hoc action: ansible -m setup hostname This will print out a dictionary of all of the facts that are available for that particular host. You might want to pipe the output to a pager.This does NOT include inventory variables or internal ‘magic’ variables. See the next question if you need more than just ‘facts’. How do I see all the inventory variables defined for my host?[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#how-do-i-see-all-the-inventory-variables-defined-for-my-host "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- By running the following command, you can see inventory variables for a host: ansible-inventory --list --yaml How do I see all the variables specific to my host?[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#how-do-i-see-all-the-variables-specific-to-my-host "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- To see all host specific variables, which might include facts and other sources: ansible -m debug -a "var=hostvars\['hostname'\]" localhost Unless you are using a fact cache, you normally need to use a play that gathers facts first, for facts included in the task above. How do I loop over a list of hosts in a group, inside of a template?[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#how-do-i-loop-over-a-list-of-hosts-in-a-group-inside-of-a-template "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- A pretty common pattern is to iterate over a list of hosts inside of a host group, perhaps to populate a template configuration file with a list of servers. To do this, you can just access the “$groups” dictionary in your template, like this: {% for host in groups\['db\_servers'\] %} {{ host }} {% endfor %} If you need to access facts about these hosts, for example, the IP address of each hostname, you need to make sure that the facts have been populated. For example, make sure you have a play that talks to db\_servers: \- hosts: db\_servers tasks: \- debug: msg="doesn't matter what you do, just that they were talked to previously." Then you can use the facts inside your template, like this: {% for host in groups\['db\_servers'\] %} {{ hostvars\[host\]\['ansible\_eth0'\]\['ipv4'\]\['address'\] }} {% endfor %} How do I access a variable name programmatically?[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#how-do-i-access-a-variable-name-programmatically "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- An example may come up where we need to get the ipv4 address of an arbitrary interface, where the interface to be used may be supplied through a role parameter or other input. Variable names can be built by adding strings together using “~”, like so: {{ hostvars\[inventory\_hostname\]\['ansible\_' ~ which\_interface\]\['ipv4'\]\['address'\] }} The trick about going through hostvars is necessary because it is a dictionary of the entire namespace of variables. `inventory_hostname` is a magic variable that indicates the current host you are looping over in the host loop. In the example above, if your interface names have dashes, you must replace them with underscores: {{ hostvars\[inventory\_hostname\]\['ansible\_' ~ which\_interface | replace('\_', '-') \]\['ipv4'\]\['address'\] }} Also see [dynamic\_variables](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#dynamic-variables) . How do I access a group variable?[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#how-do-i-access-a-group-variable "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Technically, you don’t, Ansible does not really use groups directly. Groups are labels for host selection and a way to bulk assign variables, they are not a first class entity, Ansible only cares about Hosts and Tasks. That said, you could just access the variable by selecting a host that is part of that group, see [first\_host\_in\_a\_group](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#first-host-in-a-group) below for an example. How do I access a variable of the first host in a group?[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#how-do-i-access-a-variable-of-the-first-host-in-a-group "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- What happens if we want the ip address of the first webserver in the webservers group? Well, we can do that too. Note that if we are using dynamic inventory, which host is the ‘first’ may not be consistent, so you wouldn’t want to do this unless your inventory is static and predictable. (If you are using AWX or the [Red Hat Ansible Automation Platform](https://docs.ansible.com/projects/ansible/latest/reference_appendices/tower.html#ansible-platform) , it will use database order, so this isn’t a problem even if you are using cloud based inventory scripts). Anyway, here’s the trick: {{ hostvars\[groups\['webservers'\]\[0\]\]\['ansible\_eth0'\]\['ipv4'\]\['address'\] }} Notice how we’re pulling out the hostname of the first machine of the webservers group. If you are doing this in a template, you could use the Jinja2 ‘#set’ directive to simplify this, or in a playbook, you could also use set\_fact: \- set\_fact: headnode={{ groups\['webservers'\]\[0\] }} \- debug: msg={{ hostvars\[headnode\].ansible\_eth0.ipv4.address }} Notice how we interchanged the bracket syntax for dots – that can be done anywhere. How do I copy files recursively onto a target host?[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#how-do-i-copy-files-recursively-onto-a-target-host "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The `copy` module has a recursive parameter. However, take a look at the `synchronize` module if you want to do something more efficient for a large number of files. The `synchronize` module wraps rsync. See the module index for info on both of these modules. How do I access shell environment variables?[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#how-do-i-access-shell-environment-variables "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- **On control node machine :** Access existing variables from control node use the `env` lookup plugin. For example, to access the value of the HOME environment variable on the management machine: \--- \# ... vars: local\_home: "{{ lookup('env','HOME') }}" **On target machines :** Environment variables are available through facts in the `ansible_env` variable: {{ ansible\_env.HOME }} If you need to set environment variables for TASK execution, see [Setting the remote environment](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_environment.html#playbooks-environment) in the [Advanced Playbooks](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_special_topics.html#playbooks-special-topics) section. There are several ways to set environment variables on your target machines. You can use the [template](https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/template_module.html#template-module) , [replace](https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/replace_module.html#replace-module) , or [lineinfile](https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/lineinfile_module.html#lineinfile-module) modules to introduce environment variables into files. The exact files to edit vary depending on your OS and distribution and local configuration. How do I generate encrypted passwords for the user module?[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#how-do-i-generate-encrypted-passwords-for-the-user-module "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Ansible ad hoc command is the easiest option: ansible all -i localhost, -m debug -a "msg={{ 'mypassword' | password\_hash('sha512', 'mysecretsalt') }}" The `mkpasswd` utility that is available on most Linux systems is also a great option: mkpasswd --method=sha-512 If this utility is not installed on your system (for example, you are using macOS) then you can still easily generate these passwords using Python. First, ensure that the [Passlib](https://foss.heptapod.net/python-libs/passlib/-/wikis/home) password hashing library is installed: pip install passlib Once the library is ready, SHA512 password values can then be generated as follows: python -c "from passlib.hash import sha512\_crypt; import getpass; print(sha512\_crypt.using(rounds=5000).hash(getpass.getpass()))" Use the integrated [Hashing and encrypting strings and passwords](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_filters.html#hash-filters) to generate a hashed version of a password. You shouldn’t put plaintext passwords in your playbook or host\_vars; instead, use [Using encrypted variables and files](https://docs.ansible.com/projects/ansible/latest/vault_guide/vault_using_encrypted_content.html#playbooks-vault) to encrypt sensitive data. In OpenBSD, a similar option is available in the base system called `encrypt (1)` Ansible allows dot notation and array notation for variables. Which notation should I use?[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#ansible-allows-dot-notation-and-array-notation-for-variables-which-notation-should-i-use "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The dot notation comes from Jinja and works fine for variables without special characters. If your variable contains dots (.), colons (:), or dashes (-), if a key begins and ends with two underscores, or if a key uses any of the known public attributes, it is safer to use the array notation. See [Using variables](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#playbooks-variables) for a list of the known public attributes. item\[0\]\['checksum:md5'\] item\['section'\]\['2.1'\] item\['region'\]\['Mid-Atlantic'\] It is {{ temperature\['Celsius'\]\['-3'\] }} outside. Also array notation allows for dynamic variable composition, see [dynamic\_variables](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#dynamic-variables) . Another problem with ‘dot notation’ is that some keys can cause problems because they collide with attributes and methods of python dictionaries. * Example of incorrect syntax when `item` is a dictionary: item.update This variant causes a syntax error because `update()` is a Python method for dictionaries. * Example of correct syntax: item\['update'\] When is it unsafe to bulk-set task arguments from a variable?[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#when-is-it-unsafe-to-bulk-set-task-arguments-from-a-variable "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can set all of a task’s arguments from a dictionary-typed variable. This technique can be useful in some dynamic execution scenarios. However, it introduces a security risk. We do not recommend it, so Ansible issues a warning when you do something like this: #... vars: usermod\_args: name: testuser state: present update\_password: always tasks: \- user: '{{ usermod\_args }}' This particular example is safe. However, constructing tasks like this is risky because the parameters and values passed to `usermod_args` could be overwritten by malicious values in the `host facts` on a compromised target machine. To mitigate this risk: * set bulk variables at a level of precedence greater than `host facts` in the order of precedence found in [Variable precedence: where should I put a variable?](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#ansible-variable-precedence) (the example above is safe because play vars take precedence over facts) * disable the [INJECT\_FACTS\_AS\_VARS](https://docs.ansible.com/projects/ansible/latest/reference_appendices/config.html#inject-facts-as-vars) configuration setting to prevent fact values from colliding with variables (this will also disable the original warning) Can I get training on Ansible?[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#can-i-get-training-on-ansible "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- Yes! See our [services page](https://www.ansible.com/products/consulting) for information on our services and training offerings. Email [info@ansible.com](mailto:info%40ansible.com) for further details. We also offer free web-based training classes on a regular basis. See our [webinar page](https://www.ansible.com/resources/webinars-training) for more info on upcoming webinars. Is there a web interface / REST API / GUI?[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#is-there-a-web-interface-rest-api-gui "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Yes! The open-source web interface is Ansible AWX. The supported Red Hat product that makes Ansible even more powerful and easy to use is [Red Hat Ansible Automation Platform](https://docs.ansible.com/projects/ansible/latest/reference_appendices/tower.html#ansible-platform) . How do I keep secret data in my playbook?[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#how-do-i-keep-secret-data-in-my-playbook "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- If you would like to keep secret data in your Ansible content and still share it publicly or keep things in source control, see [Using encrypted variables and files](https://docs.ansible.com/projects/ansible/latest/vault_guide/vault_using_encrypted_content.html#playbooks-vault) . If you have a task that you don’t want to show the results or command given to it when using -v (verbose) mode, the following task or playbook attribute can be useful: \- name: secret task shell: /usr/bin/do\_something --value={{ secret\_value }} no\_log: True This can be used to keep verbose output but hide sensitive information from others who would otherwise like to be able to see the output. The `no_log` attribute can also apply to an entire play: \- hosts: all no\_log: True Though this will make the play somewhat difficult to debug. It is recommended that this be applied to single tasks only, once a playbook is completed. Note that the use of the `no_log` attribute does not prevent data from being shown when debugging Ansible itself through the [`ANSIBLE_DEBUG`](https://docs.ansible.com/projects/ansible/latest/reference_appendices/config.html#envvar-ANSIBLE_DEBUG) environment variable. When should I use {{ }}? Also, how to interpolate variables or dynamic variable names[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#when-should-i-use-also-how-to-interpolate-variables-or-dynamic-variable-names "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ A steadfast rule is ‘always use `{{ }}` except when `when:`’. Conditionals are always run through Jinja2 as to resolve the expression, so `when:`, `failed_when:` and `changed_when:` are always templated and you should avoid adding `{{ }}`. In most other cases you should always use the brackets, even if previously you could use variables without specifying (like `loop` or `with_` clauses), as this made it hard to distinguish between an undefined variable and a string. Another rule is ‘moustaches don’t stack’. We often see this: {{ somevar\_{{other\_var}} }} The above DOES NOT WORK as you expect, if you need to use a dynamic variable use the following as appropriate: {{ hostvars\[inventory\_hostname\]\['somevar\_' ~ other\_var\] }} For ‘non host vars’ you can use the [vars lookup](https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/vars_lookup.html#vars-lookup) plugin: {{ lookup('vars', 'somevar\_' ~ other\_var) }} To determine if a keyword requires `{{ }}` or even supports templating, use `ansible-doc -t keyword `, this will return documentation on the keyword including a `template` field with the values `explicit` (requires `{{ }}`), `implicit` (assumes `{{ }}`, so no needed) or `static` (no templating supported, all characters will be interpreted literally) How do I get the original ansible\_host when I delegate a task?[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#how-do-i-get-the-original-ansible-host-when-i-delegate-a-task "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- As the documentation states, connection variables are taken from the `delegate_to` host so `ansible_host` is overwritten, but you can still access the original through `hostvars`: original\_host: "{{ hostvars\[inventory\_hostname\]\['ansible\_host'\] }}" This works for all overridden connection variables, like `ansible_user`, `ansible_port`, and so on. How do I fix ‘protocol error: file name does not match request’ when fetching a file?[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#how-do-i-fix-protocol-error-file-name-does-not-match-request-when-fetching-a-file "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Since release `7.9p1` of OpenSSH there is a [bug](https://bugzilla.mindrot.org/show_bug.cgi?id=2966) in the SCP client that can trigger this error on the Ansible control node when using SCP as the file transfer mechanism: Error failed to transfer file to /tmp/ansible/file.txtrnprotocol error: file name does not match request In these releases, SCP tries to validate that the path of the file to fetch matches the requested path. The validation fails if the remote file name requires quotes to escape spaces or non-ascii characters in its path. To avoid this error: * Ensure you are using SFTP, which is the optimal transfer method for security, speed and reliability. Check that you are doing one of the following: * Rely on the default setting, which is `smart` — this works if `ssh_transfer_method` is not explicitly set anywhere * Set a [host variable](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#host-variables) or [group variable](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#group-variables) in inventory: `ansible_ssh_transfer_method: smart` * Set an environment variable on your control node: `export ANSIBLE_SSH_TRANSFER_METHOD=smart` * Pass an environment variable when you run Ansible: `ANSIBLE_SSH_TRANSFER_METHOD=smart ansible-playbook` * Modify your `ansible.cfg` file: add `ssh_transfer_method=smart` to the `[ssh_connection]` section. The `smart` setting attempts to use `sftp` for the transfer, then falls back to `scp` and then `dd`. If you want the transfer to fail if SFTP is not available, add `ssh_transfer_method=sftp` to the `[ssh_connection]` section. * If you must use SCP, set the `-T` arg to tell the SCP client to ignore path validation. You can do this in one of three ways: * Set a [host variable](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#host-variables) or [group variable](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#group-variables) : `ansible_scp_extra_args=-T`, * Export or pass an environment variable: `ANSIBLE_SCP_EXTRA_ARGS=-T` * Modify your `ansible.cfg` file: add `scp_extra_args=-T` to the `[ssh_connection]` section Note If you see an `invalid argument` error when using `-T`, then your SCP client is not performing file name validation and will not trigger this error. Does Ansible support multiple factor authentication 2FA/MFA/biometrics/finterprint/usbkey/OTP/…[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#does-ansible-support-multiple-factor-authentication-2fa-mfa-biometrics-finterprint-usbkey-otp "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- No, Ansible is designed to execute multiple tasks against multiple targets, minimizing user interaction. As with most automation tools, it is not compatible with interactive security systems designed to handle human interaction. Most of these systems require a secondary prompt per target, which prevents scaling to thousands of targets. They also tend to have very short expiration periods so it requires frequent reauthorization, also an issue with many hosts and/or a long set of tasks. In such environments we recommend securing around Ansible’s execution but still allowing it to use an ‘automation user’ that does not require such measures. With AWX or the [Red Hat Ansible Automation Platform](https://docs.ansible.com/projects/ansible/latest/reference_appendices/tower.html#ansible-platform) , administrators can set up RBAC access to inventory, along with managing credentials and job execution. The ‘validate’ option is not enough for my needs, what do I do?[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#the-validate-option-is-not-enough-for-my-needs-what-do-i-do "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Many Ansible modules that create or update files have a `validate` option that allows you to abort the update if the validation command fails. This uses the temporary file Ansible creates before doing the final update. In many cases this does not work since the validation tools for the specific application require either specific names, multiple files or some other factor that is not present in this simple feature. For these cases you have to handle the validation and restoration yourself. The following is a simple example of how to do this with block/rescue and backups, which most file based modules also support: \- name: maintain config and backout if validation after change fails block: \- name: do the actual update, works with copy, lineinfile and any action that allows for \`backup\`. template: src=template.j2 dest=/x/y/z backup=yes moreoptions=stuff register: updated \- name: run validation, this will change a lot as needed. We assume it returns an error when not passing, use \`failed\_when\` if otherwise. shell: run\_validation\_commmand become: true become\_user: requiredbyapp environment: WEIRD\_REQUIREMENT: 1 when: updated is changed rescue: \- name: restore backup file to original, in the hope the previous configuration was working. copy: remote\_src: true dest: /x/y/z src: "{{ updated\['backup\_file'\] }}" when: updated is changed always: \- name: We choose to always delete backup, but could copy or move, or only delete in rescue. file: path: "{{ updated\['backup\_file'\] }}" state: absent when: updated is changed How do I submit a change to the documentation?[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#how-do-i-submit-a-change-to-the-documentation "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Documentation for Ansible is kept in the [ansible/ansible-documentation](https://github.com/ansible/ansible-documentation) project Git repository. See [Contributing to the Ansible Documentation](https://docs.ansible.com/projects/ansible/latest/community/documentation_contributions.html#community-documentation-contributions) for details. What is the difference between `ansible.legacy` and `ansible.builtin` collections?[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#what-is-the-difference-between-ansible-legacy-and-ansible-builtin-collections "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Neither is a real collection. They are virtually constructed by the core engine (synthetic collections). The `ansible.builtin` collection only refers to plugins that ship with `ansible-core`. The `ansible.legacy` collection is a superset of `ansible.builtin` (you can reference the plugins from builtin through `ansible.legacy`). You also get the ability to add ‘custom’ plugins in the [configured paths and adjacent directories](https://docs.ansible.com/projects/ansible/latest/dev_guide/overview_architecture.html#ansible-search-path) , with the ability to override the builtin plugins that have the same name. Also, `ansible.legacy` is what you get by default when you do not specify an FQCN. So this: > \- shell: echo hi Is really equivalent to: > \- ansible.legacy.shell: echo hi Though, if you do not override the `shell` module, you can also just write it as `ansible.builtin.shell`, since legacy will resolve to the builtin collection. I don’t see my question here[](https://docs.ansible.com/projects/ansible/latest/reference_appendices/faq.html#i-don-t-see-my-question-here "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------- If you have not found an answer to your questions, ask the community! Visit the [Ansible communication guide](https://docs.ansible.com/projects/ansible/latest/community/communication.html#communication) for details. See also [Working with playbooks](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks.html#working-with-playbooks) An introduction to playbooks [Ansible tips and tricks](https://docs.ansible.com/projects/ansible/latest/tips_tricks/index.html#playbooks-best-practices) Tips and tricks for playbooks [Communication](https://docs.ansible.com/projects/ansible/latest/community/communication.html#communication) Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide --- # Using Ansible on Windows, BSD, and z/OS UNIX — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * Using Ansible on Windows, BSD, and z/OS UNIX * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/os_guide/index.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Using Ansible on Windows, BSD, and z/OS UNIX[](https://docs.ansible.com/projects/ansible-core/devel/os_guide/index.html#using-ansible-on-windows-bsd-and-z-os-unix "Link to this heading") ============================================================================================================================================================================================ Note **Making Open Source More Inclusive** 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) . Welcome to the Ansible guide for Microsoft Windows and BSD. Because Windows is not a POSIX-compliant operating system, Ansible interacts with Windows hosts differently than Linux/Unix hosts. Likewise, managing hosts that run BSD is different than managing other Unix-like host operating systems. Find out everything you need to know about using Ansible on Windows and with BSD hosts. * [Managing BSD hosts with Ansible](https://docs.ansible.com/projects/ansible-core/devel/os_guide/intro_bsd.html) * [Connecting to BSD nodes](https://docs.ansible.com/projects/ansible-core/devel/os_guide/intro_bsd.html#connecting-to-bsd-nodes) * [Bootstrapping BSD](https://docs.ansible.com/projects/ansible-core/devel/os_guide/intro_bsd.html#bootstrapping-bsd) * [Setting the Python interpreter](https://docs.ansible.com/projects/ansible-core/devel/os_guide/intro_bsd.html#setting-the-python-interpreter) * [Which modules are available?](https://docs.ansible.com/projects/ansible-core/devel/os_guide/intro_bsd.html#which-modules-are-available) * [Using BSD as the control node](https://docs.ansible.com/projects/ansible-core/devel/os_guide/intro_bsd.html#using-bsd-as-the-control-node) * [BSD facts](https://docs.ansible.com/projects/ansible-core/devel/os_guide/intro_bsd.html#bsd-facts) * [BSD efforts and contributions](https://docs.ansible.com/projects/ansible-core/devel/os_guide/intro_bsd.html#bsd-efforts-and-contributions) * [Managing Windows hosts with Ansible](https://docs.ansible.com/projects/ansible-core/devel/os_guide/intro_windows.html) * [Windows App Control](https://docs.ansible.com/projects/ansible-core/devel/os_guide/windows_app_control.html) * [Desired State Configuration](https://docs.ansible.com/projects/ansible-core/devel/os_guide/windows_dsc.html) * [Windows performance](https://docs.ansible.com/projects/ansible-core/devel/os_guide/windows_performance.html) * [Windows SSH](https://docs.ansible.com/projects/ansible-core/devel/os_guide/windows_ssh.html) * [Using Ansible and Windows](https://docs.ansible.com/projects/ansible-core/devel/os_guide/windows_usage.html) * [Windows Remote Management](https://docs.ansible.com/projects/ansible-core/devel/os_guide/windows_winrm.html) * [WinRM Certificate Authentication](https://docs.ansible.com/projects/ansible-core/devel/os_guide/windows_winrm_certificate.html) * [Kerberos Authentication](https://docs.ansible.com/projects/ansible-core/devel/os_guide/windows_winrm_kerberos.html) * [Bootstrapping Windows](https://docs.ansible.com/projects/ansible-core/devel/os_guide/intro_windows.html#bootstrapping-windows) * [Connecting to Windows nodes](https://docs.ansible.com/projects/ansible-core/devel/os_guide/intro_windows.html#connecting-to-windows-nodes) * [Which modules are available?](https://docs.ansible.com/projects/ansible-core/devel/os_guide/intro_windows.html#which-modules-are-available) * [Using Windows as the control node](https://docs.ansible.com/projects/ansible-core/devel/os_guide/intro_windows.html#using-windows-as-the-control-node) * [Windows facts](https://docs.ansible.com/projects/ansible-core/devel/os_guide/intro_windows.html#windows-facts) * [Common Windows problems](https://docs.ansible.com/projects/ansible-core/devel/os_guide/intro_windows.html#common-windows-problems) * [Managing z/OS UNIX hosts with Ansible](https://docs.ansible.com/projects/ansible-core/devel/os_guide/intro_zos.html) * [Ansible and z/OS UNIX System Services](https://docs.ansible.com/projects/ansible-core/devel/os_guide/intro_zos.html#ansible-and-z-os-unix-system-services) * [The z/OS landscape](https://docs.ansible.com/projects/ansible-core/devel/os_guide/intro_zos.html#the-z-os-landscape) * [Using `ansible.builtin` modules with z/OS UNIX](https://docs.ansible.com/projects/ansible-core/devel/os_guide/intro_zos.html#using-ansible-builtin-modules-with-z-os-unix) * [Configure the remote environment](https://docs.ansible.com/projects/ansible-core/devel/os_guide/intro_zos.html#configure-the-remote-environment) * [Configure the remote Python interpreter](https://docs.ansible.com/projects/ansible-core/devel/os_guide/intro_zos.html#configure-the-remote-python-interpreter) * [Configure the remote shell](https://docs.ansible.com/projects/ansible-core/devel/os_guide/intro_zos.html#configure-the-remote-shell) * [Enable Ansible pipelining](https://docs.ansible.com/projects/ansible-core/devel/os_guide/intro_zos.html#enable-ansible-pipelining) * [Unreadable characters](https://docs.ansible.com/projects/ansible-core/devel/os_guide/intro_zos.html#unreadable-characters) * [Using z/OS as a control node](https://docs.ansible.com/projects/ansible-core/devel/os_guide/intro_zos.html#using-z-os-as-a-control-node) --- # Ansible-core 2.11 Porting Guide — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * [Ansible Core Porting Guides](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/core_porting_guides.html) * Ansible-core 2.11 Porting Guide * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/porting_guides/porting_guide_core_2.11.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * [Ansible-core 2.11 Porting Guide](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.11.html#id1) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.11.html#ansible-core-2-11-porting-guide "Link to this heading") ===================================================================================================================================================================================================================================================================================================== This section discusses the behavioral changes between `ansible-base` 2.10 and `ansible-core` 2.11. It is intended to assist in updating your playbooks, plugins and other parts of your Ansible infrastructure so they work with this version of `ansible-core`. We suggest you read this page along with the [ansible-core Changelog for 2.11](https://github.com/ansible/ansible/blob/stable-2.11/changelogs/CHANGELOG-v2.11.rst) to understand what updates you may need to make. `ansible-core` is mainly of interest for developers and users who only want to use a small, controlled subset of the available collections. Regular users should install Ansible. The complete list of porting guides can be found at [porting guides](https://docs.ansible.com/projects/ansible/2.9/porting_guides/porting_guides.html#porting-guides "(in Ansible v2.9)") . [Playbook](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.11.html#id2) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.11.html#playbook "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * The `jinja2_native` setting now does not affect the template module which implicitly returns strings. For the template lookup there is a new argument `jinja2_native` (off by default) to control that functionality. The rest of the Jinja2 expressions still operate based on the `jinja2_native` setting. [Command Line](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.11.html#id3) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.11.html#command-line "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * The `ansible-galaxy login` command has been removed, as the underlying API it used for GitHub auth has been shut down. Publishing roles or collections to Galaxy with `ansible-galaxy` now requires that a Galaxy API token be passed to the CLI using a token file (default location `~/.ansible/galaxy_token`) or (insecurely) with the `--token` argument to `ansible-galaxy`. [Deprecated](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.11.html#id4) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.11.html#deprecated "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The constant `ansible.module_utils.basic._CHECK_ARGUMENT_TYPES_DISPATCHER` is deprecated. Use [`ansible.module_utils.common.parameters.DEFAULT_TYPE_VALIDATORS`](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.parameters.DEFAULT_TYPE_VALIDATORS "ansible.module_utils.common.parameters.DEFAULT_TYPE_VALIDATORS") instead. [Breaking Changes](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.11.html#id5) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.11.html#breaking-changes "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [Changes to `AnsibleModule`](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.11.html#id6) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.11.html#changes-to-ansiblemodule "Link to this heading") With the move to [`ArgumentSpecValidator`](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.arg_spec.ArgumentSpecValidator "ansible.module_utils.common.arg_spec.ArgumentSpecValidator") for performing argument spec validation, the following private methods in [`AnsibleModule`](https://docs.ansible.com/projects/ansible/2.9/reference_appendices/module_utils.html#ansible.module_utils.basic.AnsibleModule "(in Ansible v2.9)") have been removed: > * `_check_argument_types()` > > * `_check_argument_values()` > > * `_check_arguments()` > > * `_check_mutually_exclusive()` –> [`ansible.module_utils.common.validation.check_mutually_exclusive()`](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_mutually_exclusive "ansible.module_utils.common.validation.check_mutually_exclusive") > > * `_check_required_arguments()` –> [`ansible.module_utils.common.validation.check_required_arguments()`](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_required_arguments "ansible.module_utils.common.validation.check_required_arguments") > > * `_check_required_by()` –> [`ansible.module_utils.common.validation.check_required_by()`](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_required_by "ansible.module_utils.common.validation.check_required_by") > > * `_check_required_if()` –> [`ansible.module_utils.common.validation.check_required_if()`](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_required_if "ansible.module_utils.common.validation.check_required_if") > > * `_check_required_one_of()` –> [`ansible.module_utils.common.validation.check_required_one_of()`](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_required_one_of "ansible.module_utils.common.validation.check_required_one_of") > > * `_check_required_together()` –> [`ansible.module_utils.common.validation.check_required_together()`](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_required_together "ansible.module_utils.common.validation.check_required_together") > > * `_check_type_bits()` –> [`ansible.module_utils.common.validation.check_type_bits()`](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_bits "ansible.module_utils.common.validation.check_type_bits") > > * `_check_type_bool()` –> [`ansible.module_utils.common.validation.check_type_bool()`](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_bool "ansible.module_utils.common.validation.check_type_bool") > > * `_check_type_bytes()` –> [`ansible.module_utils.common.validation.check_type_bytes()`](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_bytes "ansible.module_utils.common.validation.check_type_bytes") > > * `_check_type_dict()` –> [`ansible.module_utils.common.validation.check_type_dict()`](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_dict "ansible.module_utils.common.validation.check_type_dict") > > * `_check_type_float()` –> [`ansible.module_utils.common.validation.check_type_float()`](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_float "ansible.module_utils.common.validation.check_type_float") > > * `_check_type_int()` –> [`ansible.module_utils.common.validation.check_type_int()`](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_int "ansible.module_utils.common.validation.check_type_int") > > * `_check_type_jsonarg()` –> [`ansible.module_utils.common.validation.check_type_jsonarg()`](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_jsonarg "ansible.module_utils.common.validation.check_type_jsonarg") > > * `_check_type_list()` –> [`ansible.module_utils.common.validation.check_type_list()`](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_list "ansible.module_utils.common.validation.check_type_list") > > * `_check_type_path()` –> [`ansible.module_utils.common.validation.check_type_path()`](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_path "ansible.module_utils.common.validation.check_type_path") > > * `_check_type_raw()` –> [`ansible.module_utils.common.validation.check_type_raw()`](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_raw "ansible.module_utils.common.validation.check_type_raw") > > * `_check_type_str()` –> [`ansible.module_utils.common.validation.check_type_str()`](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_str "ansible.module_utils.common.validation.check_type_str") > > * `_count_terms()` –> [`ansible.module_utils.common.validation.count_terms()`](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.validation.count_terms "ansible.module_utils.common.validation.count_terms") > > * `_get_wanted_type()` > > * `_handle_aliases()` > > * `_handle_no_log_values()` > > * `_handle_options()` > > * `_set_defaults()` > > * `_set_fallbacks()` > Modules or plugins using these private methods should use the public functions in [`ansible.module_utils.common.validation`](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#module-ansible.module_utils.common.validation "ansible.module_utils.common.validation") or [`ArgumentSpecValidator.validate()`](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.arg_spec.ArgumentSpecValidator.validate "ansible.module_utils.common.arg_spec.ArgumentSpecValidator.validate") if no public function was listed above. ### [Changes to](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.11.html#id7) [`ansible.module_utils.common.parameters`](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#module-ansible.module_utils.common.parameters "ansible.module_utils.common.parameters") [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.11.html#changes-to-ansible-module-utils-common-parameters "Link to this heading") The following functions in [`ansible.module_utils.common.parameters`](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#module-ansible.module_utils.common.parameters "ansible.module_utils.common.parameters") are now private and should not be used directly. Use [`ArgumentSpecValidator.validate()`](https://docs.ansible.com/projects/ansible-core/devel/reference_appendices/module_utils.html#ansible.module_utils.common.arg_spec.ArgumentSpecValidator.validate "ansible.module_utils.common.arg_spec.ArgumentSpecValidator.validate") instead. > * `list_no_log_values` > > * `list_deprecations` > > * `handle_aliases` > [Other](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.11.html#id8) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.11.html#other "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * **Upgrading**: If upgrading from `ansible < 2.10` or from `ansible-base` and using pip, you must `pip uninstall ansible` or `pip uninstall ansible-base` before installing `ansible-core` to avoid conflicts. * Python 3.8 on the controller node is a soft requirement for this release. `ansible-core` 2.11 still works with the same versions of Python that `ansible-base` 2.10 worked with, however 2.11 emits a warning when running on a controller node with a Python version less than 3.8. This warning can be disabled by setting `ANSIBLE_CONTROLLER_PYTHON_WARNING=False` in your environment. `ansible-core` 2.12 will require Python 3.8 or greater. * The configuration system now validates the `choices` field, so any settings that violate it and were ignored in 2.10 cause an error in 2.11. For example, `ANSIBLE_COLLECTIONS_ON_ANSIBLE_VERSION_MISMATCH=0` now causes an error (valid choices are `ignore`, `warn` or `error`). * The `ansible-galaxy` command now uses `resolvelib` for resolving dependencies. In most cases this should not make a user-facing difference beyond being more performant, but we note it here for posterity and completeness. * If you import Python `module_utils` into any modules you maintain, you may now mark the import as optional during the module payload build by wrapping the `import` statement in a `try` or `if` block. This allows modules to use `module_utils` that may not be present in all versions of Ansible or a collection, and to perform arbitrary recovery or fallback actions during module runtime. [Modules](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.11.html#id9) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.11.html#modules "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * The `apt_key` module has explicitly defined `file` as mutually exclusive with `data`, `keyserver` and `url`. They cannot be used together anymore. * The `meta` module now supports tags for user-defined tasks. Set the task’s tags to ‘always’ to maintain the previous behavior. Internal `meta` tasks continue to always run. ### [Modules removed](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.11.html#id10) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.11.html#modules-removed "Link to this heading") The following modules no longer exist: * No notable changes ### [Deprecation notices](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.11.html#id11) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.11.html#deprecation-notices "Link to this heading") No notable changes ### [Noteworthy module changes](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.11.html#id12) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.11.html#noteworthy-module-changes "Link to this heading") * facts - On NetBSD, `ansible_virtualization_type` now tries to report a more accurate result than `xen` when virtualized and not running on Xen. * facts - Virtualization facts now include `virtualization_tech_guest` and `virtualization_tech_host` keys. These are lists of virtualization technologies that a guest is a part of, or that a host provides, respectively. As an example, if you set up a host to provide both KVM and VirtualBox, both values are included in `virtualization_tech_host`. Similarly, a podman container running on a VM powered by KVM has a `virtualization_tech_guest` of `["kvm", "podman", "container"]`. * The parameter `filter` type is changed from `string` to `list` in the [setup](https://docs.ansible.com/projects/ansible-core/devel/collections/ansible/builtin/setup_module.html#setup-module) module in order to use more than one filter. Previous behavior (using a `string`) still remains and works as a single filter. [Plugins](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.11.html#id13) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.11.html#plugins "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ * inventory plugins - `CachePluginAdjudicator.flush()` now calls the underlying cache plugin’s `flush()` instead of only deleting keys that it knows about. Inventory plugins should use `delete()` to remove any specific keys. As a user, this means that when an inventory plugin calls its `clear_cache()` method, facts could also be flushed from the cache. To work around this, users can configure inventory plugins to use a cache backend that is independent of the facts cache. * callback plugins - `meta` task execution is now sent to `v2_playbook_on_task_start` like any other task. By default, only explicit meta tasks are sent there. Callback plugins can opt-in to receiving internal, implicitly created tasks to act on those as well, as noted in the plugin development documentation. * The `choices` are now validated, so plugins that were using incorrect or incomplete choices issue an error in 2.11 if the value provided does not match. This has a simple fix: update the entries in `choices` to match reality. [Porting custom scripts](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.11.html#id14) [](https://docs.ansible.com/projects/ansible-core/devel/porting_guides/porting_guide_core_2.11.html#porting-custom-scripts "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ No notable changes --- # Using Ansible on Windows, BSD, and z/OS UNIX — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * Using Ansible on Windows, BSD, and z/OS UNIX * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/os_guide/index.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Using Ansible on Windows, BSD, and z/OS UNIX[](https://docs.ansible.com/projects/ansible/latest/os_guide/index.html#using-ansible-on-windows-bsd-and-z-os-unix "Link to this heading") ======================================================================================================================================================================================== Note **Making Open Source More Inclusive** 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) . Welcome to the Ansible guide for Microsoft Windows and BSD. Because Windows is not a POSIX-compliant operating system, Ansible interacts with Windows hosts differently than Linux/Unix hosts. Likewise, managing hosts that run BSD is different than managing other Unix-like host operating systems. Find out everything you need to know about using Ansible on Windows and with BSD hosts. * [Managing BSD hosts with Ansible](https://docs.ansible.com/projects/ansible/latest/os_guide/intro_bsd.html) * [Connecting to BSD nodes](https://docs.ansible.com/projects/ansible/latest/os_guide/intro_bsd.html#connecting-to-bsd-nodes) * [Bootstrapping BSD](https://docs.ansible.com/projects/ansible/latest/os_guide/intro_bsd.html#bootstrapping-bsd) * [Setting the Python interpreter](https://docs.ansible.com/projects/ansible/latest/os_guide/intro_bsd.html#setting-the-python-interpreter) * [Which modules are available?](https://docs.ansible.com/projects/ansible/latest/os_guide/intro_bsd.html#which-modules-are-available) * [Using BSD as the control node](https://docs.ansible.com/projects/ansible/latest/os_guide/intro_bsd.html#using-bsd-as-the-control-node) * [BSD facts](https://docs.ansible.com/projects/ansible/latest/os_guide/intro_bsd.html#bsd-facts) * [BSD efforts and contributions](https://docs.ansible.com/projects/ansible/latest/os_guide/intro_bsd.html#bsd-efforts-and-contributions) * [Managing Windows hosts with Ansible](https://docs.ansible.com/projects/ansible/latest/os_guide/intro_windows.html) * [Windows App Control](https://docs.ansible.com/projects/ansible/latest/os_guide/windows_app_control.html) * [Desired State Configuration](https://docs.ansible.com/projects/ansible/latest/os_guide/windows_dsc.html) * [Windows performance](https://docs.ansible.com/projects/ansible/latest/os_guide/windows_performance.html) * [Windows SSH](https://docs.ansible.com/projects/ansible/latest/os_guide/windows_ssh.html) * [Using Ansible and Windows](https://docs.ansible.com/projects/ansible/latest/os_guide/windows_usage.html) * [Windows Remote Management](https://docs.ansible.com/projects/ansible/latest/os_guide/windows_winrm.html) * [WinRM Certificate Authentication](https://docs.ansible.com/projects/ansible/latest/os_guide/windows_winrm_certificate.html) * [Kerberos Authentication](https://docs.ansible.com/projects/ansible/latest/os_guide/windows_winrm_kerberos.html) * [Bootstrapping Windows](https://docs.ansible.com/projects/ansible/latest/os_guide/intro_windows.html#bootstrapping-windows) * [Connecting to Windows nodes](https://docs.ansible.com/projects/ansible/latest/os_guide/intro_windows.html#connecting-to-windows-nodes) * [Which modules are available?](https://docs.ansible.com/projects/ansible/latest/os_guide/intro_windows.html#which-modules-are-available) * [Using Windows as the control node](https://docs.ansible.com/projects/ansible/latest/os_guide/intro_windows.html#using-windows-as-the-control-node) * [Windows facts](https://docs.ansible.com/projects/ansible/latest/os_guide/intro_windows.html#windows-facts) * [Common Windows problems](https://docs.ansible.com/projects/ansible/latest/os_guide/intro_windows.html#common-windows-problems) * [Managing z/OS UNIX hosts with Ansible](https://docs.ansible.com/projects/ansible/latest/os_guide/intro_zos.html) * [Ansible and z/OS UNIX System Services](https://docs.ansible.com/projects/ansible/latest/os_guide/intro_zos.html#ansible-and-z-os-unix-system-services) * [The z/OS landscape](https://docs.ansible.com/projects/ansible/latest/os_guide/intro_zos.html#the-z-os-landscape) * [Using `ansible.builtin` modules with z/OS UNIX](https://docs.ansible.com/projects/ansible/latest/os_guide/intro_zos.html#using-ansible-builtin-modules-with-z-os-unix) * [Configure the remote environment](https://docs.ansible.com/projects/ansible/latest/os_guide/intro_zos.html#configure-the-remote-environment) * [Configure the remote Python interpreter](https://docs.ansible.com/projects/ansible/latest/os_guide/intro_zos.html#configure-the-remote-python-interpreter) * [Configure the remote shell](https://docs.ansible.com/projects/ansible/latest/os_guide/intro_zos.html#configure-the-remote-shell) * [Enable Ansible pipelining](https://docs.ansible.com/projects/ansible/latest/os_guide/intro_zos.html#enable-ansible-pipelining) * [Unreadable characters](https://docs.ansible.com/projects/ansible/latest/os_guide/intro_zos.html#unreadable-characters) * [Using z/OS as a control node](https://docs.ansible.com/projects/ansible/latest/os_guide/intro_zos.html#using-z-os-as-a-control-node) --- # Using Ansible playbooks — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * Using Ansible playbooks * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/playbook_guide/index.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Using Ansible playbooks[](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/index.html#using-ansible-playbooks "Link to this heading") ========================================================================================================================================================== Note **Making Open Source More Inclusive** 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) . Welcome to the Ansible playbooks guide. Playbooks are automation blueprints, in `YAML` format, that Ansible uses to deploy and configure nodes in an inventory. This guide introduces you to playbooks and then covers different use cases for tasks and plays, such as: * Executing tasks with elevated privileges or as a different user. * Using loops to repeat tasks for items in a list. * Delegating playbooks to execute tasks on different machines. * Running conditional tasks and evaluating conditions with playbook tests. * Using blocks to group sets of tasks. You can also learn how to use Ansible playbooks more effectively by using collections, creating reusable files and roles, including and importing playbooks, and running selected parts of a playbook with tags. * [Ansible playbooks](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_intro.html) * [Playbook syntax](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_intro.html#playbook-syntax) * [Playbook execution](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_intro.html#playbook-execution) * [Ansible-Pull](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_intro.html#ansible-pull) * [Verifying playbooks](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_intro.html#verifying-playbooks) * [Working with playbooks](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks.html) * [Templating (Jinja2)](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_templating.html) * [Using filters to manipulate data](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_filters.html) * [Tests](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_tests.html) * [Lookups](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_lookups.html) * [Python3 in templates](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_python_version.html) * [The now function: get the current time](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_templating_now.html) * [The undef function: add hint for undefined variables](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_templating_undef.html) * [Loops](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_loops.html) * [Controlling where tasks run: delegation and local actions](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_delegation.html) * [Conditionals](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_conditionals.html) * [Blocks](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_blocks.html) * [Handlers: running operations on change](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_handlers.html) * [Error handling in playbooks](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_error_handling.html) * [Setting the remote environment](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_environment.html) * [Working with language-specific version managers](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_environment.html#working-with-language-specific-version-managers) * [Reusing Ansible artifacts](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_reuse.html) * [Roles](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_reuse_roles.html) * [Module defaults](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_module_defaults.html) * [Interactive input: prompts](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_prompts.html) * [Using variables](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_variables.html) * [Discovering variables: facts and magic variables](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_vars_facts.html) * [Play Argument Validation](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_variables_validation.html) * [Specification Format](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_variables_validation.html#specification-format) * [Sample Specification](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_variables_validation.html#sample-specification) * [Playbook Example: Continuous Delivery and Rolling Upgrades](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/guide_rolling_upgrade.html) * [Executing playbooks](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_execution.html) * [Validating tasks: check mode and diff mode](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_checkmode.html) * [Understanding privilege escalation: become](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_privilege_escalation.html) * [Tags](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_tags.html) * [Executing playbooks for troubleshooting](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_startnstep.html) * [Debugging tasks](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_debugger.html) * [Asynchronous actions and polling](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_async.html) * [Controlling playbook execution: strategies and more](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_strategies.html) * [Advanced playbook syntax](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_advanced_syntax.html) * [Unsafe or raw strings](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_advanced_syntax.html#unsafe-or-raw-strings) * [YAML anchors and aliases: sharing variable values](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_advanced_syntax.html#yaml-anchors-and-aliases-sharing-variable-values) * [Manipulating data](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/complex_data_manipulation.html) * [Loops and list comprehensions](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/complex_data_manipulation.html#loops-and-list-comprehensions) * [Complex Type transformations](https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/complex_data_manipulation.html#complex-type-transformations) --- # How to build your inventory — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * [Building Ansible inventories](https://docs.ansible.com/projects/ansible/latest/inventory_guide/index.html) * How to build your inventory * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/inventory_guide/intro_inventory.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * How to build your inventory[](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#how-to-build-your-inventory "Link to this heading") ========================================================================================================================================================================= Ansible automates tasks on managed nodes or “hosts” in your infrastructure by using a list or group of lists known as inventory. Ansible composes its inventory from one or more ‘inventory sources’. While one of these sources can be the list of host names you pass at the command line, most Ansible users create inventory files. Your inventory defines the managed nodes you automate and the variables associated with those hosts. You can also specify groups. Groups allow you to reference multiple associated hosts to target for your automation or to define variables in bulk. Once you define your inventory, you use [patterns](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_patterns.html#intro-patterns) to select the hosts or groups you want Ansible to run against. The simplest inventory is a single file that contains a list of hosts and groups. The default location for this file is `/etc/ansible/hosts`. You can specify a different inventory source or sources at the command line by using the `-i ` option or by using the configuration system. Ansible [Inventory plugins](https://docs.ansible.com/projects/ansible/latest/plugins/inventory.html#inventory-plugins) supports a range of formats and sources, which makes your inventory flexible and customizable. As your inventory expands, you might need more than a single file to organize your hosts and groups. You have the following common options beyond the `/etc/ansible/hosts` file: * You can generate an inventory dynamically. For example, you can use an inventory plugin to list resources in one or more cloud providers or other sources. See [Working with dynamic inventory](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_dynamic_inventory.html#intro-dynamic-inventory) . * You can use multiple sources for inventory, including both dynamic inventory and static files. See [Passing multiple inventory sources](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#using-multiple-inventory-sources) . * You can create a directory with multiple inventory sources, static or dynamic. See [Organizing inventory in a directory](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#inventory-directory) . The following YAML snippets include an ellipsis (…) to indicate that the snippets are part of a larger YAML file. You can find out more about YAML syntax at [YAML Basics](https://docs.ansible.com/projects/ansible/latest/reference_appendices/YAMLSyntax.html#yaml-basics) . [Inventory basics: formats, hosts, and groups](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#id4) [](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#inventory-basics-formats-hosts-and-groups "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ You can create your inventory file in one of many formats, depending on the inventory plugins you have. The most common formats are INI and YAML because Ansible includes built-in support for them. This introduction focuses on these two formats, but many other formats and sources are possible. A basic INI `/etc/ansible/hosts` might look like this: mail.example.com \[webservers\] foo.example.com bar.example.com \[dbservers\] one.example.com two.example.com three.example.com The headings in brackets are group names. You can use group names to classify hosts and to decide which hosts you are controlling at what times and for what purpose. Group names should follow the same guidelines as [Creating valid variable names](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#valid-variable-names) . Here’s the same basic inventory file in YAML format: ungrouped: hosts: mail.example.com: webservers: hosts: foo.example.com: bar.example.com: dbservers: hosts: one.example.com: two.example.com: three.example.com: ### [Default groups](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#id5) [](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#default-groups "Link to this heading") Even if you do not define any groups in your inventory, Ansible creates two default groups: `all` and `ungrouped`. The `all` group contains every host. The `ungrouped` group contains all hosts that do not belong to any other group. Every host always belongs to at least two groups (`all` and `ungrouped`, or `all` and another group). For example, in the basic inventory above, the host `mail.example.com` belongs to the `all` and `ungrouped` groups. The host `two.example.com` belongs to the `all` and `dbservers` groups. Although `all` and `ungrouped` are always present, they can be implicit and might not appear in group listings like `group_names`. ### [Hosts in multiple groups](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#id6) [](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#hosts-in-multiple-groups "Link to this heading") You can put a host in more than one group. For example, you can include a production web server in a data center in Atlanta in the `[prod]`, `[atlanta]`, and `[webservers]` groups. You can create groups that track the following criteria: * **What** - An application, stack, or microservice (for example, database servers, web servers, and so on). * **Where** - A datacenter or region, to talk to local DNS, storage, and so on (for example, east, west). * **When** - The development stage, to avoid testing on production resources (for example, prod, test). The following example extends the previous YAML inventory to include what, when, and where: ungrouped: hosts: mail.example.com: webservers: hosts: foo.example.com: bar.example.com: dbservers: hosts: one.example.com: two.example.com: three.example.com: east: hosts: foo.example.com: one.example.com: two.example.com: west: hosts: bar.example.com: three.example.com: prod: hosts: foo.example.com: one.example.com: two.example.com: test: hosts: bar.example.com: three.example.com: As the example shows, `one.example.com` exists in the `dbservers`, `east`, and `prod` groups. ### [Grouping groups: parent/child group relationships](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#id7) [](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#grouping-groups-parent-child-group-relationships "Link to this heading") You can create parent/child relationships among groups. Parent groups are also known as nested groups or groups of groups. For example, if all your production hosts are already in groups such as  `atlanta_prod` and `denver_prod`, you can create a `production` group that includes those smaller groups. This approach reduces maintenance because you add or remove hosts from the parent group by editing the child groups. To create parent/child relationships for groups, use one of the following methods: * In INI format, use the `:children` suffix. * In YAML format, use the `children:` entry. The following example shows the same inventory as above, simplified with parent groups for the `prod` and `test` groups: ungrouped: hosts: mail.example.com: webservers: hosts: foo.example.com: bar.example.com: dbservers: hosts: one.example.com: two.example.com: three.example.com: east: hosts: foo.example.com: one.example.com: two.example.com: west: hosts: bar.example.com: three.example.com: prod: children: east: test: children: west: Note the following properties of child groups: * Any host that is a member of a child group is automatically a member of the parent group. * A group can have multiple parents and children, but not circular relationships. * A host can be in multiple groups, but Ansible processes only **one** instance of the host at runtime. Ansible merges the data from multiple groups. * Hosts and groups are always ‘global’. If you define a host or group more than once under different ‘branches’ or ‘instances’, the host or group remains the same entity. Defining a host or group more than once either adds new information to it or overwrites any conflicting information with the latest definition. ### [Adding ranges of hosts](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#id8) [](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#adding-ranges-of-hosts "Link to this heading") Some plugins, like YAML and INI, support adding ranges of hosts. If you have many hosts with a similar pattern, you can add the hosts as a range rather than listing each hostname separately: In INI: \[webservers\] www\[01:50\].example.com In YAML: \# ... webservers: hosts: www\[01:50\].example.com: You can specify a stride (increments between sequence numbers) when you define a numeric range of hosts: In INI: \[webservers\] www\[01:50:2\].example.com In YAML: \# ... webservers: hosts: www\[01:50:2\].example.com: The example above matches the subdomains www01, www03, www05, …, www49, but not www00, www02, www50, and so on, because the stride (increment) is 2 units for each step. For numeric patterns, you can include or remove leading zeros as desired. Ranges are inclusive. You can also define alphabetic ranges: \[databases\] db-\[a:f\].example.com [Passing multiple inventory sources](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#id9) [](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#passing-multiple-inventory-sources "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can target multiple inventory sources (static files, directories, dynamic inventory scripts or anything supported by inventory plugins) at the same time. To do this, specify multiple inventory sources from the command line (see below) or by configuration, either by setting [`ANSIBLE_INVENTORY`](https://docs.ansible.com/projects/ansible/latest/reference_appendices/config.html#envvar-ANSIBLE_INVENTORY) or in `ansible.cfg` ([DEFAULT\_HOST\_LIST](https://docs.ansible.com/projects/ansible/latest/reference_appendices/config.html#default-host-list) ). This capability can be useful when you want to target normally separate environments, like staging and production, at the same time for a specific action. To target two inventory sources from the command line: ansible-playbook get\_logs.yml \-i staging \-i production [Organizing inventory in a directory](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#id10) [](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#organizing-inventory-in-a-directory "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can consolidate multiple inventory sources in a single directory. The simplest version of this approach is a directory with multiple files instead of a single inventory file. Maintaining a single file becomes difficult when the file gets too long. If you have multiple teams and multiple automation projects, creating one inventory file per team or project lets everyone easily find the hosts and groups that matter to them. You can also still use the files individually or in subsets, depending on how you configure or call Ansible. These files can use all formats or plugin configurations (for example, YAML or INI). In this case, your directory becomes your ‘single’ inventory source, and Ansible aggregates the multiple sources it finds in that directory. By default, Ansible ignores some directories and extensions, but you can change this behavior in the configuration ([INVENTORY\_IGNORE\_PATTERNS](https://docs.ansible.com/projects/ansible/latest/reference_appendices/config.html#inventory-ignore-patterns) and [INVENTORY\_IGNORE\_EXTS](https://docs.ansible.com/projects/ansible/latest/reference_appendices/config.html#inventory-ignore-exts) ). You can also combine multiple inventory source types in an inventory directory. This method can be useful for combining static and dynamic hosts and managing them as one inventory. The following inventory directory combines an inventory plugin source, a dynamic inventory script, and a file with static hosts: inventory/ openstack.yml # configure inventory plugin to get hosts from OpenStack cloud dynamic-inventory.py # add additional hosts with dynamic inventory script on-prem # add static hosts and groups parent-groups # add static hosts and groups You can target this inventory directory as follows: ansible-playbook example.yml \-i inventory You can also configure the inventory directory in your `ansible.cfg` file. See [Configuring Ansible](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_configuration.html#intro-configuration) for more details. Ansible reads and loads files from the top directory down in alphabetically sorted order. ### [Managing inventory load order](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#id11) [](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#managing-inventory-load-order "Link to this heading") Ansible loads inventory sources in the order you supply them. It defines hosts, groups, and variables as it encounters them in the source files, adding the `all` and `ungrouped` groups at the end if needed. Depending on the inventory plugin or plugins you use, you might need to rearrange the order of sources to ensure that parent/child-defined groups or hosts exist as the plugins expect. Otherwise, you might encounter a parsing error. For example, the YAML and INI inventory plugins discard empty groups (groups with no associated hosts) when they finish processing each source. If you define a variable multiple times, Ansible overwrites the previous value. The last definition wins. [Adding variables to inventory](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#id12) [](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#adding-variables-to-inventory "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can define variables that relate to a specific host or group in your inventory. A simple way to start is by adding variables directly to the hosts and groups in a YAML or INI inventory source. This guide documents how to add variables in the inventory source for simplicity. However, you can also use [Vars plugins](https://docs.ansible.com/projects/ansible/latest/plugins/vars.html#vars-plugins) to add variables from many other sources. By default, Ansible ships with the [host\_group\_vars](https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/host_group_vars_vars.html#host-group-vars-vars) plugin, which allows you to define variables in separate host and group variable files. Using separate files is a more robust approach to describing your system policy than defining variables in the inventory source. See [Organizing host and group variables](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#splitting-out-vars) for guidelines on how to store variable values in individual files in the ‘host\_vars’ and ‘group\_vars’ directories. [Assigning a variable to one machine: host variables](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#id13) [](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#assigning-a-variable-to-one-machine-host-variables "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can easily assign a variable to a single host and then use that variable later in playbooks. You can do this directly in your inventory file. In INI: \[atlanta\] host1 http\_port=80 maxRequestsPerChild=808 host2 http\_port=303 maxRequestsPerChild=909 In YAML: atlanta: hosts: host1: http\_port: 80 maxRequestsPerChild: 808 host2: http\_port: 303 maxRequestsPerChild: 909 Unique values like non-standard SSH ports work well as host variables. You can add them to your Ansible inventory by adding the port number after the hostname with a colon: badwolf.example.com:5309 You can use host variables to define ‘Connection variables’. Connection variables configure `connection`, `shell`, and `become` plugins to enable task execution on the host. For example: \[targets\] localhost ansible\_connection=local other1.example.com ansible\_connection=ssh ansible\_user=myuser other2.example.com ansible\_connection=ssh ansible\_user=myotheruser ### [Inventory aliases](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#id14) [](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#inventory-aliases "Link to this heading") The `inventory_hostname` is the unique identifier for a host in Ansible. This identifier can be an IP address or a hostname, but it can also be just an ‘alias’ or short name for the host. In INI: jumper ansible\_port=5555 ansible\_host=192.0.2.50 In YAML: \# ... hosts: jumper: ansible\_port: 5555 ansible\_host: 192.0.2.50 In this example, running Ansible against the host alias “jumper” connects to 192.0.2.50 on port 5555. See [behavioral inventory parameters](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#behavioral-parameters) to further customize the connection to hosts. This feature is also useful for targeting the same host more than once, but remember that tasks can run in parallel: In INI: jumper1 ansible\_port=5555 ansible\_host=192.0.2.50 jumper2 ansible\_port=5555 ansible\_host=192.0.2.50 In YAML: \# ... hosts: jumper1: ansible\_port: 5555 ansible\_host: 192.0.2.50 jumper2: ansible\_port: 5555 ansible\_host: 192.0.2.50 [Defining variables in INI format](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#id15) [](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#defining-variables-in-ini-format "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Ansible interprets values that you pass in the INI format by using the `key=value` syntax differently depending on where you declare them: * When you declare a value inline with the host, Ansible interprets the INI value as a Python literal structure (for example, a string, number, tuple, list, dict, boolean, or None). Host lines accept multiple `key=value` parameters per line. Therefore, you need a way to indicate that a space is part of a value rather than a separator. You can quote values that contain whitespace (using single or double quotes). See the [Python shlex parsing rules](https://docs.python.org/3/library/shlex.html#parsing-rules) for details. * When you declare a value in a `:vars` section, Ansible interprets the INI value as a string. For example, `var=FALSE` creates a string with the value ‘FALSE’. Unlike host lines, `:vars` sections accept only a single entry per line, so everything after the `=` becomes the value for the entry. If you need a variable from an INI inventory to have a certain type (for example, a string or a boolean), always specify the type with a filter in your task. Do not rely on types that you set in INI inventories when you consume variables. Consider using the YAML format for inventory sources to avoid confusion about the actual type of a variable. The YAML inventory plugin processes variable values consistently and correctly. [Assigning a variable to many machines: group variables](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#id16) [](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#assigning-a-variable-to-many-machines-group-variables "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- If all hosts in a group share a variable value, you can apply that variable to an entire group at once. In INI: \[atlanta\] host1 host2 \[atlanta:vars\] ntp\_server=ntp.atlanta.example.com proxy=proxy.atlanta.example.com In YAML: atlanta: hosts: host1: host2: vars: ntp\_server: ntp.atlanta.example.com proxy: proxy.atlanta.example.com Group variables are a convenient way to apply variables to multiple hosts at once. Before executing, however, Ansible always flattens variables, including inventory variables, to the host level. If a host is a member of multiple groups, Ansible reads variable values from all of those groups. If you assign different values to the same variable in different groups, Ansible chooses which value to use based on internal [rules for merging](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#how-we-merge) . ### [Inheriting variable values: group variables for groups of groups](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#id17) [](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#inheriting-variable-values-group-variables-for-groups-of-groups "Link to this heading") You can apply variables to parent groups (nested groups or groups of groups) as well as to child groups. The syntax is the same: `:vars` for INI format and `vars:` for YAML format: In INI: \[atlanta\] host1 host2 \[raleigh\] host2 host3 \[southeast:children\] atlanta raleigh \[southeast:vars\] some\_server=foo.southeast.example.com halon\_system\_timeout=30 self\_destruct\_countdown=60 escape\_pods=2 \[usa:children\] southeast northeast southwest northwest In YAML: usa: children: southeast: children: atlanta: hosts: host1: host2: raleigh: hosts: host2: host3: vars: some\_server: foo.southeast.example.com halon\_system\_timeout: 30 self\_destruct\_countdown: 60 escape\_pods: 2 northeast: northwest: southwest: A child group’s variables have higher precedence (they override) than a parent group’s variables. [Organizing host and group variables](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#id18) [](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#organizing-host-and-group-variables "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Although you can define variables in the inventory source, you can also use [Vars plugins](https://docs.ansible.com/projects/ansible/latest/plugins/vars.html#vars-plugins) to define alternate sources for your variables. The default vars plugin that Ansible ships with, [host\_group\_vars](https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/host_group_vars_vars.html#host-group-vars-vars) , lets you use separate host and group variable files. This method helps you organize your variable values more easily. You can also use lists and hash data in these files, which you cannot do in your main inventory file. For the `host_group_vars` plugin, your host and group variable files must use YAML syntax. Valid file extensions are ‘.yml’, ‘.yaml’, ‘.json’, or no file extension. See [YAML Syntax](https://docs.ansible.com/projects/ansible/latest/reference_appendices/YAMLSyntax.html#yaml-syntax) if you are new to YAML. The `host_group_vars` plugin loads host and group variable files by searching paths relative to the inventory source or the playbook file. If your inventory file at `/etc/ansible/hosts` contains a host named ‘foosball’ that belongs to the `raleigh` and `webservers` groups, that host will use variables from the YAML files in the following locations: /etc/ansible/group\_vars/raleigh \# can optionally end in '.yml', '.yaml', or '.json' /etc/ansible/group\_vars/webservers /etc/ansible/host\_vars/foosball For example, if you group hosts in your inventory by datacenter, and each datacenter uses its own NTP server and database server, you can create a file named `/etc/ansible/group_vars/raleigh` to store the variables for the `raleigh` group: \--- ntp\_server: acme.example.org database\_server: storage.example.org You can also create _directories_ named after your groups or hosts. Ansible reads all the files in these directories in lexicographical order. Here is an example with the ‘raleigh’ group: /etc/ansible/group\_vars/raleigh/db\_settings /etc/ansible/group\_vars/raleigh/cluster\_settings All hosts in the ‘raleigh’ group have the variables that you define in these files available to them. This method is very useful for keeping your variables organized when a single file gets too big, or when you want to use [Ansible Vault](https://docs.ansible.com/projects/ansible/latest/vault_guide/vault_using_encrypted_content.html#playbooks-vault) on some group variables. Ansible’s [host\_group\_vars](https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/host_group_vars_vars.html#host-group-vars-vars) vars plugin can also add `group_vars/` and `host_vars/` directories to your playbook directory when you use `ansible-playbook`. However, not all Ansible commands have a playbook (for example, `ansible` or `ansible-console`). For those commands, you can use the `--playbook-dir` option to provide the directory on the command line. If you have sources for the vars plugins relative to both the playbook directory and the inventory directory, the variables that Ansible sources relative to the playbook override the variables that it sources relative to the inventory source. To track changes to your inventory and variable definitions, keep your inventory sources and their relative variable directories and files in a Git repository or other version control system. [How variables are merged](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#id19) [](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#how-variables-are-merged "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ Note Ansible merges variables from different sources and applies precedence to some variables over others according to a set of rules. For example, variables that occur higher in an inventory can override variables that occur lower in the inventory. See [Variable precedence: where should I put a variable?](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#ansible-variable-precedence) for more information. Before it runs a play, Ansible merges and flattens variables to the specific host. This process keeps Ansible focused on the Host and Task, so groups do not survive outside of inventory and host matching. By default, Ansible overwrites variables, including the ones that you define for a group or host (see [DEFAULT\_HASH\_BEHAVIOUR](https://docs.ansible.com/projects/ansible/latest/reference_appendices/config.html#default-hash-behaviour) ). The order/precedence for inventory entities is (from lowest to highest): The following list shows the order of precedence for inventory entities, from lowest to highest: * `all` group (because it is the ‘parent’ of all other groups) * parent group * child group * host By default, Ansible merges groups at the same parent/child level in alphabetical order. Variables from the last group that Ansible loads overwrite variables from the previous groups. For example, Ansible merges an `a_group` with a `b_group`, and matching variables from `b_group` overwrite the variables in `a_group`. You can fine-tune this merge behavior by setting the group variable `ansible_group_priority`. This variable overrides the alphabetical sorting for the merge order for groups of the same level (after Ansible resolves the parent/child order). The larger the number, the later Ansible merges the group, giving it higher priority. This variable defaults to `1` if you do not set it. For example: a\_group: vars: testvar: a ansible\_group\_priority: 10 b\_group: vars: testvar: b In this example, if both groups have the same priority, the result would normally be `testvar == b`. However, because we give `a_group` a higher priority, the result is `testvar == a`. You can set `ansible_group_priority` only in an inventory source, not in `group_vars/`. Ansible uses this variable when it loads the `group_vars/` directory. ### [Managing inventory variable load order](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#id20) [](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#managing-inventory-variable-load-order "Link to this heading") This section describes how to control variable precedence by managing the load order of inventory sources. You can pass sources in a specific order at the command line or use prefixes in the filenames of sources within a directory. When you use multiple inventory sources, remember that Ansible resolves any variable conflicts according to the rules described in [How variables are merged](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#how-we-merge) and [Variable precedence: where should I put a variable?](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#ansible-variable-precedence) . You can control the merging order of variables in inventory sources to get the variable value you need. When you pass multiple inventory sources at the command line, Ansible merges variables in the order you pass those parameters. If the `[all:vars]` section in the staging inventory defines `myvar = 1` and the production inventory defines `myvar = 2`, then the following outcomes are true: * If you pass `-i staging -i production`, Ansible runs the playbook with `myvar = 2`. * If you pass `-i production -i staging`, Ansible runs the playbook with `myvar = 1`. When you put multiple inventory sources in a directory, Ansible merges the sources in alphabetical order according to their filenames. You can control the load order by adding prefixes to the files: inventory/ 01-openstack.yml # configure inventory plugin to get hosts from Openstack cloud 02-dynamic-inventory.py # add additional hosts with dynamic inventory script 03-static-inventory # add static hosts group\_vars/ all.yml # assign variables to all hosts If `01-openstack.yml` defines `myvar = 1` for the group `all`, `02-dynamic-inventory.py` defines `myvar = 2`, and `03-static-inventory` defines `myvar = 3`, Ansible runs the playbook with `myvar = 3`. For more details on inventory plugins and dynamic inventory scripts see [Inventory plugins](https://docs.ansible.com/projects/ansible/latest/plugins/inventory.html#inventory-plugins) and [Working with dynamic inventory](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_dynamic_inventory.html#intro-dynamic-inventory) . [Connecting to hosts: behavioral inventory parameters](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#id21) [](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#connecting-to-hosts-behavioral-inventory-parameters "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- As described above, you can set the following variables to control how Ansible interacts with remote hosts. Host connection: Note Ansible does not expose a channel to allow communication between the user and the ssh process to accept a password manually to decrypt an ssh key when using the ssh connection plugin (which is the default). The use of `ssh-agent` is highly recommended. ansible\_connection Specifies the connection type to the host. This can be the name of any Ansible connection plugin. SSH protocol types are `ssh` or `paramiko`. The default is `ssh`. General for all connections: ansible\_host Specifies the resolvable name or IP of the host to connect to, if it is different from the alias you wish to give to it. Never set it to depend on `inventory_hostname`. If you really need something like that, use `inventory_hostname_short` so it can work with delegation. ansible\_port The connection port number, if not the default (22 for ssh). ansible\_user The username to use when connecting (logging in) to the host. ansible\_password The password to use to authenticate to the host. (Never store this variable in plain text. Always use a vault. See [Keep vaulted variables safely visible](https://docs.ansible.com/projects/ansible/latest/tips_tricks/ansible_tips_tricks.html#tip-for-variables-and-vaults) .) Specific to the SSH connection plugin: ansible\_ssh\_private\_key\_file Private key file used by SSH. This is useful if you use multiple keys and you do not want to use SSH agent. ansible\_ssh\_common\_args Ansible always appends this setting to the default command line for **sftp**, **scp**, and **ssh**. This is useful for configuring a `ProxyCommand` for a certain host or group. ansible\_sftp\_extra\_args Ansible always appends this setting to the default **sftp** command line. ansible\_scp\_extra\_args Ansible always appends this setting to the default **scp** command line. ansible\_ssh\_extra\_args Ansible always appends this setting to the default **ssh** command line. ansible\_ssh\_pipelining Specifies whether to use SSH pipelining. This can override the `pipelining` setting in `ansible.cfg`. ansible\_ssh\_executable (added in version 2.2) This setting overrides the default behavior to use the system **ssh**. It can override the `ssh_executable` setting in the `ssh_connection` section of `ansible.cfg`. Privilege escalation (see [Ansible Privilege Escalation](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_privilege_escalation.html#become) for further details): ansible\_become Equivalent to `ansible_sudo` or `ansible_su`; allows you to force privilege escalation. ansible\_become\_method Allows you to set the privilege escalation method to a matching become plugin. ansible\_become\_user Equivalent to `ansible_sudo_user` or `ansible_su_user`; allows you to set the user you become through privilege escalation. ansible\_become\_password Equivalent to `ansible_sudo_password` or `ansible_su_password`; allows you to set the privilege escalation password. (Never store this variable in plain text. Always use a vault. See [Keep vaulted variables safely visible](https://docs.ansible.com/projects/ansible/latest/tips_tricks/ansible_tips_tricks.html#tip-for-variables-and-vaults) .) ansible\_become\_exe Equivalent to `ansible_sudo_exe` or `ansible_su_exe`; allows you to set the executable for the escalation method you selected. ansible\_become\_flags Equivalent to `ansible_sudo_flags` or `ansible_su_flags`; allows you to set the flags passed to the selected escalation method. You can also set this globally in `ansible.cfg` in the `become_flags` option under `privilege_escalation`. Remote host environment parameters: ansible\_shell\_type Specifies the shell type of the target system. You should not use this setting unless you have set the [ansible\_shell\_executable](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#ansible-shell-executable) to a non-Bourne (sh) compatible shell.  By default, Ansible formats commands using `sh`\-style syntax.  If you set this to `csh` or `fish`, commands that Ansible executes on target systems follow those shell’s syntax instead. ansible\_python\_interpreter Specifies the target host Python path. This is useful for systems with more than one Python or for systems where Python is not located at **/usr/bin/python**, such as \*BSD, or where **/usr/bin/python** is not a 2.X series Python.  We do not use the **/usr/bin/env** mechanism because that requires the remote user’s path to be set correctly and also assumes the **python** executable is named python, where the executable might be named something like **python2.6**. ansible\_\*\_interpreter Works for any language, such as Ruby or Perl, and works just like [ansible\_python\_interpreter](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#ansible-python-interpreter) . This variable replaces the shebang of modules that will run on that host. New in version 2.1. ansible\_shell\_executable This setting sets the shell the Ansible control node will use on the target machine. It overrides `executable` in `ansible.cfg`, which defaults to **/bin/sh**.  You should only change this value if it is not possible to use **/bin/sh** (in other words, if **/bin/sh** is not installed on the target machine or cannot be run from sudo.). Examples from an Ansible-INI host file: some\_host ansible\_port=2222 ansible\_user=manager aws\_host ansible\_ssh\_private\_key\_file=/home/example/.ssh/aws.pem freebsd\_host ansible\_python\_interpreter=/usr/local/bin/python ruby\_module\_host ansible\_ruby\_interpreter=/usr/bin/ruby.1.9.3 ### [Non-SSH connection types](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#id22) [](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#non-ssh-connection-types "Link to this heading") As stated in the previous section, Ansible executes playbooks over SSH by default, but it is not limited to this connection type. You can change the connection type with the host-specific parameter `ansible_connection=`. For a full list of available plugins and examples, see [Plugin list](https://docs.ansible.com/projects/ansible/latest/plugins/connection.html#connection-plugin-list) . [Inventory setup examples](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#id23) [](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#inventory-setup-examples "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ See also [Sample Ansible setup](https://docs.ansible.com/projects/ansible/latest/tips_tricks/sample_setup.html#sample-setup) , which shows inventory along with playbooks and other Ansible artifacts. ### [Example: One inventory per environment](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#id24) [](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#example-one-inventory-per-environment "Link to this heading") If you need to manage multiple environments, consider defining only the hosts of a single environment in each inventory. This way, it is harder to, for example, accidentally change the state of nodes inside the “test” environment when you wanted to update some “staging” servers. For the example mentioned above, you could have an `inventory_test` file: \[dbservers\] db01.test.example.com db02.test.example.com \[appservers\] app01.test.example.com app02.test.example.com app03.test.example.com That file only includes hosts that are part of the “test” environment. You can define the “staging” machines in another file called `inventory_staging`: \[dbservers\] db01.staging.example.com db02.staging.example.com \[appservers\] app01.staging.example.com app02.staging.example.com app03.staging.example.com To apply a playbook called `site.yml` to all the app servers in the test environment, use the following command: ansible-playbook \-i inventory\_test \-l appservers site.yml ### [Example: Group by function](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#id25) [](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#example-group-by-function "Link to this heading") In the previous section, you already saw an example of using groups to cluster hosts that have the same function. This approach allows you, for example, to define firewall rules inside a playbook or role that affect only database servers: \- hosts: dbservers tasks: \- name: Allow access from 10.0.0.1 ansible.builtin.iptables: chain: INPUT jump: ACCEPT source: 10.0.0.1 ### [Example: Group by location](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#id26) [](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#example-group-by-location "Link to this heading") Other tasks might focus on where a certain host is located. Let’s say that `db01.test.example.com` and `app01.test.example.com` are located in DC1, while `db02.test.example.com` is in DC2: \[dc1\] db01.test.example.com app01.test.example.com \[dc2\] db02.test.example.com In practice, you might end up mixing all these setups. For example, you might need to update all nodes in a specific data center on one day, while on another day, you might need to update all the application servers no matter their location. See also [Inventory plugins](https://docs.ansible.com/projects/ansible/latest/plugins/inventory.html#inventory-plugins) Pulling inventory from dynamic or static sources [Working with dynamic inventory](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_dynamic_inventory.html#intro-dynamic-inventory) Pulling inventory from dynamic sources, such as cloud providers [Introduction to ad hoc commands](https://docs.ansible.com/projects/ansible/latest/command_guide/intro_adhoc.html#intro-adhoc) Examples of basic commands [Working with playbooks](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks.html#working-with-playbooks) Learning Ansible’s configuration, deployment, and orchestration language. [Communication](https://docs.ansible.com/projects/ansible/latest/community/communication.html#communication) Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide --- # index - Ansible Lint Documentation [Skip to content](https://docs.ansible.com/projects/lint/rules/#rules) [](https://github.com/ansible/ansible-lint/blob/main/docs/rules/index.md "Edit this page") [](https://github.com/ansible/ansible-lint/raw/main/docs/rules/index.md "View source of this page") Rules[¶](https://docs.ansible.com/projects/lint/rules/#rules "Permanent link") =============================================================================== * [args](https://docs.ansible.com/projects/lint/rules/args/#args) * [avoid-implicit](https://docs.ansible.com/projects/lint/rules/avoid-implicit/#avoid-implicit) * [complexity](https://docs.ansible.com/projects/lint/rules/complexity/#complexity) * [command-instead-of-module](https://docs.ansible.com/projects/lint/rules/command-instead-of-module/#command-instead-of-module) * [command-instead-of-shell](https://docs.ansible.com/projects/lint/rules/command-instead-of-shell/#command-instead-of-shell) * [deprecated-bare-vars](https://docs.ansible.com/projects/lint/rules/deprecated-bare-vars/#deprecated-bare-vars) * [deprecated-local-action](https://docs.ansible.com/projects/lint/rules/deprecated-local-action/#deprecated-local-action) * [deprecated-module](https://docs.ansible.com/projects/lint/rules/deprecated-module/#deprecated-module) * [empty-string-compare](https://docs.ansible.com/projects/lint/rules/empty-string-compare/#empty-string-compare) * [fqcn](https://docs.ansible.com/projects/lint/rules/fqcn/#fqcn) * [galaxy](https://docs.ansible.com/projects/lint/rules/galaxy/#galaxy) * [galaxy-version-incorrect](https://docs.ansible.com/projects/lint/rules/galaxy-version-incorrect/#galaxy-version-incorrect) * [ignore-errors](https://docs.ansible.com/projects/lint/rules/ignore-errors/#ignore-errors) * [inline-env-var](https://docs.ansible.com/projects/lint/rules/inline-env-var/#inline-env-var) * [internal-error](https://docs.ansible.com/projects/lint/rules/internal-error/#internal-error) * [jinja](https://docs.ansible.com/projects/lint/rules/jinja/#jinja) * [jinja-template-extension](https://docs.ansible.com/projects/lint/rules/jinja-template-extension/#jinja-template-extension) * [key-order](https://docs.ansible.com/projects/lint/rules/key-order/#key-order) * [latest](https://docs.ansible.com/projects/lint/rules/latest/#latest) * [literal-compare](https://docs.ansible.com/projects/lint/rules/literal-compare/#literal-compare) * [load-failure](https://docs.ansible.com/projects/lint/rules/load-failure/#load-failure) * [loop-var-prefix](https://docs.ansible.com/projects/lint/rules/loop-var-prefix/#loop-var-prefix) * [meta-incorrect](https://docs.ansible.com/projects/lint/rules/meta-incorrect/#meta-incorrect) * [meta-no-tags](https://docs.ansible.com/projects/lint/rules/meta-no-tags/#meta-no-tags) * [meta-runtime](https://docs.ansible.com/projects/lint/rules/meta-runtime/#meta-runtime) * [meta-video-links](https://docs.ansible.com/projects/lint/rules/meta-video-links/#meta-video-links) * [name](https://docs.ansible.com/projects/lint/rules/name/#name) * [no-changed-when](https://docs.ansible.com/projects/lint/rules/no-changed-when/#no-changed-when) * [no-free-form](https://docs.ansible.com/projects/lint/rules/no-free-form/#no-free-form) * [no-handler](https://docs.ansible.com/projects/lint/rules/no-handler/#no-handler) * [no-jinja-when](https://docs.ansible.com/projects/lint/rules/no-jinja-when/#no-jinja-when) * [no-log-password](https://docs.ansible.com/projects/lint/rules/no-log-password/#no-log-password) * [no-prompting](https://docs.ansible.com/projects/lint/rules/no-prompting/#no-prompting) * [no-relative-paths](https://docs.ansible.com/projects/lint/rules/no-relative-paths/#no-relative-paths) * [no-same-owner](https://docs.ansible.com/projects/lint/rules/no-same-owner/#no-same-owner) * [no-tabs](https://docs.ansible.com/projects/lint/rules/no-tabs/#no-tabs) * [only-builtins](https://docs.ansible.com/projects/lint/rules/only-builtins/#only-builtins) * [package-latest](https://docs.ansible.com/projects/lint/rules/package-latest/#package-latest) * [parser-error](https://docs.ansible.com/projects/lint/rules/parser-error/#parser-error) * [partial-become](https://docs.ansible.com/projects/lint/rules/partial-become/#partial-become) * [playbook-extension](https://docs.ansible.com/projects/lint/rules/playbook-extension/#playbook-extension) * [risky-file-permissions](https://docs.ansible.com/projects/lint/rules/risky-file-permissions/#risky-file-permissions) * [risky-octal](https://docs.ansible.com/projects/lint/rules/risky-octal/#risky-octal) * [risky-shell-pipe](https://docs.ansible.com/projects/lint/rules/risky-shell-pipe/#risky-shell-pipe) * [role-name](https://docs.ansible.com/projects/lint/rules/role-name/#role-name) * [run-once](https://docs.ansible.com/projects/lint/rules/run-once/#run-once) * [sanity](https://docs.ansible.com/projects/lint/rules/sanity/#sanity) * [schema](https://docs.ansible.com/projects/lint/rules/schema/#schema) * [syntax-check](https://docs.ansible.com/projects/lint/rules/syntax-check/#syntax-check) * [var-naming](https://docs.ansible.com/projects/lint/rules/var-naming/#var-naming) * [warning](https://docs.ansible.com/projects/lint/rules/warning/#warning) * [yaml](https://docs.ansible.com/projects/lint/rules/yaml/#yaml) Back to top --- # Working with command line tools — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * [Using Ansible command line tools](https://docs.ansible.com/projects/ansible-core/devel/command_guide/index.html) * Working with command line tools * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/command_guide/command_line_tools.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Working with command line tools[](https://docs.ansible.com/projects/ansible-core/devel/command_guide/command_line_tools.html#working-with-command-line-tools "Link to this heading") ====================================================================================================================================================================================== Most users are familiar with ansible and ansible-playbook, but those are not the only utilities Ansible provides. Below is a complete list of Ansible utilities. Each page contains a description of the utility and a listing of supported parameters. Note You should not run most Ansible CLI tools in parallel against the same targets. * [ansible](https://docs.ansible.com/projects/ansible-core/devel/cli/ansible.html) * [ansible-config](https://docs.ansible.com/projects/ansible-core/devel/cli/ansible-config.html) * [ansible-console](https://docs.ansible.com/projects/ansible-core/devel/cli/ansible-console.html) * [ansible-doc](https://docs.ansible.com/projects/ansible-core/devel/cli/ansible-doc.html) * [ansible-galaxy](https://docs.ansible.com/projects/ansible-core/devel/cli/ansible-galaxy.html) * [ansible-inventory](https://docs.ansible.com/projects/ansible-core/devel/cli/ansible-inventory.html) * [ansible-playbook](https://docs.ansible.com/projects/ansible-core/devel/cli/ansible-playbook.html) * [ansible-pull](https://docs.ansible.com/projects/ansible-core/devel/cli/ansible-pull.html) * [ansible-vault](https://docs.ansible.com/projects/ansible-core/devel/cli/ansible-vault.html) --- # Using Ansible playbooks — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * Using Ansible playbooks * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/playbook_guide/index.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Using Ansible playbooks[](https://docs.ansible.com/projects/ansible/latest/playbook_guide/index.html#using-ansible-playbooks "Link to this heading") ====================================================================================================================================================== Note **Making Open Source More Inclusive** 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) . Welcome to the Ansible playbooks guide. Playbooks are automation blueprints, in `YAML` format, that Ansible uses to deploy and configure nodes in an inventory. This guide introduces you to playbooks and then covers different use cases for tasks and plays, such as: * Executing tasks with elevated privileges or as a different user. * Using loops to repeat tasks for items in a list. * Delegating playbooks to execute tasks on different machines. * Running conditional tasks and evaluating conditions with playbook tests. * Using blocks to group sets of tasks. You can also learn how to use Ansible playbooks more effectively by using collections, creating reusable files and roles, including and importing playbooks, and running selected parts of a playbook with tags. * [Ansible playbooks](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_intro.html) * [Playbook syntax](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_intro.html#playbook-syntax) * [Playbook execution](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_intro.html#playbook-execution) * [Ansible-Pull](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_intro.html#ansible-pull) * [Verifying playbooks](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_intro.html#verifying-playbooks) * [Working with playbooks](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks.html) * [Templating (Jinja2)](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_templating.html) * [Using filters to manipulate data](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_filters.html) * [Tests](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_tests.html) * [Lookups](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_lookups.html) * [Python3 in templates](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_python_version.html) * [The now function: get the current time](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_templating_now.html) * [The undef function: add hint for undefined variables](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_templating_undef.html) * [Loops](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_loops.html) * [Controlling where tasks run: delegation and local actions](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_delegation.html) * [Conditionals](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_conditionals.html) * [Blocks](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_blocks.html) * [Handlers: running operations on change](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_handlers.html) * [Error handling in playbooks](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_error_handling.html) * [Setting the remote environment](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_environment.html) * [Working with language-specific version managers](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_environment.html#working-with-language-specific-version-managers) * [Reusing Ansible artifacts](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse.html) * [Roles](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html) * [Module defaults](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_module_defaults.html) * [Interactive input: prompts](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_prompts.html) * [Using variables](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html) * [Discovering variables: facts and magic variables](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_vars_facts.html) * [Play Argument Validation](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables_validation.html) * [Specification Format](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables_validation.html#specification-format) * [Sample Specification](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables_validation.html#sample-specification) * [Playbook Example: Continuous Delivery and Rolling Upgrades](https://docs.ansible.com/projects/ansible/latest/playbook_guide/guide_rolling_upgrade.html) * [Executing playbooks](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_execution.html) * [Validating tasks: check mode and diff mode](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_checkmode.html) * [Understanding privilege escalation: become](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_privilege_escalation.html) * [Tags](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_tags.html) * [Executing playbooks for troubleshooting](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_startnstep.html) * [Debugging tasks](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_debugger.html) * [Asynchronous actions and polling](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_async.html) * [Controlling playbook execution: strategies and more](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_strategies.html) * [Advanced playbook syntax](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_advanced_syntax.html) * [Unsafe or raw strings](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_advanced_syntax.html#unsafe-or-raw-strings) * [YAML anchors and aliases: sharing variable values](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_advanced_syntax.html#yaml-anchors-and-aliases-sharing-variable-values) * [Manipulating data](https://docs.ansible.com/projects/ansible/latest/playbook_guide/complex_data_manipulation.html) * [Loops and list comprehensions](https://docs.ansible.com/projects/ansible/latest/playbook_guide/complex_data_manipulation.html#loops-and-list-comprehensions) * [Complex Type transformations](https://docs.ansible.com/projects/ansible/latest/playbook_guide/complex_data_manipulation.html#complex-type-transformations) --- # Developer Guide — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * Developer Guide * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/dev_guide/index.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Developer Guide[](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/index.html#developer-guide "Link to this heading") ===================================================================================================================================== Note **Making Open Source More Inclusive** 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) . Welcome to the Ansible Developer Guide! **Who should use this guide?** 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. Find the task that best describes what you want to do: * I’m looking for a way to address a use case: > * I want to [add a custom plugin or module locally](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_locally.html#developing-locally) > . > > * I want to figure out if [developing a module is the right approach](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules.html#module-dev-should-you) > for my use case. > > * I want to understand [what a successful collection creator path looks like](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_collections_path.html#developing-collections-path) > . > > * I want to [develop a collection](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_collections.html#developing-collections) > . > > * I want to [contribute to an Ansible-maintained collection](https://docs.ansible.com/projects/ansible/12/community/contributing_maintained_collections.html#contributing-maintained-collections "(in Ansible v12)") > . > > * I want to [contribute to a community-maintained collection](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_collections_contributing.html#hacking-collections) > . > > * I want to [migrate a role to a collection](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/migrating_roles.html#migrating-roles) > . > * I’ve read the info above, and I’m sure I want to develop a module: > * What do I need to know before I start coding? > > * I want to [set up my Python development environment](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_general.html#environment-setup) > . > > * I want to [get started writing a module](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_general.html#developing-modules-general) > . > > * I want to write a specific kind of module: > > * a [network module](https://docs.ansible.com/projects/ansible/2.9/network/dev_guide/developing_plugins_network.html#developing-modules-network "(in Ansible v2.9)") > > * a [Windows module](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_general_windows.html#developing-modules-general-windows) > . > > > * I want to [write a series of related modules](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_in_groups.html#developing-modules-in-groups) > that integrate Ansible with a new product (for example, a database, cloud provider, network platform, and so on). > * I want to refine my code: > * I want to [debug my module code](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/debugging.html#debugging-modules) > . > > * I want to [add tests](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/testing.html#developing-testing) > . > > * I want to [document my module](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_documenting.html#module-documenting) > . > > * I want to [improve documentation by using Ansible markup](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/ansible_markup.html#ansible-markup) > . > > * I want to [document my set of modules for a network platform](https://docs.ansible.com/projects/ansible/2.9/network/dev_guide/documenting_modules_network.html#documenting-modules-network "(in Ansible v2.9)") > . > > * I want to follow [conventions and tips for clean, usable module code](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_best_practices.html#developing-modules-best-practices) > . > > * I want to [make sure my code runs on Python 2 and Python 3](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_python_3.html#developing-python-3) > . > * I want to work on other development projects: > * I want to [write a plugin](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_plugins.html#developing-plugins) > . > > * I want to [connect Ansible to a new source of inventory](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_inventory.html#developing-inventory) > . > > * I want to [deprecate an outdated module](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/module_lifecycle.html#deprecating-modules) > . > * I want to contribute back to the Ansible project: * I want to [understand how to contribute to Ansible](https://docs.ansible.com/projects/ansible-core/devel/community/index.html#ansible-community-guide) . * I want to [contribute my module or plugin](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_checklist.html#developing-modules-checklist) . * I want to [understand the DCO agreement](https://docs.ansible.com/projects/ansible-core/devel/community/developer_certificate_of_origin.html#developer-certificate-of-origin) for contributions to the [Ansible Core](https://github.com/ansible/ansible) and [Ansible Documentation](https://github.com/ansible/ansible-documentation) repositories. If you prefer to read the entire guide, here’s a list of the pages in order. * [Adding modules and plugins locally](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_locally.html) * [Modules and plugins: what is the difference?](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_locally.html#modules-and-plugins-what-is-the-difference) * [Adding modules and plugins in collections](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_locally.html#adding-modules-and-plugins-in-collections) * [Adding a module or plugin outside of a collection](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_locally.html#adding-a-module-or-plugin-outside-of-a-collection) * [Adding a non-module plugin locally outside of a collection](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_locally.html#adding-a-non-module-plugin-locally-outside-of-a-collection) * [Using `ansible.legacy` to access custom versions of an `ansible.builtin` module](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_locally.html#using-ansible-legacy-to-access-custom-versions-of-an-ansible-builtin-module) * [Should you develop a module?](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules.html) * [Developing modules](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_general.html) * [Preparing an environment for developing Ansible modules](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_general.html#preparing-an-environment-for-developing-ansible-modules) * [Creating a standalone module](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_general.html#creating-a-standalone-module) * [Creating a module in a collection](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_general.html#creating-a-module-in-a-collection) * [Creating an info or a facts module](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_general.html#creating-an-info-or-a-facts-module) * [Verifying your module code](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_general.html#verifying-your-module-code) * [Testing your newly-created module](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_general.html#testing-your-newly-created-module) * [Contributing back to Ansible](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_general.html#contributing-back-to-ansible) * [Communication and development support](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_general.html#communication-and-development-support) * [Credit](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_general.html#credit) * [Contributing your module to an existing Ansible collection](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_checklist.html) * [Contributing modules: objective requirements](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_checklist.html#contributing-modules-objective-requirements) * [Contributing to Ansible: subjective requirements](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_checklist.html#contributing-to-ansible-subjective-requirements) * [Other checklists](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_checklist.html#other-checklists) * [Conventions, tips, and pitfalls](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_best_practices.html) * [Scoping your module(s)](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_best_practices.html#scoping-your-module-s) * [Designing module interfaces](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_best_practices.html#designing-module-interfaces) * [General guidelines & tips](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_best_practices.html#general-guidelines-tips) * [Functions and Methods](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_best_practices.html#functions-and-methods) * [Python tips](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_best_practices.html#python-tips) * [Importing and using shared code](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_best_practices.html#importing-and-using-shared-code) * [Handling module failures](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_best_practices.html#handling-module-failures) * [Handling exceptions (bugs) gracefully](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_best_practices.html#handling-exceptions-bugs-gracefully) * [Creating correct and informative module output](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_best_practices.html#creating-correct-and-informative-module-output) * [Following Ansible conventions](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_best_practices.html#following-ansible-conventions) * [Module Security](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_best_practices.html#module-security) * [Ansible and Python 3](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_python_3.html) * [Minimum version of Python 3.x and Python 2.x](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_python_3.html#minimum-version-of-python-3-x-and-python-2-x) * [Developing Ansible code that supports Python 2 and Python 3](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_python_3.html#developing-ansible-code-that-supports-python-2-and-python-3) * [Debugging modules](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/debugging.html) * [Detailed debugging steps](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/debugging.html#detailed-debugging-steps) * [Simple debugging](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/debugging.html#simple-debugging) * [Module format and documentation](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_documenting.html) * [Non-Python modules documentation](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_documenting.html#non-python-modules-documentation) * [Python shebang & UTF-8 coding](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_documenting.html#python-shebang-utf-8-coding) * [Copyright and license](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_documenting.html#copyright-and-license) * [DOCUMENTATION block](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_documenting.html#documentation-block) * [EXAMPLES block](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_documenting.html#examples-block) * [RETURN block](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_documenting.html#return-block) * [Python imports](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_documenting.html#python-imports) * [Testing module documentation](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_documenting.html#testing-module-documentation) * [Ansible markup](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/ansible_markup.html) * [Semantic markup within module documentation](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/ansible_markup.html#semantic-markup-within-module-documentation) * [Linking within module documentation](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/ansible_markup.html#linking-within-module-documentation) * [Format macros within module documentation](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/ansible_markup.html#format-macros-within-module-documentation) * [Adjacent YAML documentation files](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/sidecar.html) * [YAML documentation for plugins](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/sidecar.html#yaml-documentation-for-plugins) * [YAML format](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/sidecar.html#yaml-format) * [Supported plugin types](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/sidecar.html#supported-plugin-types) * [Windows module development walkthrough](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_general_windows.html) * [Windows environment setup](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_general_windows.html#windows-environment-setup) * [Create a Windows server in a VM](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_general_windows.html#create-a-windows-server-in-a-vm) * [Create an Ansible inventory](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_general_windows.html#create-an-ansible-inventory) * [Provisioning the environment](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_general_windows.html#provisioning-the-environment) * [Windows new module development](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_general_windows.html#windows-new-module-development) * [Windows module utilities](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_general_windows.html#windows-module-utilities) * [Windows playbook module testing](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_general_windows.html#windows-playbook-module-testing) * [Windows debugging](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_general_windows.html#windows-debugging) * [Windows unit testing](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_general_windows.html#windows-unit-testing) * [Windows integration testing](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_general_windows.html#windows-integration-testing) * [Windows communication and development support](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_general_windows.html#windows-communication-and-development-support) * [Creating a new collection](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_in_groups.html) * [Before you start coding](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_in_groups.html#before-you-start-coding) * [Naming conventions](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_in_groups.html#naming-conventions) * [Speak to us](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_in_groups.html#speak-to-us) * [Where to get support](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_in_groups.html#where-to-get-support) * [Required files](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_in_groups.html#required-files) * [New to Git or GitHub](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_modules_in_groups.html#new-to-git-or-github) * [Testing Ansible](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/testing.html) * [Why test your Ansible contributions?](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/testing.html#why-test-your-ansible-contributions) * [Types of tests](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/testing.html#types-of-tests) * [Testing within GitHub & Azure Pipelines](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/testing.html#testing-within-github-azure-pipelines) * [How to test a PR](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/testing.html#how-to-test-a-pr) * [Want to know more about testing?](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/testing.html#want-to-know-more-about-testing) * [The lifecycle of an Ansible module or plugin](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/module_lifecycle.html) * [Deprecating modules and plugins in the Ansible main repository](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/module_lifecycle.html#deprecating-modules-and-plugins-in-the-ansible-main-repository) * [Deprecating modules and plugins in a collection](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/module_lifecycle.html#deprecating-modules-and-plugins-in-a-collection) * [Changing a module or plugin name in the Ansible main repository](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/module_lifecycle.html#changing-a-module-or-plugin-name-in-the-ansible-main-repository) * [Renaming a module or plugin in a collection, or redirecting a module or plugin to another collection](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/module_lifecycle.html#renaming-a-module-or-plugin-in-a-collection-or-redirecting-a-module-or-plugin-to-another-collection) * [Tombstoning a module or plugin in a collection](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/module_lifecycle.html#tombstoning-a-module-or-plugin-in-a-collection) * [Developing plugins](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_plugins.html) * [Writing plugins in Python](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_plugins.html#writing-plugins-in-python) * [Raising errors](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_plugins.html#raising-errors) * [String encoding](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_plugins.html#string-encoding) * [Plugin configuration & documentation standards](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_plugins.html#plugin-configuration-documentation-standards) * [Developing particular plugin types](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_plugins.html#developing-particular-plugin-types) * [Developing dynamic inventory](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_inventory.html) * [Inventory sources](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_inventory.html#inventory-sources) * [Inventory plugins](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_inventory.html#inventory-plugins) * [Inventory scripts](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_inventory.html#developing-inventory-scripts) * [Developing `ansible-core`](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_core.html) * [`ansible-core` project branches and tags](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/core_branches_and_tags.html) * [Ansible module architecture](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_program_flow_modules.html) * [Ansible module architecture](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_program_flow_modules.html) * [Types of modules](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_program_flow_modules.html#types-of-modules) * [How modules are executed](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_program_flow_modules.html#how-modules-are-executed) * [Python API](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_api.html) * [Rebasing a pull request](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_rebasing.html) * [Configuring your remotes](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_rebasing.html#configuring-your-remotes) * [Rebasing your branch](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_rebasing.html#rebasing-your-branch) * [Updating your pull request](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_rebasing.html#updating-your-pull-request) * [Getting help rebasing](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_rebasing.html#getting-help-rebasing) * [Using and developing module utilities](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_module_utilities.html) * [Naming and finding module utilities](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_module_utilities.html#naming-and-finding-module-utilities) * [Standard module utilities](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_module_utilities.html#standard-module-utilities) * [Ansible collection creator path](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_collections_path.html) * [Examine currently available solutions](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_collections_path.html#examine-currently-available-solutions) * [Create your content](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_collections_path.html#create-your-content) * [Put your content in a collection](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_collections_path.html#put-your-content-in-a-collection) * [Write good user collection documentation](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_collections_path.html#write-good-user-collection-documentation) * [Publish your collection source code](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_collections_path.html#publish-your-collection-source-code) * [Follow a versioning convention](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_collections_path.html#follow-a-versioning-convention) * [Understand and implement testing and CI](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_collections_path.html#understand-and-implement-testing-and-ci) * [Provide good contributor & maintainer documentation](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_collections_path.html#provide-good-contributor-maintainer-documentation) * [Publish your collection on distribution servers](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_collections_path.html#publish-your-collection-on-distribution-servers) * [Make your collection a part of Ansible community package](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_collections_path.html#make-your-collection-a-part-of-ansible-community-package) * [Maintain](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_collections_path.html#maintain) * [Communicate](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_collections_path.html#communicate) * [Developing collections](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_collections.html) * [Creating collections](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_collections_creating.html) * [Using shared resources in collections](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_collections_shared.html) * [Testing collections](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_collections_testing.html) * [Distributing collections](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_collections_distributing.html) * [Documenting collections](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_collections_documenting.html) * [Migrating Ansible content to a different collection](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_collections_migrating.html) * [Contributing to collections](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_collections_contributing.html) * [Generating changelogs and porting guide entries in a collection](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_collections_changelogs.html) * [Collection structure](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/developing_collections_structure.html) * [Collection Galaxy metadata structure](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/collections_galaxy_meta.html) * [Migrating Roles to Roles in Collections on Galaxy](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/migrating_roles.html) * [Comparing standalone roles to collection roles](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/migrating_roles.html#comparing-standalone-roles-to-collection-roles) * [Migrating a role to a collection](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/migrating_roles.html#migrating-a-role-to-a-collection) * [Migrating a role that contains plugins to a collection](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/migrating_roles.html#migrating-a-role-that-contains-plugins-to-a-collection) * [Using `ansible.legacy` to access local custom modules from collections-based roles](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/migrating_roles.html#using-ansible-legacy-to-access-local-custom-modules-from-collections-based-roles) * [Collection Galaxy metadata structure](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/collections_galaxy_meta.html) * [Structure](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/collections_galaxy_meta.html#structure) * [Examples](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/collections_galaxy_meta.html#examples) * [Ansible architecture](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/overview_architecture.html) * [Modules](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/overview_architecture.html#modules) * [Module utilities](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/overview_architecture.html#module-utilities) * [Plugins](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/overview_architecture.html#plugins) * [Inventory](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/overview_architecture.html#inventory) * [Playbooks](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/overview_architecture.html#playbooks) * [The Ansible search path](https://docs.ansible.com/projects/ansible-core/devel/dev_guide/overview_architecture.html#the-ansible-search-path) --- # Indexes of all modules and plugins — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * Indexes of all modules and plugins * * * * Indexes of all modules and plugins[](https://docs.ansible.com/projects/ansible/latest/collections/all_plugins.html#indexes-of-all-modules-and-plugins "Link to this heading") =============================================================================================================================================================================== Plugin indexes * [Index of all Become Plugins](https://docs.ansible.com/projects/ansible/latest/collections/index_become.html) * [Index of all Cache Plugins](https://docs.ansible.com/projects/ansible/latest/collections/index_cache.html) * [Index of all Callback Plugins](https://docs.ansible.com/projects/ansible/latest/collections/index_callback.html) * [Index of all Cliconf Plugins](https://docs.ansible.com/projects/ansible/latest/collections/index_cliconf.html) * [Index of all Connection Plugins](https://docs.ansible.com/projects/ansible/latest/collections/index_connection.html) * [Index of all Filter Plugins](https://docs.ansible.com/projects/ansible/latest/collections/index_filter.html) * [Index of all Httpapi Plugins](https://docs.ansible.com/projects/ansible/latest/collections/index_httpapi.html) * [Index of all Inventory Plugins](https://docs.ansible.com/projects/ansible/latest/collections/index_inventory.html) * [Index of all Lookup Plugins](https://docs.ansible.com/projects/ansible/latest/collections/index_lookup.html) * [Index of all Modules](https://docs.ansible.com/projects/ansible/latest/collections/index_module.html) * [Index of all Netconf Plugins](https://docs.ansible.com/projects/ansible/latest/collections/index_netconf.html) * [Index of all Roles](https://docs.ansible.com/projects/ansible/latest/collections/index_role.html) * [Index of all Shell Plugins](https://docs.ansible.com/projects/ansible/latest/collections/index_shell.html) * [Index of all Strategy Plugins](https://docs.ansible.com/projects/ansible/latest/collections/index_strategy.html) * [Index of all Test Plugins](https://docs.ansible.com/projects/ansible/latest/collections/index_test.html) * [Index of all Vars Plugins](https://docs.ansible.com/projects/ansible/latest/collections/index_vars.html) * [Index of all deprecated collections and plugins](https://docs.ansible.com/projects/ansible/latest/collections/deprecations.html) --- # Using Ansible modules and plugins — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * Using Ansible modules and plugins * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/module_plugin_guide/index.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Using Ansible modules and plugins[](https://docs.ansible.com/projects/ansible/latest/module_plugin_guide/index.html#using-ansible-modules-and-plugins "Link to this heading") =============================================================================================================================================================================== Note **Making Open Source More Inclusive** 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) . Welcome to the Ansible guide for working with modules, plugins, and collections. Ansible modules are units of code that can control system resources or execute system commands. Ansible provides a module library that you can execute directly on remote hosts or through playbooks. You can also write custom modules. Similar to modules are plugins, which are pieces of code that extend core Ansible functionality. Ansible uses a plugin architecture to enable a rich, flexible, and expandable feature set. Ansible ships with several plugins and lets you easily use your own plugins. * [Introduction to modules](https://docs.ansible.com/projects/ansible/latest/module_plugin_guide/modules_intro.html) * [Boolean variables](https://docs.ansible.com/projects/ansible/latest/module_plugin_guide/modules_intro.html#boolean-variables) * [Module maintenance and support](https://docs.ansible.com/projects/ansible/latest/module_plugin_guide/modules_support.html) * [Maintenance](https://docs.ansible.com/projects/ansible/latest/module_plugin_guide/modules_support.html#maintenance) * [Issue Reporting](https://docs.ansible.com/projects/ansible/latest/module_plugin_guide/modules_support.html#issue-reporting) * [Support](https://docs.ansible.com/projects/ansible/latest/module_plugin_guide/modules_support.html#support) * [Rejecting modules](https://docs.ansible.com/projects/ansible/latest/module_plugin_guide/plugin_filtering_config.html) * [Working with plugins](https://docs.ansible.com/projects/ansible/latest/plugins/plugins.html) * [Action plugins](https://docs.ansible.com/projects/ansible/latest/plugins/action.html) * [Become plugins](https://docs.ansible.com/projects/ansible/latest/plugins/become.html) * [Cache plugins](https://docs.ansible.com/projects/ansible/latest/plugins/cache.html) * [Callback plugins](https://docs.ansible.com/projects/ansible/latest/plugins/callback.html) * [Cliconf plugins](https://docs.ansible.com/projects/ansible/latest/plugins/cliconf.html) * [Connection plugins](https://docs.ansible.com/projects/ansible/latest/plugins/connection.html) * [Docs fragments](https://docs.ansible.com/projects/ansible/latest/plugins/docs_fragment.html) * [Filter plugins](https://docs.ansible.com/projects/ansible/latest/plugins/filter.html) * [Httpapi plugins](https://docs.ansible.com/projects/ansible/latest/plugins/httpapi.html) * [Inventory plugins](https://docs.ansible.com/projects/ansible/latest/plugins/inventory.html) * [Lookup plugins](https://docs.ansible.com/projects/ansible/latest/plugins/lookup.html) * [Modules](https://docs.ansible.com/projects/ansible/latest/plugins/module.html) * [Module utilities](https://docs.ansible.com/projects/ansible/latest/plugins/module_util.html) * [Netconf plugins](https://docs.ansible.com/projects/ansible/latest/plugins/netconf.html) * [Shell plugins](https://docs.ansible.com/projects/ansible/latest/plugins/shell.html) * [Strategy plugins](https://docs.ansible.com/projects/ansible/latest/plugins/strategy.html) * [Terminal plugins](https://docs.ansible.com/projects/ansible/latest/plugins/terminal.html) * [Test plugins](https://docs.ansible.com/projects/ansible/latest/plugins/test.html) * [Vars plugins](https://docs.ansible.com/projects/ansible/latest/plugins/vars.html) * [Modules and plugins index](https://docs.ansible.com/projects/ansible/latest/module_plugin_guide/modules_plugins_index.html) --- # Using Ansible modules and plugins — Ansible Core Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible-core/devel/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Core Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible-core/devel/index.html) * Using Ansible modules and plugins * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/module_plugin_guide/index.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Using Ansible modules and plugins[](https://docs.ansible.com/projects/ansible-core/devel/module_plugin_guide/index.html#using-ansible-modules-and-plugins "Link to this heading") =================================================================================================================================================================================== Note **Making Open Source More Inclusive** 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) . Welcome to the Ansible guide for working with modules, plugins, and collections. Ansible modules are units of code that can control system resources or execute system commands. Ansible provides a module library that you can execute directly on remote hosts or through playbooks. You can also write custom modules. Similar to modules are plugins, which are pieces of code that extend core Ansible functionality. Ansible uses a plugin architecture to enable a rich, flexible, and expandable feature set. Ansible ships with several plugins and lets you easily use your own plugins. * [Introduction to modules](https://docs.ansible.com/projects/ansible-core/devel/module_plugin_guide/modules_intro.html) * [Boolean variables](https://docs.ansible.com/projects/ansible-core/devel/module_plugin_guide/modules_intro.html#boolean-variables) * [Module maintenance and support](https://docs.ansible.com/projects/ansible-core/devel/module_plugin_guide/modules_support.html) * [Maintenance](https://docs.ansible.com/projects/ansible-core/devel/module_plugin_guide/modules_support.html#maintenance) * [Issue Reporting](https://docs.ansible.com/projects/ansible-core/devel/module_plugin_guide/modules_support.html#issue-reporting) * [Support](https://docs.ansible.com/projects/ansible-core/devel/module_plugin_guide/modules_support.html#support) * [Rejecting modules](https://docs.ansible.com/projects/ansible-core/devel/module_plugin_guide/plugin_filtering_config.html) * [Working with plugins](https://docs.ansible.com/projects/ansible-core/devel/plugins/plugins.html) * [Action plugins](https://docs.ansible.com/projects/ansible-core/devel/plugins/action.html) * [Become plugins](https://docs.ansible.com/projects/ansible-core/devel/plugins/become.html) * [Cache plugins](https://docs.ansible.com/projects/ansible-core/devel/plugins/cache.html) * [Callback plugins](https://docs.ansible.com/projects/ansible-core/devel/plugins/callback.html) * [Cliconf plugins](https://docs.ansible.com/projects/ansible-core/devel/plugins/cliconf.html) * [Connection plugins](https://docs.ansible.com/projects/ansible-core/devel/plugins/connection.html) * [Docs fragments](https://docs.ansible.com/projects/ansible-core/devel/plugins/docs_fragment.html) * [Filter plugins](https://docs.ansible.com/projects/ansible-core/devel/plugins/filter.html) * [Httpapi plugins](https://docs.ansible.com/projects/ansible-core/devel/plugins/httpapi.html) * [Inventory plugins](https://docs.ansible.com/projects/ansible-core/devel/plugins/inventory.html) * [Lookup plugins](https://docs.ansible.com/projects/ansible-core/devel/plugins/lookup.html) * [Modules](https://docs.ansible.com/projects/ansible-core/devel/plugins/module.html) * [Module utilities](https://docs.ansible.com/projects/ansible-core/devel/plugins/module_util.html) * [Netconf plugins](https://docs.ansible.com/projects/ansible-core/devel/plugins/netconf.html) * [Shell plugins](https://docs.ansible.com/projects/ansible-core/devel/plugins/shell.html) * [Strategy plugins](https://docs.ansible.com/projects/ansible-core/devel/plugins/strategy.html) * [Terminal plugins](https://docs.ansible.com/projects/ansible-core/devel/plugins/terminal.html) * [Test plugins](https://docs.ansible.com/projects/ansible-core/devel/plugins/test.html) * [Vars plugins](https://docs.ansible.com/projects/ansible-core/devel/plugins/vars.html) * [Modules and plugins index](https://docs.ansible.com/projects/ansible-core/devel/module_plugin_guide/modules_plugins_index.html) --- # How to Develop a Custom Plugin — Ansible Rulebook Documentation * [AnsibleFest](https://www.ansible.com/ansiblefest) * [Products](https://www.ansible.com/tower) * [Community](https://www.ansible.com/community) * [Webinars & Training](https://www.ansible.com/webinars-training) * [Blog](https://www.ansible.com/blog) [![Ansible Logo](https://docs.ansible.com/projects/rulebook/en/v1.2.0/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Rulebook Documentation](https://ansible-rulebook.readthedocs.io/en/latest/) * [](https://docs.ansible.com/projects/rulebook/en/v1.2.0/index.html) * How to Develop a Custom Plugin * [View page source](https://docs.ansible.com/projects/rulebook/en/v1.2.0/_sources/sources.rst.txt) * * * Event source plugins are responsible for generating events that trigger rule evaluation in ansible-rulebook. They can either receive events or interface with external systems, such as message queues, to produce event data for the rule engine. **To help users get started the \`ansible.eda\` collection provides a set of event source plugins** that cover common integration scenarios with Ansible Event Driven. You can explore the available source plugins here: [https://galaxy.ansible.com/ui/repo/published/ansible/eda/content/](https://galaxy.ansible.com/ui/repo/published/ansible/eda/content/) How to Develop a Custom Plugin[](https://docs.ansible.com/projects/rulebook/en/v1.2.0/sources.html#how-to-develop-a-custom-plugin "Link to this heading") =========================================================================================================================================================== You can build your own event source plugin in python. A plugin is a single python file but before we get to that lets take a look at some best practices and patterns: Best Practices and Patterns[](https://docs.ansible.com/projects/rulebook/en/v1.2.0/sources.html#best-practices-and-patterns "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------- There are 3 basic patterns that you’ll be developing against when considering a new source plugin: 1. Event Bus Plugins These are plugins that listen to a stream of events from a source where the connection is established by the plugin itself. Examples of this are the `kafka` and `aws_sqs_queue` plugins. This is the most ideal and reliable pattern to follow. Durability and Reliability of the data is the responsibility of the event source and availability of the data can follow the patterns of the event source and its own internal configuration. 2. Scraper Plugins These plugins connect to a source and scrape the data from the source usually after a given amount of time has passed. Examples of this are the `url_check` and `watchdog` plugins. These plugins can be reliable but may require extract logic for handling duplication. It’s also possible to miss data if the scraper is not running at the time the data is available. 3. Callback Plugins These plugins provide a callback endpoint that the event source can call when data is available. Examples of this are the `webhook` and `alertmanager` plugins. These plugins are the least reliable as they are dependent on the event source to call the callback endpoint and are highly sensitive to data loss. If the event source is not available or the callback endpoint is not available then there may not be another opportunity to receive the data. These can also require other ingress policies and firewall rules to be available and configured properly to operate. It’s strongly recommended to adopt one of the first two patterns and only consider callback plugins in the absence of any other solution. Note Ansible Automation Platform provides integrated webhooks called **Event Streams**. It is recommended to use Event Streams for webhook integrations instead of custom callback plugins. For more information, see the documentation: [https://docs.redhat.com/en/documentation/red\_hat\_ansible\_automation\_platform/2.5/html/using\_automation\_decisions/simplified-event-routing](https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.5/html/using_automation_decisions/simplified-event-routing) When deciding whether to build a dedicated plugin you may consider configuring the data source to send data to a system where a more general plugin exists already. For example, if you have a system that can send data to a kafka topic then you can use the `kafka` plugin to receive the data. There are many connectors for tying systems to other message buses and this is a great way to leverage existing plugins. Plugin template[](https://docs.ansible.com/projects/rulebook/en/v1.2.0/sources.html#plugin-template "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------- Lets take a look at a very basic example that you could use in the form of a template for producing other plugins: """ template.py An ansible-rulebook event source plugin template. Arguments: - delay: seconds to wait between events Examples: sources: - template: delay: 1 """ import asyncio from typing import Any, Dict async def main(queue: asyncio.Queue, args: Dict\[str, Any\]): delay \= args.get("delay", 0) while True: await queue.put(dict(template\=dict(msg\="hello world"))) await asyncio.sleep(delay) if \_\_name\_\_ \== "\_\_main\_\_": class MockQueue: async def put(self, event): print(event) mock\_arguments \= dict() asyncio.run(main(MockQueue(), mock\_arguments)) Plugin entrypoint[](https://docs.ansible.com/projects/rulebook/en/v1.2.0/sources.html#plugin-entrypoint "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------- The plugin python file must contain an entrypoint function exactly like the following: async def main(queue: asyncio.Queue, args: Dict\[str, Any\]): It is an async function. The first argument is an asyncio queue that will be consumed by ansible-rulebook CLI. The rest arguments are custom defined. They must match the arguments in the source section of the rulebook. For example the template plugin expects a single argument `delay`. In the rulebook the source section looks like: \- name: example hosts: all sources: \- template: delay: 5 Each source must contain a key which is the name of the plugin. Its nested keys must match argument names expected by the main function. The name of the plugin is the python filename. If the plugin is from a collection then the plugin name is a FQCN which is the collection name concatenating with the python filename with a period delimit, for example `ansible.eda.range`. In the main function you can implement code that connects to an external source of events, retrieves events and puts them onto the provided asyncio queue. The event data put on the queue must be a dictionary. You can insert the `meta` key that points to another dictionary that holds a list of hosts. These hosts will limit where the ansible playbook can run. A simple example looks like `{"i": 2, "meta": {hosts: "localhost"}}`. `hosts` can be a comma delimited string or a list of host names. As the plugin have full access to an unbounded queue that is consumed by ansible-rulebbok we carefully recommend to use always the method `asyncio.Queue.put` to put events as it’s a non-blocking call. To give free cpu cycles to the event loop to process the events, we recommend to use `asyncio.sleep(0)` immediately after the `put` method. Note ansible-rulebook is intended to be a long running process and react to events over the time. If the `main` function of **any of the sources** exits then the ansible-rulebook process will be terminated. Usually you may want to implement a loop that keeps running and waits for events endlessly. Note The rulebook can contain it’s own logic to finish the process through the `shutdown` action. If your plugin needs to perform some cleanup before the process is terminated, you must catch the `asyncio.CancelledError` exception. Note Please, pay attention when handling errors in your plugin and ensure to raise an exception with a meaningful message so that ansible-rulebook can log it correctly. Ansible-rulebook will not log the exception itself or print stack traces; it will only log the message you provide. Distributing plugins[](https://docs.ansible.com/projects/rulebook/en/v1.2.0/sources.html#distributing-plugins "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------- For local tests the plugin source file can be saved under a folder specified by the `-S` argument in the ansible-rulebook CLI. The recommended method for distributing and installing the plugin is through a collection. In this case the plugin source file should be placed under `extensions/eda/plugins/event_source` folder and referred to by FQCN. The following rulebook example illustrates how to refer to the range plugin provided by `ansible.eda` collection: \- name: example2 hosts: localhost sources: \- name: range ansible.eda.range: limit: 5 Any dependent packages needed by the custom plugin should be installed in the ansible-rulebook CLI env regardless the plugin is local or from a collection. Document plugins[](https://docs.ansible.com/projects/rulebook/en/v1.2.0/sources.html#document-plugins "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------- It is strongly recommended that you add comments at the top of the source file. Please describe the purpose of the event source plugin. List all required or optional arguments. Also add an example how to configure the plugin in a rulebook. --- # Developer Guide — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * Developer Guide * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/dev_guide/index.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Developer Guide[](https://docs.ansible.com/projects/ansible/latest/dev_guide/index.html#developer-guide "Link to this heading") ================================================================================================================================= Note **Making Open Source More Inclusive** 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) . Welcome to the Ansible Developer Guide! **Who should use this guide?** 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. Find the task that best describes what you want to do: * I’m looking for a way to address a use case: > * I want to [add a custom plugin or module locally](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_locally.html#developing-locally) > . > > * I want to figure out if [developing a module is the right approach](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules.html#module-dev-should-you) > for my use case. > > * I want to understand [what a successful collection creator path looks like](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_collections_path.html#developing-collections-path) > . > > * I want to [develop a collection](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_collections.html#developing-collections) > . > > * I want to [contribute to an Ansible-maintained collection](https://docs.ansible.com/projects/ansible/latest/community/contributing_maintained_collections.html#contributing-maintained-collections) > . > > * I want to [contribute to a community-maintained collection](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_collections_contributing.html#hacking-collections) > . > > * I want to [migrate a role to a collection](https://docs.ansible.com/projects/ansible/latest/dev_guide/migrating_roles.html#migrating-roles) > . > * I’ve read the info above, and I’m sure I want to develop a module: > * What do I need to know before I start coding? > > * I want to [set up my Python development environment](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_general.html#environment-setup) > . > > * I want to [get started writing a module](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_general.html#developing-modules-general) > . > > * I want to write a specific kind of module: > > * a [network module](https://docs.ansible.com/projects/ansible/latest/network/dev_guide/developing_plugins_network.html#developing-modules-network) > > * a [Windows module](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_general_windows.html#developing-modules-general-windows) > . > > * an [Amazon module](https://docs.ansible.com/projects/ansible/latest/collections/amazon/aws/docsite/dev_guidelines.html#ansible-collections-amazon-aws-docsite-dev-guide-intro) > . > > * an [oVirt/RHV module](https://github.com/oVirt/ovirt-ansible-collection/blob/master/README-developers.md) > . > > * a [VMware module](https://docs.ansible.com/projects/ansible/latest/collections/community/vmware/docsite/dev_guide.html#ansible-collections-community-vmware-docsite-vmware-ansible-devguide) > . > > > * I want to [write a series of related modules](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_in_groups.html#developing-modules-in-groups) > that integrate Ansible with a new product (for example, a database, cloud provider, network platform, and so on). > * I want to refine my code: > * I want to [debug my module code](https://docs.ansible.com/projects/ansible/latest/dev_guide/debugging.html#debugging-modules) > . > > * I want to [add tests](https://docs.ansible.com/projects/ansible/latest/dev_guide/testing.html#developing-testing) > . > > * I want to [document my module](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_documenting.html#module-documenting) > . > > * I want to [improve documentation by using Ansible markup](https://docs.ansible.com/projects/ansible/latest/dev_guide/ansible_markup.html#ansible-markup) > . > > * I want to [document my set of modules for a network platform](https://docs.ansible.com/projects/ansible/latest/network/dev_guide/documenting_modules_network.html#documenting-modules-network) > . > > * I want to follow [conventions and tips for clean, usable module code](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_best_practices.html#developing-modules-best-practices) > . > > * I want to [make sure my code runs on Python 2 and Python 3](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_python_3.html#developing-python-3) > . > * I want to work on other development projects: > * I want to [write a plugin](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_plugins.html#developing-plugins) > . > > * I want to [connect Ansible to a new source of inventory](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_inventory.html#developing-inventory) > . > > * I want to [deprecate an outdated module](https://docs.ansible.com/projects/ansible/latest/dev_guide/module_lifecycle.html#deprecating-modules) > . > * I want to contribute back to the Ansible project: * I want to [understand how to contribute to Ansible](https://docs.ansible.com/projects/ansible/latest/community/index.html#ansible-community-guide) . * I want to [contribute my module or plugin](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_checklist.html#developing-modules-checklist) . * I want to [understand the DCO agreement](https://docs.ansible.com/projects/ansible/latest/community/developer_certificate_of_origin.html#developer-certificate-of-origin) for contributions to the [Ansible Core](https://github.com/ansible/ansible) and [Ansible Documentation](https://github.com/ansible/ansible-documentation) repositories. If you prefer to read the entire guide, here’s a list of the pages in order. * [Adding modules and plugins locally](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_locally.html) * [Modules and plugins: what is the difference?](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_locally.html#modules-and-plugins-what-is-the-difference) * [Adding modules and plugins in collections](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_locally.html#adding-modules-and-plugins-in-collections) * [Adding a module or plugin outside of a collection](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_locally.html#adding-a-module-or-plugin-outside-of-a-collection) * [Adding a non-module plugin locally outside of a collection](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_locally.html#adding-a-non-module-plugin-locally-outside-of-a-collection) * [Using `ansible.legacy` to access custom versions of an `ansible.builtin` module](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_locally.html#using-ansible-legacy-to-access-custom-versions-of-an-ansible-builtin-module) * [Should you develop a module?](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules.html) * [Developing modules](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_general.html) * [Preparing an environment for developing Ansible modules](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_general.html#preparing-an-environment-for-developing-ansible-modules) * [Creating a standalone module](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_general.html#creating-a-standalone-module) * [Creating a module in a collection](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_general.html#creating-a-module-in-a-collection) * [Creating an info or a facts module](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_general.html#creating-an-info-or-a-facts-module) * [Verifying your module code](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_general.html#verifying-your-module-code) * [Testing your newly-created module](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_general.html#testing-your-newly-created-module) * [Contributing back to Ansible](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_general.html#contributing-back-to-ansible) * [Communication and development support](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_general.html#communication-and-development-support) * [Credit](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_general.html#credit) * [Contributing your module to an existing Ansible collection](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_checklist.html) * [Contributing modules: objective requirements](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_checklist.html#contributing-modules-objective-requirements) * [Contributing to Ansible: subjective requirements](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_checklist.html#contributing-to-ansible-subjective-requirements) * [Other checklists](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_checklist.html#other-checklists) * [Conventions, tips, and pitfalls](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_best_practices.html) * [Scoping your module(s)](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_best_practices.html#scoping-your-module-s) * [Designing module interfaces](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_best_practices.html#designing-module-interfaces) * [General guidelines & tips](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_best_practices.html#general-guidelines-tips) * [Functions and Methods](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_best_practices.html#functions-and-methods) * [Python tips](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_best_practices.html#python-tips) * [Importing and using shared code](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_best_practices.html#importing-and-using-shared-code) * [Handling module failures](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_best_practices.html#handling-module-failures) * [Handling exceptions (bugs) gracefully](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_best_practices.html#handling-exceptions-bugs-gracefully) * [Creating correct and informative module output](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_best_practices.html#creating-correct-and-informative-module-output) * [Following Ansible conventions](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_best_practices.html#following-ansible-conventions) * [Module Security](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_best_practices.html#module-security) * [Ansible and Python 3](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_python_3.html) * [Minimum version of Python 3.x and Python 2.x](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_python_3.html#minimum-version-of-python-3-x-and-python-2-x) * [Developing Ansible code that supports Python 2 and Python 3](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_python_3.html#developing-ansible-code-that-supports-python-2-and-python-3) * [Debugging modules](https://docs.ansible.com/projects/ansible/latest/dev_guide/debugging.html) * [Detailed debugging steps](https://docs.ansible.com/projects/ansible/latest/dev_guide/debugging.html#detailed-debugging-steps) * [Simple debugging](https://docs.ansible.com/projects/ansible/latest/dev_guide/debugging.html#simple-debugging) * [Module format and documentation](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_documenting.html) * [Non-Python modules documentation](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_documenting.html#non-python-modules-documentation) * [Python shebang & UTF-8 coding](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_documenting.html#python-shebang-utf-8-coding) * [Copyright and license](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_documenting.html#copyright-and-license) * [DOCUMENTATION block](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_documenting.html#documentation-block) * [EXAMPLES block](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_documenting.html#examples-block) * [RETURN block](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_documenting.html#return-block) * [Python imports](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_documenting.html#python-imports) * [Testing module documentation](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_documenting.html#testing-module-documentation) * [Ansible markup](https://docs.ansible.com/projects/ansible/latest/dev_guide/ansible_markup.html) * [Semantic markup within module documentation](https://docs.ansible.com/projects/ansible/latest/dev_guide/ansible_markup.html#semantic-markup-within-module-documentation) * [Linking within module documentation](https://docs.ansible.com/projects/ansible/latest/dev_guide/ansible_markup.html#linking-within-module-documentation) * [Format macros within module documentation](https://docs.ansible.com/projects/ansible/latest/dev_guide/ansible_markup.html#format-macros-within-module-documentation) * [Adjacent YAML documentation files](https://docs.ansible.com/projects/ansible/latest/dev_guide/sidecar.html) * [YAML documentation for plugins](https://docs.ansible.com/projects/ansible/latest/dev_guide/sidecar.html#yaml-documentation-for-plugins) * [YAML format](https://docs.ansible.com/projects/ansible/latest/dev_guide/sidecar.html#yaml-format) * [Supported plugin types](https://docs.ansible.com/projects/ansible/latest/dev_guide/sidecar.html#supported-plugin-types) * [Windows module development walkthrough](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_general_windows.html) * [Windows environment setup](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_general_windows.html#windows-environment-setup) * [Create a Windows server in a VM](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_general_windows.html#create-a-windows-server-in-a-vm) * [Create an Ansible inventory](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_general_windows.html#create-an-ansible-inventory) * [Provisioning the environment](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_general_windows.html#provisioning-the-environment) * [Windows new module development](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_general_windows.html#windows-new-module-development) * [Windows module utilities](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_general_windows.html#windows-module-utilities) * [Windows playbook module testing](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_general_windows.html#windows-playbook-module-testing) * [Windows debugging](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_general_windows.html#windows-debugging) * [Windows unit testing](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_general_windows.html#windows-unit-testing) * [Windows integration testing](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_general_windows.html#windows-integration-testing) * [Windows communication and development support](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_general_windows.html#windows-communication-and-development-support) * [Creating a new collection](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_in_groups.html) * [Before you start coding](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_in_groups.html#before-you-start-coding) * [Naming conventions](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_in_groups.html#naming-conventions) * [Speak to us](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_in_groups.html#speak-to-us) * [Where to get support](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_in_groups.html#where-to-get-support) * [Required files](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_in_groups.html#required-files) * [New to Git or GitHub](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_in_groups.html#new-to-git-or-github) * [Testing Ansible](https://docs.ansible.com/projects/ansible/latest/dev_guide/testing.html) * [Why test your Ansible contributions?](https://docs.ansible.com/projects/ansible/latest/dev_guide/testing.html#why-test-your-ansible-contributions) * [Types of tests](https://docs.ansible.com/projects/ansible/latest/dev_guide/testing.html#types-of-tests) * [Testing within GitHub & Azure Pipelines](https://docs.ansible.com/projects/ansible/latest/dev_guide/testing.html#testing-within-github-azure-pipelines) * [How to test a PR](https://docs.ansible.com/projects/ansible/latest/dev_guide/testing.html#how-to-test-a-pr) * [Want to know more about testing?](https://docs.ansible.com/projects/ansible/latest/dev_guide/testing.html#want-to-know-more-about-testing) * [The lifecycle of an Ansible module or plugin](https://docs.ansible.com/projects/ansible/latest/dev_guide/module_lifecycle.html) * [Deprecating modules and plugins in the Ansible main repository](https://docs.ansible.com/projects/ansible/latest/dev_guide/module_lifecycle.html#deprecating-modules-and-plugins-in-the-ansible-main-repository) * [Deprecating modules and plugins in a collection](https://docs.ansible.com/projects/ansible/latest/dev_guide/module_lifecycle.html#deprecating-modules-and-plugins-in-a-collection) * [Changing a module or plugin name in the Ansible main repository](https://docs.ansible.com/projects/ansible/latest/dev_guide/module_lifecycle.html#changing-a-module-or-plugin-name-in-the-ansible-main-repository) * [Renaming a module or plugin in a collection, or redirecting a module or plugin to another collection](https://docs.ansible.com/projects/ansible/latest/dev_guide/module_lifecycle.html#renaming-a-module-or-plugin-in-a-collection-or-redirecting-a-module-or-plugin-to-another-collection) * [Tombstoning a module or plugin in a collection](https://docs.ansible.com/projects/ansible/latest/dev_guide/module_lifecycle.html#tombstoning-a-module-or-plugin-in-a-collection) * [Developing plugins](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_plugins.html) * [Writing plugins in Python](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_plugins.html#writing-plugins-in-python) * [Raising errors](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_plugins.html#raising-errors) * [String encoding](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_plugins.html#string-encoding) * [Plugin configuration & documentation standards](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_plugins.html#plugin-configuration-documentation-standards) * [Developing particular plugin types](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_plugins.html#developing-particular-plugin-types) * [Developing dynamic inventory](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_inventory.html) * [Inventory sources](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_inventory.html#inventory-sources) * [Inventory plugins](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_inventory.html#inventory-plugins) * [Inventory scripts](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_inventory.html#developing-inventory-scripts) * [Developing `ansible-core`](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_core.html) * [`ansible-core` project branches and tags](https://docs.ansible.com/projects/ansible/latest/dev_guide/core_branches_and_tags.html) * [Ansible module architecture](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_program_flow_modules.html) * [Ansible module architecture](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_program_flow_modules.html) * [Types of modules](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_program_flow_modules.html#types-of-modules) * [How modules are executed](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_program_flow_modules.html#how-modules-are-executed) * [Python API](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_api.html) * [Rebasing a pull request](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_rebasing.html) * [Configuring your remotes](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_rebasing.html#configuring-your-remotes) * [Rebasing your branch](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_rebasing.html#rebasing-your-branch) * [Updating your pull request](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_rebasing.html#updating-your-pull-request) * [Getting help rebasing](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_rebasing.html#getting-help-rebasing) * [Using and developing module utilities](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_module_utilities.html) * [Naming and finding module utilities](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_module_utilities.html#naming-and-finding-module-utilities) * [Standard module utilities](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_module_utilities.html#standard-module-utilities) * [Ansible collection creator path](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_collections_path.html) * [Examine currently available solutions](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_collections_path.html#examine-currently-available-solutions) * [Create your content](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_collections_path.html#create-your-content) * [Put your content in a collection](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_collections_path.html#put-your-content-in-a-collection) * [Write good user collection documentation](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_collections_path.html#write-good-user-collection-documentation) * [Publish your collection source code](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_collections_path.html#publish-your-collection-source-code) * [Follow a versioning convention](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_collections_path.html#follow-a-versioning-convention) * [Understand and implement testing and CI](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_collections_path.html#understand-and-implement-testing-and-ci) * [Provide good contributor & maintainer documentation](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_collections_path.html#provide-good-contributor-maintainer-documentation) * [Publish your collection on distribution servers](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_collections_path.html#publish-your-collection-on-distribution-servers) * [Make your collection a part of Ansible community package](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_collections_path.html#make-your-collection-a-part-of-ansible-community-package) * [Maintain](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_collections_path.html#maintain) * [Communicate](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_collections_path.html#communicate) * [Developing collections](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_collections.html) * [Creating collections](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_collections_creating.html) * [Using shared resources in collections](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_collections_shared.html) * [Testing collections](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_collections_testing.html) * [Distributing collections](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_collections_distributing.html) * [Documenting collections](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_collections_documenting.html) * [Migrating Ansible content to a different collection](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_collections_migrating.html) * [Contributing to collections](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_collections_contributing.html) * [Generating changelogs and porting guide entries in a collection](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_collections_changelogs.html) * [Collection structure](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_collections_structure.html) * [Collection Galaxy metadata structure](https://docs.ansible.com/projects/ansible/latest/dev_guide/collections_galaxy_meta.html) * [Migrating Roles to Roles in Collections on Galaxy](https://docs.ansible.com/projects/ansible/latest/dev_guide/migrating_roles.html) * [Comparing standalone roles to collection roles](https://docs.ansible.com/projects/ansible/latest/dev_guide/migrating_roles.html#comparing-standalone-roles-to-collection-roles) * [Migrating a role to a collection](https://docs.ansible.com/projects/ansible/latest/dev_guide/migrating_roles.html#migrating-a-role-to-a-collection) * [Migrating a role that contains plugins to a collection](https://docs.ansible.com/projects/ansible/latest/dev_guide/migrating_roles.html#migrating-a-role-that-contains-plugins-to-a-collection) * [Using `ansible.legacy` to access local custom modules from collections-based roles](https://docs.ansible.com/projects/ansible/latest/dev_guide/migrating_roles.html#using-ansible-legacy-to-access-local-custom-modules-from-collections-based-roles) * [Collection Galaxy metadata structure](https://docs.ansible.com/projects/ansible/latest/dev_guide/collections_galaxy_meta.html) * [Structure](https://docs.ansible.com/projects/ansible/latest/dev_guide/collections_galaxy_meta.html#structure) * [Examples](https://docs.ansible.com/projects/ansible/latest/dev_guide/collections_galaxy_meta.html#examples) * [Ansible architecture](https://docs.ansible.com/projects/ansible/latest/dev_guide/overview_architecture.html) * [Modules](https://docs.ansible.com/projects/ansible/latest/dev_guide/overview_architecture.html#modules) * [Module utilities](https://docs.ansible.com/projects/ansible/latest/dev_guide/overview_architecture.html#module-utilities) * [Plugins](https://docs.ansible.com/projects/ansible/latest/dev_guide/overview_architecture.html#plugins) * [Inventory](https://docs.ansible.com/projects/ansible/latest/dev_guide/overview_architecture.html#inventory) * [Playbooks](https://docs.ansible.com/projects/ansible/latest/dev_guide/overview_architecture.html#playbooks) * [The Ansible search path](https://docs.ansible.com/projects/ansible/latest/dev_guide/overview_architecture.html#the-ansible-search-path) --- # Ansible Porting Guides — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * Ansible Porting Guides * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/porting_guides/porting_guides.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Ansible Porting Guides[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guides.html#ansible-porting-guides "Link to this heading") ============================================================================================================================================================= This section lists porting guides that can help you in updating playbooks, plugins and other parts of your Ansible infrastructure from one version of Ansible to the next. * [Ansible 13 Porting Guide](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html) * [Ansible 12 Porting Guide](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_12.html) * [Ansible 11 Porting Guide](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_11.html) * [Ansible 10 Porting Guide](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html) * [Ansible 9 Porting Guide](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_9.html) * [Ansible 8 Porting Guide](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_8.html) * [Ansible 7 Porting Guide](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_7.html) * [Ansible 6 Porting Guide](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html) * [Ansible 5 Porting Guide](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_5.html) * [Ansible 4 Porting Guide](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html) * [Ansible 3 Porting Guide](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html) * [Ansible 2.10 Porting Guide](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_2.10.html) * [Ansible 2.9 Porting Guide](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_2.9.html) * [Ansible 2.8 Porting Guide](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_2.8.html) * [Ansible 2.7 Porting Guide](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_2.7.html) * [Ansible 2.6 Porting Guide](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_2.6.html) * [Ansible 2.5 Porting Guide](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_2.5.html) * [Ansible 2.4 Porting Guide](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_2.4.html) * [Ansible 2.3 Porting Guide](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_2.3.html) * [Ansible 2.0 Porting Guide](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_2.0.html) --- # Conditionals — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * [Using Ansible playbooks](https://docs.ansible.com/projects/ansible/latest/playbook_guide/index.html) * [Working with playbooks](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks.html) * Conditionals * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/playbook_guide/playbooks_conditionals.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Conditionals[](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_conditionals.html#conditionals "Link to this heading") ================================================================================================================================================= In a playbook, you may want to execute different tasks or have different goals, depending on the value of a fact (data about the remote system), a variable, or the result of a previous task. You may want the value of some variables to depend on the value of other variables. Or you may want to create additional groups of hosts based on whether the hosts match other criteria. You can do all of these things with conditionals. Ansible uses Jinja2 [tests](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_tests.html#playbooks-tests) and [filters](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_filters.html#playbooks-filters) in conditionals. Ansible supports all the standard tests and filters and adds some unique ones as well. Note There are many options to control execution flow in Ansible. You can find more examples of supported conditionals at [https://jinja.palletsprojects.com/en/latest/templates/#comparisons](https://jinja.palletsprojects.com/en/latest/templates/#comparisons) . [Basic conditionals with `when`](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_conditionals.html#id3) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_conditionals.html#basic-conditionals-with-when "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The simplest conditional statement applies to a single task. Create the task, then add a `when` statement that applies a test. The `when` clause is a raw Jinja2 expression without double curly braces (see [Referencing simple variables](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#jinja2-simple) ). When you run the task or playbook, Ansible evaluates the test for all hosts. On any host where the test passes (returns a value of True), Ansible runs that task. For example, if you are installing mysql on multiple machines, some of which have SELinux enabled, you might have a task to configure SELinux to allow mysql to run. You would only want that task to run on machines that have SELinux enabled: tasks: \- name: Configure SELinux to start mysql on any port ansible.posix.seboolean: name: mysql\_connect\_any state: true persistent: true when: ansible\_selinux.status == "enabled" \# all variables can be used directly in conditionals without double curly braces ### [Conditionals based on ansible\_facts](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_conditionals.html#id4) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_conditionals.html#conditionals-based-on-ansible-facts "Link to this heading") Often you want to execute or skip a task based on facts. Facts are attributes of individual hosts, including IP address, operating system, the status of a filesystem, and many more. With conditionals based on facts: > * You can install a certain package only when the operating system is a particular version. > > * You can skip configuring a firewall on hosts with internal IP addresses. > > * You can perform cleanup tasks only when a filesystem is getting full. > See [Commonly-used facts](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_conditionals.html#commonly-used-facts) for a list of facts that frequently appear in conditional statements. Not all facts exist for all hosts. For example, the ‘lsb\_major\_release’ fact used in the example below only exists when the `lsb_release package` is installed on the target host. To see what facts are available on your systems, add a debug task to your playbook: \- name: Show facts available on the system ansible.builtin.debug: var: ansible\_facts Here is a sample conditional based on a fact: tasks: \- name: Shut down Debian flavored systems ansible.builtin.command: /sbin/shutdown -t now when: ansible\_facts\['os\_family'\] == "Debian" If you have multiple conditions, you can group them with parentheses: tasks: \- name: Shut down CentOS 6 and Debian 7 systems ansible.builtin.command: /sbin/shutdown -t now when: (ansible\_facts\['distribution'\] == "CentOS" and ansible\_facts\['distribution\_major\_version'\] == "6") or (ansible\_facts\['distribution'\] == "Debian" and ansible\_facts\['distribution\_major\_version'\] == "7") You can use [logical operators](https://jinja.palletsprojects.com/en/latest/templates/#logic) to combine conditions. When you have multiple conditions that all need to be true (that is, a logical `and`), you can specify them as a list: tasks: \- name: Shut down CentOS 6 systems ansible.builtin.command: /sbin/shutdown -t now when: \- ansible\_facts\['distribution'\] == "CentOS" \- ansible\_facts\['distribution\_major\_version'\] == "6" If a fact or variable is a string, and you need to run a mathematical comparison on it, use a filter to ensure that Ansible reads the value as an integer: tasks: \- ansible.builtin.shell: echo "only on Red Hat 6, derivatives, and later" when: ansible\_facts\['os\_family'\] == "RedHat" and ansible\_facts\['lsb'\]\['major\_release'\] | int >= 6 You can store Ansible facts as variables to use for conditional logic, as in the following example: tasks: \- name: Get the CPU temperature set\_fact: temperature: "{{ ansible\_facts\['cpu\_temperature'\] }}" \- name: Restart the system if the temperature is too high when: temperature | float > 90 shell: "reboot" ### [Conditions based on registered variables](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_conditionals.html#id5) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_conditionals.html#conditions-based-on-registered-variables "Link to this heading") Often in a playbook, you want to execute or skip a task based on the outcome of an earlier task. For example, you might want to configure a service after it is upgraded by an earlier task. To create a conditional based on a registered variable: > 1. Register the outcome of the earlier task as a variable. > > 2. Create a conditional test based on the registered variable. > You create the name of the registered variable using the `register` keyword. A registered variable always contains the status of the task that created it as well as any output that the task generated. You can use registered variables in templates and action lines as well as in conditional `when` statements. You can access the string contents of the registered variable using `variable.stdout`. For example: \- name: Test play hosts: all tasks: \- name: Register a variable ansible.builtin.shell: cat /etc/motd register: motd\_contents \- name: Use the variable in conditional statement ansible.builtin.shell: echo "motd contains the word hi" when: motd\_contents.stdout.find('hi') != -1 You can use registered results in the loop of a task if the variable is a list. If the variable is not a list, you can convert it into a list, with either `stdout_lines` or with `variable.stdout.split()`. You can also split the lines by other fields: \- name: Registered variable usage as a loop list hosts: all tasks: \- name: Retrieve the list of home directories ansible.builtin.command: ls /home register: home\_dirs \- name: Add home dirs to the backup spooler ansible.builtin.file: path: /mnt/bkspool/{{ item }} src: /home/{{ item }} state: link loop: "{{ home\_dirs.stdout\_lines }}" \# same as loop: "{{ home\_dirs.stdout.split() }}" The string content of a registered variable can be empty. If you want to run another task only on hosts where the stdout of your registered variable is empty, check the registered variable’s string contents for emptiness: \- name: check registered variable for emptiness hosts: all tasks: \- name: List contents of directory ansible.builtin.command: ls mydir register: contents \- name: Check contents for emptiness ansible.builtin.debug: msg: "Directory is empty" when: contents.stdout == "" Ansible always registers something in a registered variable for every host, even on hosts where a task fails or Ansible skips a task because a condition is not met. To run a follow-up task on these hosts, query the registered variable for `is skipped` (not for “undefined” or “default”). See [Registering variables](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#registered-variables) for more information. Here are sample conditionals based on the success or failure of a task. Remember to ignore errors if you want Ansible to continue executing on a host when a failure occurs: tasks: \- name: Register a variable, ignore errors and continue ansible.builtin.command: /bin/false register: result ignore\_errors: true \- name: Run only if the task that registered the "result" variable fails ansible.builtin.command: /bin/something when: result is failed \- name: Run only if the task that registered the "result" variable succeeds ansible.builtin.command: /bin/something\_else when: result is succeeded \- name: Run only if the task that registered the "result" variable is skipped ansible.builtin.command: /bin/still/something\_else when: result is skipped \- name: Run only if the task that registered the "result" variable changed something. ansible.builtin.command: /bin/still/something\_else when: result is changed Note Older versions of Ansible used `success` and `fail`, but `succeeded` and `failed` use the correct tense. All of these options are now valid. ### [Conditionals based on variables](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_conditionals.html#id6) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_conditionals.html#conditionals-based-on-variables "Link to this heading") You can also create conditionals based on variables defined in the playbooks or inventory. Because conditionals require boolean input (a test must evaluate as True to trigger the condition), you must apply the `| bool` filter to non-boolean variables, such as string variables with content like ‘yes’, ‘on’, ‘1’, or ‘true’. You can define variables like this: vars: epic: true monumental: "yes" With the variables above, Ansible would run one of these tasks and skip the other: tasks: \- name: Run the command if "epic" or "monumental" is true ansible.builtin.shell: echo "This certainly is epic!" when: epic or monumental | bool \- name: Run the command if "epic" is false ansible.builtin.shell: echo "This certainly isn't epic!" when: not epic If a required variable has not been set, you can skip or fail using Jinja2’s defined test. For example: tasks: \- name: Run the command if "foo" is defined ansible.builtin.shell: echo "I've got '{{ foo }}' and am not afraid to use it!" when: foo is defined \- name: Fail if "bar" is undefined ansible.builtin.fail: msg="Bailing out. This play requires 'bar'" when: bar is undefined This is especially useful in combination with the conditional import of `vars` files (see below). As the examples show, you do not need to use {{ }} to use variables inside conditionals, as these are already implied. ### [Using conditionals in loops](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_conditionals.html#id7) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_conditionals.html#using-conditionals-in-loops "Link to this heading") If you combine a `when` statement with a [loop](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_loops.html#playbooks-loops) , Ansible processes the condition separately for each item. This is by design, so you can execute the task on some items in the loop and skip it on other items. For example: tasks: \- name: Run with items greater than 5 ansible.builtin.command: echo {{ item }} loop: \[ 0, 2, 4, 6, 8, 10 \] when: item > 5 If you need to skip the whole task when the loop variable is undefined, use the |default filter to provide an empty iterator. For example, when looping over a list: \- name: Skip the whole task when a loop variable is undefined ansible.builtin.command: echo {{ item }} loop: "{{ mylist|default(\[\]) }}" when: item > 5 You can do the same thing when looping over a dict: \- name: The same as above using a dict ansible.builtin.command: echo {{ item.key }} loop: "{{ query('dict', mydict|default({})) }}" when: item.value > 5 ### [Loading custom facts](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_conditionals.html#id8) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_conditionals.html#loading-custom-facts "Link to this heading") You can provide your own facts, as described in [Should you develop a module?](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules.html#developing-modules) . To run them, just make a call to your own custom fact gathering module at the top of your list of tasks, and the variables returned there will be accessible for future tasks: tasks: \- name: Gather site specific fact data action: site\_facts \- name: Use a custom fact ansible.builtin.command: /usr/bin/thingy when: my\_custom\_fact\_just\_retrieved\_from\_the\_remote\_system == '1234' ### [Conditionals with reuse](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_conditionals.html#id9) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_conditionals.html#conditionals-with-reuse "Link to this heading") You can use conditionals with reusable tasks files, playbooks, or roles. Ansible executes these conditional statements differently for dynamic reuse (includes) and static reuse (imports). See [Reusing Ansible artifacts](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse.html#playbooks-reuse) for more information on reuse in Ansible. #### [Conditionals with imports](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_conditionals.html#id10) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_conditionals.html#conditionals-with-imports "Link to this heading") When you add a conditional to an import statement, Ansible applies the condition to all tasks within the imported file. This behavior is the equivalent of [Tag inheritance: adding tags to multiple tasks](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_tags.html#tag-inheritance) . Ansible applies the condition to every task and evaluates each task separately. For example, if you want to define and then display a variable that was not previously defined, you might have a playbook called `main.yml` and a tasks file called `other_tasks.yml`: \# all tasks within an imported file inherit the condition from the import statement \# main.yml \- hosts: all tasks: \- import\_tasks: other\_tasks.yml \# note "import" when: x is not defined \# other\_tasks.yml \- name: Set a variable ansible.builtin.set\_fact: x: foo \- name: Print a variable ansible.builtin.debug: var: x Ansible expands this at execution time to the equivalent of: \- name: Set a variable if not defined ansible.builtin.set\_fact: x: foo when: x is not defined \# this task sets a value for x \- name: Do the task if "x" is not defined ansible.builtin.debug: var: x when: x is not defined \# Ansible skips this task, because x is now defined If `x` is initially defined, both tasks are skipped as intended. But if `x` is initially undefined, the debug task will be skipped since the conditional is evaluated for every imported task. The conditional will evaluate to `true` for the `set_fact` task, which will define the variable and cause the `debug` conditional to evaluate to `false`. If this is not the behavior you want, use an `include_*` statement to apply a condition only to that statement itself. \# using a conditional on include\_\* only applies to the include task itself \# main.yml \- hosts: all tasks: \- include\_tasks: other\_tasks.yml \# note "include" when: x is not defined Now if `x` is initially undefined, the debug task will not be skipped because the conditional is evaluated at the time of the include and does not apply to the individual tasks. You can apply conditions to `import_playbook` as well as to the other `import_*` statements. When you use this approach, Ansible returns a ‘skipped’ message for every task on every host that does not match the criteria, creating repetitive output. In many cases the [group\_by module](https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/group_by_module.html#group-by-module) can be a more streamlined way to accomplish the same objective; see [Handling OS and distro differences](https://docs.ansible.com/projects/ansible/latest/tips_tricks/ansible_tips_tricks.html#os-variance) . #### [Conditionals with includes](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_conditionals.html#id11) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_conditionals.html#conditionals-with-includes "Link to this heading") When you use a conditional on an `include_*` statement, the condition is applied only to the include task itself and not to any other tasks within the included file(s). To contrast with the example used for conditionals on imports above, look at the same playbook and tasks file, but using an include instead of an import: \# Includes let you reuse a file to define a variable when it is not already defined \# main.yml \- include\_tasks: other\_tasks.yml when: x is not defined \# other\_tasks.yml \- name: Set a variable ansible.builtin.set\_fact: x: foo \- name: Print a variable ansible.builtin.debug: var: x Ansible expands this at execution time to the equivalent of: \# main.yml \- include\_tasks: other\_tasks.yml when: x is not defined \# if condition is met, Ansible includes other\_tasks.yml \# other\_tasks.yml \- name: Set a variable ansible.builtin.set\_fact: x: foo \# no condition applied to this task, Ansible sets the value of x to foo \- name: Print a variable ansible.builtin.debug: var: x \# no condition applied to this task, Ansible prints the debug statement By using `include_tasks` instead of `import_tasks`, both tasks from `other_tasks.yml` will be executed as expected. For more information on the differences between `include` v `import` see [Reusing Ansible artifacts](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse.html#playbooks-reuse) . #### [Conditionals with roles](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_conditionals.html#id12) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_conditionals.html#conditionals-with-roles "Link to this heading") There are three ways to apply conditions to roles: > * Add the same condition or conditions to all tasks in the role by placing your `when` statement under the `roles` keyword. See the example in this section. > > * Add the same condition or conditions to all tasks in the role by placing your `when` statement on a static `import_role` in your playbook. > > * Add a condition or conditions to individual tasks or blocks within the role itself. This is the only approach that allows you to select or skip some tasks within the role based on your `when` statement. To select or skip tasks within the role, you must have conditions set on individual tasks or blocks, use the dynamic `include_role` in your playbook, and add the condition or conditions to the include. When you use this approach, Ansible applies the condition to the include itself plus any tasks in the role that also have that `when` statement. > When you incorporate a role in your playbook statically with the `roles` keyword, Ansible adds the conditions you define to all the tasks in the role. For example: \- hosts: webservers roles: \- role: debian\_stock\_config when: ansible\_facts\['os\_family'\] == 'Debian' ### [Selecting variables, files, or templates based on facts](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_conditionals.html#id13) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_conditionals.html#selecting-variables-files-or-templates-based-on-facts "Link to this heading") Sometimes the facts about a host determine the values you want to use for certain variables or even the file or template you want to select for that host. For example, the names of packages are different on CentOS and Debian. The configuration files for common services are also different on different OS flavors and versions. To load different variables files, templates, or other files based on a fact about the hosts: > 1. name your vars files, templates, or files to match the Ansible fact that differentiates them > > 2. select the correct vars file, template, or file for each host with a variable based on that Ansible fact > Ansible separates variables from tasks, keeping your playbooks from turning into arbitrary code with nested conditionals. This approach results in more streamlined and auditable configuration rules because there are fewer decision points to track. #### [Selecting variables files based on facts](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_conditionals.html#id14) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_conditionals.html#selecting-variables-files-based-on-facts "Link to this heading") You can create a playbook that works on multiple platforms and OS versions with a minimum of syntax by placing your variable values in vars files and conditionally importing them. If you want to install Apache on some CentOS and some Debian servers, create variables files with YAML keys and values. For example: \--- \# for vars/RedHat.yml apache: httpd somethingelse: 42 Then import those variables files based on the facts you gather on the hosts in your playbook: \--- \- hosts: webservers remote\_user: root vars\_files: \- "vars/common.yml" \- \[ "vars/{{ ansible\_facts\['os\_family'\] }}.yml", "vars/os\_defaults.yml" \] tasks: \- name: Make sure apache is started ansible.builtin.service: name: '{{ apache }}' state: started Ansible gathers facts on the hosts in the webservers group, then interpolates the variable “ansible\_facts\[‘os\_family’\]” into a list of file names. If you have hosts with Red Hat operating systems (CentOS, for example), Ansible looks for ‘vars/RedHat.yml’. If that file does not exist, Ansible attempts to load ‘vars/os\_defaults.yml’. For Debian hosts, Ansible first looks for ‘vars/Debian.yml’, before falling back on ‘vars/os\_defaults.yml’. If no files in the list are found, Ansible raises an error. #### [Selecting files and templates based on facts](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_conditionals.html#id15) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_conditionals.html#selecting-files-and-templates-based-on-facts "Link to this heading") You can use the same approach when different OS flavors or versions require different configuration files or templates. Select the appropriate file or template based on the variables assigned to each host. This approach is often much cleaner than putting a lot of conditionals into a single template to cover multiple OS or package versions. For example, you can template out a configuration file that is very different between, say, CentOS and Debian: \- name: Template a file ansible.builtin.template: src: "{{ item }}" dest: /etc/myapp/foo.conf loop: "{{ query('first\_found', { 'files': myfiles, 'paths': mypaths}) }}" vars: myfiles: \- "{{ ansible\_facts\['distribution'\] }}.conf" \- default.conf mypaths: \['search\_location\_one/somedir/', '/opt/other\_location/somedir/'\] [Debugging conditionals](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_conditionals.html#id16) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_conditionals.html#debugging-conditionals "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- If your conditional `when` statement is not behaving as you intended, you can add a `debug` statement to determine if the condition evaluates to `true` or `false`. A common cause of unexpected behavior in conditionals is testing an integer as a string or a string as an integer. To debug a conditional statement, add the entire statement as the `var:` value in a `debug` task. Ansible then shows the test and how the statement evaluates. For example, here is a set of tasks and sample output: \- name: check value of return code ansible.builtin.debug: var: bar\_status.rc \- name: check test for rc value as string ansible.builtin.debug: var: bar\_status.rc == "127" \- name: check test for rc value as integer ansible.builtin.debug: var: bar\_status.rc == 127 TASK \[check value of return code\] \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\* ok: \[foo-1\] \=> { "bar\_status.rc": "127" } TASK \[check test for rc value as string\] \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\* ok: \[foo-1\] \=> { "bar\_status.rc == \\"127\\"": false } TASK \[check test for rc value as integer\] \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\* ok: \[foo-1\] \=> { "bar\_status.rc == 127": true } [Commonly-used facts](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_conditionals.html#id17) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_conditionals.html#commonly-used-facts "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The following Ansible facts are frequently used in conditionals. ### [ansible\_facts\[‘distribution’\]](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_conditionals.html#id18) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_conditionals.html#ansible-facts-distribution "Link to this heading") Possible values (sample, not complete list): Alpine Altlinux Amazon Archlinux ClearLinux Coreos CentOS Debian Fedora Gentoo Mandriva NA OpenWrt OracleLinux RedHat Slackware SLES SMGL SUSE Ubuntu VMwareESX ### [ansible\_facts\[‘distribution\_major\_version’\]](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_conditionals.html#id19) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_conditionals.html#ansible-facts-distribution-major-version "Link to this heading") The major version of the operating system. For example, the value is 16 for Ubuntu 16.04. ### [ansible\_facts\[‘os\_family’\]](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_conditionals.html#id20) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_conditionals.html#ansible-facts-os-family "Link to this heading") Possible values (sample, not complete list): AIX Alpine Altlinux Archlinux Darwin Debian FreeBSD Gentoo HP-UX Mandrake RedHat SMGL Slackware Solaris Suse Windows See also [Working with playbooks](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks.html#working-with-playbooks) An introduction to playbooks [Roles](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#playbooks-reuse-roles) Playbook organization by roles [General tips](https://docs.ansible.com/projects/ansible/latest/tips_tricks/ansible_tips_tricks.html#tips-and-tricks) Tips and tricks for playbooks [Using variables](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#playbooks-variables) All about variables [Communication](https://docs.ansible.com/projects/ansible/latest/community/communication.html#communication) Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide --- # Ansible 13 Porting Guide — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * [Ansible Porting Guides](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guides.html) * Ansible 13 Porting Guide * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/porting_guides/porting_guide_13.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * [Ansible 13 Porting Guide](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id51) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#ansible-13-porting-guide "Link to this heading") ================================================================================================================================================================================================================================================================== Ansible 13 is based on Ansible-core 2.20. We suggest you read this page along with the [Ansible 13 Changelog](https://github.com/ansible-community/ansible-build-data/blob/main/13/CHANGELOG-v13.md) to understand what updates you may need to make. [Introduction](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id52) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#introduction "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ No notable changes [Playbook](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id53) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#playbook "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Removed quote stripping in PowerShell operations[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#removed-quote-stripping-in-powershell-operations "Link to this heading") The PowerShell module utilities no longer attempt to remove quotes from paths when performing Windows operations like copying and fetching files. This should not affect normal playbooks unless a value is quoted too many times. If you have playbooks that rely on this automatic quote removal, you will need to adjust your path formatting. [Engine](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id54) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#engine "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ No notable changes [Plugin API](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id55) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#plugin-api "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Removed Features[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#removed-features "Link to this heading") The following previously deprecated features have been removed: * The `DEFAULT_TRANSPORT` configuration option no longer supports the `smart` value that selected the default transport as either `ssh` or `paramiko` based on the underlying platform configuration. * The `vault` and `unvault` filters no longer accept the deprecated `vaultid` parameter. * The `ansible-galaxy` command no longer supports the v2 Galaxy server API. Galaxy servers hosting collections must support v3. * The `dnf` and `dnf5` modules no longer support the deprecated `install_repoquery` option. * The `encrypt` module utility no longer includes the deprecated `passlib_or_crypt` API. * The `paramiko` connection plugin no longer supports the `PARAMIKO_HOST_KEY_AUTO_ADD` and `PARAMIKO_LOOK_FOR_KEYS` configuration keys, which were previously deprecated. * The `py3compat.environ` call has been removed. * Vars plugins that do not inherit from `BaseVarsPlugin` and define a `get_vars` method can no longer use the deprecated `get_host_vars` or `get_group_vars` fallback. * The `yum_repository` module no longer supports the deprecated `keepcache` option. ### Behavioral Changes[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#behavioral-changes "Link to this heading") * The `DataLoader.get_basedir` method now returns an absolute path instead of a relative path. Plugin code that relies on relative paths may need adjustment. * Argument spec validation now treats `None` values as empty strings for the `str` type for better consistency with pre-2.19 templating conversions. * When using `failed_when` to suppress an error, the `exception` key in the result is now renamed to `failed_when_suppressed_exception`. This prevents the error from being displayed by callbacks after being suppressed. If you have playbooks that check for the exception in the result, update them as follows: \# Before \- command: /bin/false register: result failed\_when: false \- debug: msg: "Exception was: {{ result.exception }}" when: result.exception is defined \# After \- command: /bin/false register: result failed\_when: false \- debug: msg: "Exception was: {{ result.failed\_when\_suppressed\_exception }}" when: result.failed\_when\_suppressed\_exception is defined [Command Line](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id56) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#command-line "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ * Python 3.11 is no longer a supported control node version. Python 3.12+ is now required for running Ansible. * Python 3.8 is no longer a supported remote version. Python 3.9+ is now required for target execution. [Deprecated](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id57) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#deprecated "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### INJECT\_FACTS\_AS\_VARS[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#inject-facts-as-vars "Link to this heading") The `INJECT_FACTS_AS_VARS` configuration currently defaults to `True`, but this is now deprecated and it will switch to `False` in Ansible 2.24. When enabled, facts are available both inside the `ansible_facts` dictionary and as individual variables in the main namespace. In the `ansible_facts` dictionary, the `ansible_` prefix is removed from fact names. You will receive deprecation warnings if you are accessing ‘injected’ facts. To prepare for the future default: **Update your playbooks to use the ansible\_facts dictionary:** \# Deprecated - will stop working in 2.24 \- debug: msg: "OS: {{ ansible\_os\_distribution }}" \# Recommended - works in all versions \- debug: msg: "OS: {{ ansible\_facts\['distribution'\] }}" \# Note: 'ansible\_' prefix is removed inside ansible\_facts **Or explicitly enable the current behavior in your configuration:** In your `ansible.cfg` file: \[defaults\] inject\_facts\_as\_vars \= True By exporting an environment variable: export ANSIBLE\_INJECT\_FACT\_VARS\=True ### Other Deprecations[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#other-deprecations "Link to this heading") * The `vars` internal variable cache will be removed in 2.24. This cache, once used internally, exposes variables in inconsistent states. The `vars` and `varnames` lookups should be used instead. * Specifying `ignore_files` as a string in the `include_vars` module is deprecated. Use a list instead: \# Deprecated \- include\_vars: dir: vars/ ignore\_files: ".gitkeep" \# Correct \- include\_vars: dir: vars/ ignore\_files: \[".gitkeep"\] [Modules](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id58) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#modules "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Modules removed[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#modules-removed "Link to this heading") The following modules no longer exist: * No notable changes ### Deprecation notices[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#deprecation-notices "Link to this heading") No notable changes ### Noteworthy module changes[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#noteworthy-module-changes "Link to this heading") * The `include_vars` module now raises an error if the `extensions` parameter is not specified as a list. Previously, non-list values were silently accepted. * The `include_vars` module now raises an error if the `ignore_files` parameter is not specified as a list. Previously, string values were accepted but are now deprecated. * The `replace` module now reads and writes files in text-mode as unicode characters instead of as bytes, and switches regex matching to unicode characters instead of bytes. This may affect playbooks that rely on byte-level operations. [Plugins](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id59) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#plugins "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Noteworthy plugin changes[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#noteworthy-plugin-changes "Link to this heading") No notable changes [Porting custom scripts](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id60) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#porting-custom-scripts "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- No notable changes [Networking](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id61) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#networking "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- No notable changes [Porting Guide for v13.5.0](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id62) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#porting-guide-for-v13-5-0 "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Added Collections[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#added-collections "Link to this heading") * graphiant.naas (version 26.2.4) ### Known Issues[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#known-issues "Link to this heading") #### community.routeros[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#community-routeros "Link to this heading") * api\_modify - to create or modify entries in the `container` path, you need librouteros 4.0.0 or newer due to a bug preventing older versions from setting or modifying properties named `cmd` ([https://github.com/ansible-collections/community.routeros/issues/442](https://github.com/ansible-collections/community.routeros/issues/442) ). ### Breaking Changes[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#breaking-changes "Link to this heading") #### community.mysql[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#community-mysql "Link to this heading") * Update imports from ansible.module\_utils.six to use their python3 equivalent. This change will make this collection incompatible for managed hosts on python2.7. #### community.proxmox[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#community-proxmox "Link to this heading") * proxmox - set `state` as not `optional` and assign default value `present` ([https://github.com/ansible-collections/community.proxmox/pull/292](https://github.com/ansible-collections/community.proxmox/pull/292) ). ### Major Changes[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#major-changes "Link to this heading") #### community.proxmox[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id8 "Link to this heading") * proxmox - Add ca\_path option to specify a ca-certificate for tls validation ([https://github.com/ansible-collections/community.proxmox/pull/256](https://github.com/ansible-collections/community.proxmox/pull/256) ). #### community.routeros[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id9 "Link to this heading") * api\_info, api\_modify - multiple parameters can no longer be disabled for the\`\`tool netwatch\`\` path ([https://github.com/ansible-collections/community.routeros/pull/433](https://github.com/ansible-collections/community.routeros/pull/433) ). * api\_info, api\_modify - parameter `name-format` can no longer be disabled for the `interface wifi provisioning` path ([https://github.com/ansible-collections/community.routeros/pull/433](https://github.com/ansible-collections/community.routeros/pull/433) ). * api\_info, api\_modify - parameter `script` can no longer be disabled for the `ip dhcp-client` path ([https://github.com/ansible-collections/community.routeros/pull/433](https://github.com/ansible-collections/community.routeros/pull/433) ). #### fortinet.fortios[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#fortinet-fortios "Link to this heading") * Supported new versions 7.6.5 and 7.6.6. * Updated the Q&A for using the default\_group feature in modules. #### netapp.ontap[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#netapp-ontap "Link to this heading") * na\_ontap\_autoupdate\_config - REST only support for managing configurations for automatic updates, requires ONTAP 9.10.1 or later. * na\_ontap\_cg - REST only support for managing consistency groups, requires ONTAP 9.10.1 or later. * na\_ontap\_cifs - AWS Lambda support added to the module. * na\_ontap\_cifs\_acl - AWS Lambda support added to the module. * na\_ontap\_cifs\_local\_group - AWS Lambda support added to the module. * na\_ontap\_cifs\_local\_group\_member - AWS Lambda support added to the module. * na\_ontap\_cifs\_local\_user - AWS Lambda support added to the module. * na\_ontap\_cifs\_local\_user\_set\_password - AWS Lambda support added to the module. * na\_ontap\_cifs\_privileges - AWS Lambda support added to the module. * na\_ontap\_cifs\_server - AWS Lambda support added to the module. * na\_ontap\_cifs\_unix\_symlink\_mapping - AWS Lambda support added to the module. * na\_ontap\_cluster\_peer - AWS Lambda support added to the module. * na\_ontap\_igroup - AWS Lambda support added to the module. * na\_ontap\_igroup\_initiator - AWS Lambda support added to the module. * na\_ontap\_lun\_copy - AWS Lambda support added to the module. * na\_ontap\_lun\_map - AWS Lambda support added to the module. * na\_ontap\_lun\_map\_reporting\_nodes - AWS Lambda support added to the module. * na\_ontap\_s3\_buckets - AWS Lambda support added to the module. * na\_ontap\_s3\_groups - AWS Lambda support added to the module. * na\_ontap\_s3\_policies - AWS Lambda support added to the module. * na\_ontap\_s3\_services - AWS Lambda support added to the module. * na\_ontap\_s3\_users - AWS Lambda support added to the module. * na\_ontap\_snapmirror - AWS Lambda support added to the module. * na\_ontap\_volume\_autosize - AWS Lambda support added to the module. * na\_ontap\_volume\_clone - AWS Lambda support added to the module. * na\_ontap\_vserver\_peer - AWS Lambda support added to the module. ### Deprecated Features[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#deprecated-features "Link to this heading") #### community.general[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#community-general "Link to this heading") * aix\_devices - module is superseded by equivalent in `ibm.power_aix` collection. It will be removed from community.general 15.0.0 ([https://github.com/ansible-collections/community.general/issues/11290](https://github.com/ansible-collections/community.general/issues/11290) , [https://github.com/ansible-collections/community.general/pull/11540](https://github.com/ansible-collections/community.general/pull/11540) ). * aix\_filesystem - module is superseded by equivalent in `ibm.power_aix` collection. It will be removed from community.general 15.0.0 ([https://github.com/ansible-collections/community.general/issues/11290](https://github.com/ansible-collections/community.general/issues/11290) , [https://github.com/ansible-collections/community.general/pull/11540](https://github.com/ansible-collections/community.general/pull/11540) ). * aix\_inittab - module is superseded by equivalent in `ibm.power_aix` collection. It will be removed from community.general 15.0.0 ([https://github.com/ansible-collections/community.general/issues/11290](https://github.com/ansible-collections/community.general/issues/11290) , [https://github.com/ansible-collections/community.general/pull/11540](https://github.com/ansible-collections/community.general/pull/11540) ). * aix\_lvg - module is superseded by equivalent in `ibm.power_aix` collection. It will be removed from community.general 15.0.0 ([https://github.com/ansible-collections/community.general/issues/11290](https://github.com/ansible-collections/community.general/issues/11290) , [https://github.com/ansible-collections/community.general/pull/11540](https://github.com/ansible-collections/community.general/pull/11540) ). * aix\_lvol - module is superseded by equivalent in `ibm.power_aix` collection. It will be removed from community.general 15.0.0 ([https://github.com/ansible-collections/community.general/issues/11290](https://github.com/ansible-collections/community.general/issues/11290) , [https://github.com/ansible-collections/community.general/pull/11540](https://github.com/ansible-collections/community.general/pull/11540) ). * monit - support for Monit version 5.18 or older is deprecated and will be removed in community.general 14.0.0 ([https://github.com/ansible-collections/community.general/pull/11254](https://github.com/ansible-collections/community.general/pull/11254) ). * puppet - the `timeout` parameter is deprecated and will be removed in community.general 14.0.0. ([https://github.com/ansible-collections/community.general/pull/11658](https://github.com/ansible-collections/community.general/pull/11658) ). #### community.proxmox[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id10 "Link to this heading") * proxmox - Certificate verification default changes from `false` to `true` with version 2.0.0 ([https://github.com/ansible-collections/community.proxmox/pull/256](https://github.com/ansible-collections/community.proxmox/pull/256) ). [Porting Guide for v13.4.0](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id63) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#porting-guide-for-v13-4-0 "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Major Changes[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id11 "Link to this heading") #### containers.podman[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#containers-podman "Link to this heading") * Add podman Quadlet modules ### Deprecated Features[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id12 "Link to this heading") * The awx.awx collection will be removed from Ansible 14. The collection is undergoing a heavy [refactoring](https://forum.ansible.com/t/7404) and currently does not align with the standards for the community package. See [the removal discussion for details](https://forum.ansible.com/t/44706) . After removal, users can still install this collection with `ansible-galaxy collection install awx.awx`. #### community.aws[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#community-aws "Link to this heading") * The alias `aws_acm_info` for the `acm_certificate_info` module has been deprecated. Please use `community.aws.acm_certificate_info` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `aws_acm` for the `acm_certificate` module has been deprecated. Please use `community.aws.acm_certificate` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `aws_api_gateway_domain` for the `api_gateway_domain` module has been deprecated. Please use `community.aws.api_gateway_domain` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `aws_api_gateway` for the `api_gateway` module has been deprecated. Please use `community.aws.api_gateway` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `aws_application_scaling_policy` for the `application_autoscaling_policy` module has been deprecated. Please use `community.aws.application_autoscaling_policy` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `aws_batch_compute_environment` for the `batch_compute_environment` module has been deprecated. Please use `community.aws.batch_compute_environment` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `aws_batch_job_definition` for the `batch_job_definition` module has been deprecated. Please use `community.aws.batch_job_definition` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `aws_batch_job_queue` for the `batch_job_queue` module has been deprecated. Please use `community.aws.batch_job_queue` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `aws_codebuild` for the `codebuild_project` module has been deprecated. Please use `community.aws.codebuild_project` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `aws_codecommit` for the `codecommit_repository` module has been deprecated. Please use `community.aws.codecommit_repository` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `aws_codepipeline` for the `codepipeline` module has been deprecated. Please use `community.aws.codepipeline` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `aws_config_aggregation_authorization` for the `config_aggregation_authorization` module has been deprecated. Please use `community.aws.config_aggregation_authorization` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `aws_config_aggregator` for the `config_aggregator` module has been deprecated. Please use `community.aws.config_aggregator` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `aws_config_delivery_channel` for the `config_delivery_channel` module has been deprecated. Please use `community.aws.config_delivery_channel` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `aws_config_recorder` for the `config_recorder` module has been deprecated. Please use `community.aws.config_recorder` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `aws_config_rule` for the `config_rule` module has been deprecated. Please use `community.aws.config_rule` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `aws_direct_connect_confirm_connection` for the `directconnect_confirm_connection` module has been deprecated. Please use `community.aws.directconnect_confirm_connection` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `aws_direct_connect_connection` for the `directconnect_connection` module has been deprecated. Please use `community.aws.directconnect_connection` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `aws_direct_connect_gateway` for the `directconnect_gateway` module has been deprecated. Please use `community.aws.directconnect_gateway` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `aws_direct_connect_link_aggregation_group` for the `directconnect_link_aggregation_group` module has been deprecated. Please use `community.aws.directconnect_link_aggregation_group` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `aws_direct_connect_virtual_interface` for the `directconnect_virtual_interface` module has been deprecated. Please use `community.aws.directconnect_virtual_interface` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `aws_eks_cluster` for the `eks_cluster` module has been deprecated. Please use `community.aws.eks_cluster` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `aws_elasticbeanstalk_app` for the `elasticbeanstalk_app` module has been deprecated. Please use `community.aws.elasticbeanstalk_app` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `aws_glue_connection` for the `glue_connection` module has been deprecated. Please use `community.aws.glue_connection` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `aws_glue_crawler` for the `glue_crawler` module has been deprecated. Please use `community.aws.glue_crawler` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `aws_glue_job` for the `glue_job` module has been deprecated. Please use `community.aws.glue_job` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `aws_inspector_target` for the `inspector_target` module has been deprecated. Please use `community.aws.inspector_target` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `aws_kms_info` for the `kms_key_info` module has been deprecated. Please use `amazon.aws.kms_key_info` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `aws_kms` for the `kms_key` module has been deprecated. Please use `amazon.aws.kms_key` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `aws_msk_cluster` for the `msk_cluster` module has been deprecated. Please use `community.aws.msk_cluster` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `aws_msk_config` for the `msk_config` module has been deprecated. Please use `community.aws.msk_config` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `aws_s3_bucket_info` for the `s3_bucket_info` module has been deprecated. Please use `amazon.aws.s3_bucket_info` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `aws_s3_cors` for the `s3_cors` module has been deprecated. Please use `community.aws.s3_cors` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `aws_secret` for the `secretsmanager_secret` module has been deprecated. Please use `community.aws.secretsmanager_secret` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `aws_ses_identity_policy` for the `ses_identity_policy` module has been deprecated. Please use `community.aws.ses_identity_policy` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `aws_ses_identity` for the `ses_identity` module has been deprecated. Please use `community.aws.ses_identity` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `aws_ses_rule_set` for the `ses_rule_set` module has been deprecated. Please use `community.aws.ses_rule_set` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `aws_sgw_info` for the `storagegateway_info` module has been deprecated. Please use `community.aws.storagegateway_info` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `aws_ssm_parameter_store` for the `ssm_parameter` module has been deprecated. Please use `community.aws.ssm_parameter` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `aws_step_functions_state_machine_execution` for the `stepfunctions_state_machine_execution` module has been deprecated. Please use `community.aws.stepfunctions_state_machine_execution` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `aws_step_functions_state_machine` for the `stepfunctions_state_machine` module has been deprecated. Please use `community.aws.stepfunctions_state_machine` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `aws_waf_condition` for the `waf_condition` module has been deprecated. Please use `community.aws.waf_condition` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `aws_waf_info` for the `waf_info` module has been deprecated. Please use `community.aws.waf_info` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `aws_waf_rule` for the `waf_rule` module has been deprecated. Please use `community.aws.waf_rule` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `aws_waf_web_acl` for the `waf_web_acl` module has been deprecated. Please use `community.aws.waf_web_acl` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `cloudfront_info` for the `cloudfront_distribution_info` module has been deprecated. Please use `community.aws.cloudfront_distribution_info` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `cloudtrail` for the `cloudtrail` module has been deprecated. Please use `amazon.aws.cloudtrail` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `ec2_asg_info` for the `autoscaling_group_info` module has been deprecated. Please use `amazon.aws.autoscaling_group_info` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `ec2_asg_instance_refresh_info` for the `autoscaling_instance_refresh_info` module has been deprecated. Please use `amazon.aws.autoscaling_instance_refresh_info` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `ec2_asg_instance_refresh` for the `autoscaling_instance_refresh` module has been deprecated. Please use `amazon.aws.autoscaling_instance_refresh` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `ec2_asg_lifecycle_hook` for the `autoscaling_lifecycle_hook` module has been deprecated. Please use `community.aws.autoscaling_lifecycle_hook` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `ec2_asg_scheduled_action` for the `autoscaling_scheduled_action` module has been deprecated. Please use `community.aws.autoscaling_scheduled_action` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `ec2_asg` for the `autoscaling_group` module has been deprecated. Please use `amazon.aws.autoscaling_group` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `ec2_lc_find` for the `autoscaling_launch_config_find` module has been deprecated. Please use `community.aws.autoscaling_launch_config_find` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `ec2_lc_info` for the `autoscaling_launch_config_info` module has been deprecated. Please use `community.aws.autoscaling_launch_config_info` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `ec2_lc` for the `autoscaling_launch_config` module has been deprecated. Please use `community.aws.autoscaling_launch_config` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `ec2_metric_alarm` for the `cloudwatch_metric_alarm` module has been deprecated. Please use `amazon.aws.cloudwatch_metric_alarm` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `ec2_scaling_policy` for the `autoscaling_policy` module has been deprecated. Please use `community.aws.autoscaling_policy` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * The alias `execute_lambda` for the `lambda_execute` module has been deprecated. Please use `amazon.aws.lambda_execute` instead ([https://github.com/ansible-collections/community.aws/pull/2387](https://github.com/ansible-collections/community.aws/pull/2387) ). * cloudfront\_distribution - The `items` return value in `active_trusted_signers` has been deprecated and will be removed in a release after 2026-12-15. Use `elements` instead ([https://github.com/ansible-collections/community.aws/pull/2354](https://github.com/ansible-collections/community.aws/pull/2354) ). * cloudfront\_distribution - The `items` return value in `aliases` has been deprecated and will be removed in a release after 2026-12-15. Use `elements` instead ([https://github.com/ansible-collections/community.aws/pull/2354](https://github.com/ansible-collections/community.aws/pull/2354) ). * cloudfront\_distribution - The `items` return value in `cache_behaviors.items.allowed_methods.cached_methods` has been deprecated and will be removed in a release after 2026-12-15. Use `elements` instead ([https://github.com/ansible-collections/community.aws/pull/2354](https://github.com/ansible-collections/community.aws/pull/2354) ). * cloudfront\_distribution - The `items` return value in `cache_behaviors.items.allowed_methods` has been deprecated and will be remove in a release after 2026-12-15. Use `elements` instead ([https://github.com/ansible-collections/community.aws/pull/2354](https://github.com/ansible-collections/community.aws/pull/2354) ). * cloudfront\_distribution - The `items` return value in `cache_behaviors.items.forwarded_values.cookies.whitelisted_names` has been deprecated and will be remove in a release after 2026-12-15. Use `elements` instead ([https://github.com/ansible-collections/community.aws/pull/2354](https://github.com/ansible-collections/community.aws/pull/2354) ). * cloudfront\_distribution - The `items` return value in `cache_behaviors.items.forwarded_values.headers` has been deprecated and will be remove in a release after 2026-12-15. Use `elements` instead ([https://github.com/ansible-collections/community.aws/pull/2354](https://github.com/ansible-collections/community.aws/pull/2354) ). * cloudfront\_distribution - The `items` return value in `cache_behaviors.items.forwarded_values.query_string_cache_keys` has been deprecated and will be remove in a release after 2026-12-15. Use `elements` instead ([https://github.com/ansible-collections/community.aws/pull/2354](https://github.com/ansible-collections/community.aws/pull/2354) ). * cloudfront\_distribution - The `items` return value in `cache_behaviors.items.lambda_function_associations` has been deprecated and will be remove in a release after 2026-12-15. Use `elements` instead ([https://github.com/ansible-collections/community.aws/pull/2354](https://github.com/ansible-collections/community.aws/pull/2354) ). * cloudfront\_distribution - The `items` return value in `cache_behaviors` has been deprecated and will be remove in a release after 2026-12-15. Use `elements` instead ([https://github.com/ansible-collections/community.aws/pull/2354](https://github.com/ansible-collections/community.aws/pull/2354) ). * cloudfront\_distribution - The `items` return value in `custom_error_responses` has been deprecated and will be remove in a release after 2026-12-15. Use `elements` instead ([https://github.com/ansible-collections/community.aws/pull/2354](https://github.com/ansible-collections/community.aws/pull/2354) ). * cloudfront\_distribution - The `items` return value in `default_cache_behavior.allowed_methods.cached_methods` has been deprecated and will be remove in a release after 2026-12-15. Use `elements` instead ([https://github.com/ansible-collections/community.aws/pull/2354](https://github.com/ansible-collections/community.aws/pull/2354) ). * cloudfront\_distribution - The `items` return value in `default_cache_behavior.allowed_methods` has been deprecated and will be remove in a release after 2026-12-15. Use `elements` instead ([https://github.com/ansible-collections/community.aws/pull/2354](https://github.com/ansible-collections/community.aws/pull/2354) ). * cloudfront\_distribution - The `items` return value in `default_cache_behavior.forwarded_values.cookies.whitelisted_names` has been deprecated and will be remove in a release after 2026-12-15. Use `elements` instead ([https://github.com/ansible-collections/community.aws/pull/2354](https://github.com/ansible-collections/community.aws/pull/2354) ). * cloudfront\_distribution - The `items` return value in `default_cache_behavior.forwarded_values.headers` has been deprecated and will be remove in a release after 2026-12-15. Use `elements` instead ([https://github.com/ansible-collections/community.aws/pull/2354](https://github.com/ansible-collections/community.aws/pull/2354) ). * cloudfront\_distribution - The `items` return value in `default_cache_behavior.forwarded_values.query_string_cache_keys` has been deprecated and will be remove in a release after 2026-12-15. Use `elements` instead ([https://github.com/ansible-collections/community.aws/pull/2354](https://github.com/ansible-collections/community.aws/pull/2354) ). * cloudfront\_distribution - The `items` return value in `default_cache_behavior.lambda_function_associations` has been deprecated and will be remove in a release after 2026-12-15. Use `elements` instead ([https://github.com/ansible-collections/community.aws/pull/2354](https://github.com/ansible-collections/community.aws/pull/2354) ). * cloudfront\_distribution - The `items` return value in `origins.items.custom_origin_config.origin_ssl_protocols` has been deprecated and will be remove in a release after 2026-12-15. Use `elements` instead ([https://github.com/ansible-collections/community.aws/pull/2354](https://github.com/ansible-collections/community.aws/pull/2354) ). * cloudfront\_distribution - The `items` return value in `origins` has been deprecated and will be remove in a release after 2026-12-15. Use `elements` instead ([https://github.com/ansible-collections/community.aws/pull/2354](https://github.com/ansible-collections/community.aws/pull/2354) ). * cloudfront\_distribution - The `items` return value in `restrictions.geo_restriction` has been deprecated and will be remove in a release after 2026-12-15. Use `elements` instead ([https://github.com/ansible-collections/community.aws/pull/2354](https://github.com/ansible-collections/community.aws/pull/2354) ). * cloudfront\_invalidation - The `items` return value in `invalidation.invalidation_batch.paths` has been deprecated and will be remove in a release after 2026-12-15. Use `elements` instead ([https://github.com/ansible-collections/community.aws/pull/2354](https://github.com/ansible-collections/community.aws/pull/2354) ). * cloudfront\_invalidation - The `items` return value in `invalidation.invalidation_batch.paths` has been deprecated and will be removed in a release after 2026-12-15. Use `elements` instead ([https://github.com/ansible-collections/community.aws/pull/2354](https://github.com/ansible-collections/community.aws/pull/2354) ). * waf\_condition - The module has been deprecated as Amazon has retired the `WAF Classic` service. Please use the `AWS WAF (WAFv2)` service and modules instead. The module will be removed in version 12.0.0 ([https://github.com/ansible-collections/community.aws/pull/2389](https://github.com/ansible-collections/community.aws/pull/2389) ). * waf\_info - The module has been deprecated as Amazon has retired the `WAF Classic` service. Please use the `AWS WAF (WAFv2)` service and modules instead. The module will be removed in version 12.0.0 ([https://github.com/ansible-collections/community.aws/pull/2389](https://github.com/ansible-collections/community.aws/pull/2389) ). * waf\_rule - The module has been deprecated as Amazon has retired the `WAF Classic` service. Please use the `AWS WAF (WAFv2)` service and modules instead. The module will be removed in version 12.0.0 ([https://github.com/ansible-collections/community.aws/pull/2389](https://github.com/ansible-collections/community.aws/pull/2389) ). * waf\_web\_acl - The module has been deprecated as Amazon has retired the `WAF Classic` service. Please use the `AWS WAF (WAFv2)` service and modules instead. The module will be removed in version 12.0.0 ([https://github.com/ansible-collections/community.aws/pull/2389](https://github.com/ansible-collections/community.aws/pull/2389) ). #### kubernetes.core[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#kubernetes-core "Link to this heading") * helm - the `status.values` return value has been deprecated and will be removed in a release after 2027-01-08. Use `status.release_values` instead ([https://github.com/ansible-collections/kubernetes.core/pull/1056](https://github.com/ansible-collections/kubernetes.core/pull/1056) ). * helm\_info - the `status.values` return value has been deprecated and will be removed in a release after 2027-01-08. Use `status.release_values` instead ([https://github.com/ansible-collections/kubernetes.core/pull/1056](https://github.com/ansible-collections/kubernetes.core/pull/1056) ). #### vmware.vmware\_rest[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#vmware-vmware-rest "Link to this heading") * Deprecate modules that have been moved to the new vmware.vmware collection. Includes vcenter\_vm\_guest\_customization, vcenter\_vm\_hardware\_adapter\_sata, vcenter\_vm\_hardware\_adapter\_scsi, vcenter\_vm\_hardware\_cdrom, vcenter\_vm\_hardware\_cpu, vcenter\_vm\_hardware\_disk, vcenter\_vm\_hardware\_ethernet, vcenter\_vm\_hardware\_memory, vcenter\_vm [Porting Guide for v13.3.0](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id64) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#porting-guide-for-v13-3-0 "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Added Collections[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id13 "Link to this heading") * community.clickhouse (version 2.0.0) * pcg.alpaca\_operator (version 2.1.1) ### Major Changes[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id14 "Link to this heading") #### community.vmware[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#community-vmware "Link to this heading") * Bump required `vmware.vmware` collection version to 2.5.0 ([https://github.com/ansible-collections/community.vmware/pull/2503](https://github.com/ansible-collections/community.vmware/pull/2503) ). #### containers.podman[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id15 "Link to this heading") * Rewrite podman and buildah connections ### Deprecated Features[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id16 "Link to this heading") * The `netapp.cloudmanager` collection is considered unmaintained and will be removed from Ansible 15 if no one starts maintaining it again before Ansible 15. See [Collections Removal Process for unmaintained collections](https://docs.ansible.com/projects/ansible/devel/community/collection_contributors/collection_package_removal.html#unmaintained-collections) for more details, including for how this can be cancelled ([https://forum.ansible.com/t/44891](https://forum.ansible.com/t/44891) ). After removal, users can still install this collection with `ansible-galaxy collection install netapp.cloudmanager`. #### amazon.aws[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#amazon-aws "Link to this heading") * ec2\_vpc\_dhcp\_option - the `dhcp_config` return value has been deprecated and will be removed in a release after 2026-12-01. Use `dhcp_options` instead ([https://github.com/ansible-collections/amazon.aws/pull/2772](https://github.com/ansible-collections/amazon.aws/pull/2772) ). * ec2\_vpc\_dhcp\_option\_info - the `dhcp_config` return value has been deprecated and will be removed in a release after 2026-12-01. Use `dhcp_options` instead ([https://github.com/ansible-collections/amazon.aws/pull/2772](https://github.com/ansible-collections/amazon.aws/pull/2772) ). * route53 - the `values` key in the `resource_record_sets` return value has been deprecated in favor of `record_values` for Jinja2 compatibility. The `values` key will be removed in a release after 2026-12-01 ([https://github.com/ansible-collections/amazon.aws/pull/2772](https://github.com/ansible-collections/amazon.aws/pull/2772) ). #### hetzner.hcloud[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#hetzner-hcloud "Link to this heading") * hcloud inventory - The `hcloud_datacenter` host variable is deprecated and will be removed after 1 July 2026. Please use the `hcloud_location` host variable instead. * network\_info - The `hcloud_network_info[].servers[].datacenter` return value is deprecated and will be removed after 1 July 2026. Please use the `hcloud_network_info[].servers[].location` return value instead. * primary\_ip - The `datacenter` argument is deprecated and will be removed after 1 July 2026. Please use the `location` argument instead. * primary\_ip - The `hcloud_primary_ip.datacenter` return value is deprecated and will be removed after 1 July 2026. Please use the `hcloud_primary_ip.location` return value instead. * primary\_ip\_info - The `hcloud_primary_ip_info[].datacenter` return value is deprecated and will be removed after 1 July 2026. Please use the `hcloud_primary_ip_info[].location` return value instead. * server - The `datacenter` argument is deprecated and will be removed after 1 July 2026. Please use the `location` argument instead. * server - The `hcloud_server.datacenter` return value is deprecated and will be removed after 1 July 2026. Please use the `hcloud_server.location` return value instead. * server\_info - The `hcloud_server_info[].datacenter` return value is deprecated and will be removed after 1 July 2026. Please use the `hcloud_server_info[].location` return value instead. [Porting Guide for v13.2.0](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id65) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#porting-guide-for-v13-2-0 "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Major Changes[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id17 "Link to this heading") #### netapp.ontap[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id18 "Link to this heading") * na\_ontap\_interface - AWS Lambda support added to the module. * na\_ontap\_lun - AWS Lambda support added to the module. * na\_ontap\_snapshot - AWS Lambda support added to the module. * na\_ontap\_svm - AWS Lambda support added to the module. ### Deprecated Features[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id19 "Link to this heading") #### community.general[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id20 "Link to this heading") * All module utils, plugin utils, and doc fragments will be made **private** in community.general 13.0.0. This means that they will no longer be part of the public API of the collection, and can have breaking changes even in bugfix releases. If you depend on importing code from the module or plugin utils, or use one of the doc fragments, please [comment in the issue to discuss this](https://github.com/ansible-collections/community.general/issues/11312) . Note that this does not affect any use of community.general in task files, roles, or playbooks ([https://github.com/ansible-collections/community.general/issues/11312](https://github.com/ansible-collections/community.general/issues/11312) , [https://github.com/ansible-collections/community.general/pull/11320](https://github.com/ansible-collections/community.general/pull/11320) ). #### community.routeros[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id21 "Link to this heading") * api\_find\_and\_modify - the current defaults for `ignore_dynamic` and `ignore_builtin` (both `false`) have been deprecated and will change to `true` in community.routeros 4.0.0. To avoid deprecation messages, please set the value explicitly to `true` or `false`, if you have not already done so. We recommend to set them to `true`, unless you have a good reason to set them to `false` ([https://github.com/ansible-collections/community.routeros/pull/399](https://github.com/ansible-collections/community.routeros/pull/399) ). [Porting Guide for v13.1.0](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id66) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#porting-guide-for-v13-1-0 "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Known Issues[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id22 "Link to this heading") #### community.docker[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#community-docker "Link to this heading") * docker\_image, docker\_image\_export - idempotency for archiving images depends on whether the image IDs used by the image storage backend correspond to the IDs used in the tarball’s `manifest.json` files. The new default backend in Docker 29 apparently uses image IDs that no longer correspond, whence idempotency no longer works ([https://github.com/ansible-collections/community.docker/pull/1199](https://github.com/ansible-collections/community.docker/pull/1199) ). ### Major Changes[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id23 "Link to this heading") #### vmware.vmware[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#vmware-vmware "Link to this heading") * Replace `ansible.module_utils._text` ([https://github.com/ansible-collections/vmware.vmware/issues/268](https://github.com/ansible-collections/vmware.vmware/issues/268) ). * Replace `ansible.module_utils.common._collections_compat` ([https://github.com/ansible-collections/vmware.vmware/issues/271](https://github.com/ansible-collections/vmware.vmware/issues/271) ). ### Deprecated Features[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id24 "Link to this heading") * The `junipernetworks.junos` collection has been deprecated. It will be removed from Ansible 14 if no one starts maintaining it again before Ansible 14. See [Collections Removal Process for unmaintained collections](https://docs.ansible.com/projects/ansible/devel/community/collection_contributors/collection_package_removal.html#unmaintained-collections) for more details ([https://forum.ansible.com/t/44869](https://forum.ansible.com/t/44869) ). #### community.general[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id25 "Link to this heading") * cloud module utils - this module utils is not used by community.general and will thus be removed from community.general 13.0.0. If you are using it from another collection, please copy it over ([https://github.com/ansible-collections/community.general/pull/11205](https://github.com/ansible-collections/community.general/pull/11205) ). * database module utils - this module utils is not used by community.general and will thus be removed from community.general 13.0.0. If you are using it from another collection, please copy it over ([https://github.com/ansible-collections/community.general/pull/11205](https://github.com/ansible-collections/community.general/pull/11205) ). * dconf - deprecate fallback mechanism when `gi.repository` is not available; fallback will be removed in community.general 15.0.0 ([https://github.com/ansible-collections/community.general/pull/11088](https://github.com/ansible-collections/community.general/pull/11088) ). * known\_hosts module utils - this module utils is not used by community.general and will thus be removed from community.general 13.0.0. If you are using it from another collection, please copy it over ([https://github.com/ansible-collections/community.general/pull/11205](https://github.com/ansible-collections/community.general/pull/11205) ). * layman - ClearLinux was made EOL in July 2025.; the module will be removed from community.general 15.0.0 ([https://github.com/ansible-collections/community.general/pull/11087](https://github.com/ansible-collections/community.general/pull/11087) ). * layman - Gentoo deprecated `layman` in mid-2023; the module will be removed from community.general 14.0.0 ([https://github.com/ansible-collections/community.general/pull/11070](https://github.com/ansible-collections/community.general/pull/11070) ). * pushbullet - module relies on Python package supporting Python 3.2 only; the module will be removed from community.general 13.0.0 ([https://github.com/ansible-collections/community.general/pull/11224](https://github.com/ansible-collections/community.general/pull/11224) ). * saslprep module utils - this module utils is not used by community.general and will thus be removed from community.general 13.0.0. If you are using it from another collection, please copy it over ([https://github.com/ansible-collections/community.general/pull/11205](https://github.com/ansible-collections/community.general/pull/11205) ). * spotinst\_aws\_elastigroup - module relies on Python package supporting Python 2.7 only; the module will be removed from community.general 13.0.0 ([https://github.com/ansible-collections/community.general/pull/11069](https://github.com/ansible-collections/community.general/pull/11069) ). [Porting Guide for v13.0.0](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id67) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#porting-guide-for-v13-0-0 "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Added Collections[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id26 "Link to this heading") * hitachivantara.vspone\_object (version 1.0.0) * ravendb.ravendb (version 1.0.4) ### Known Issues[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id27 "Link to this heading") #### Ansible-core[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#ansible-core "Link to this heading") * templating - Exceptions raised in a Jinja `set` or `with` block which are not accessed by the template are ignored in the same manner as undefined values. * templating - Passing a container created in a Jinja `set` or `with` block to a method results in a copy of that container. Mutations to that container which are not returned by the method will be discarded. #### community.sops[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#community-sops "Link to this heading") * When using the `community.sops.load_vars` with ansible-core 2.20, note that the deprecation of `INJECT_FACTS_AS_VARS` causes deprecation warnings to be shown every time a variable loaded with `community.sops.load_vars` is used. This is due to ansible-core deprecating `INJECT_FACTS_AS_VARS` without providing an alternative for modules like `community.sops.load_vars` to use. If you do not like these deprecation warnings, you have to explicitly set `INJECT_FACTS_AS_VARS` to `true`. **DO NOT** change the use of SOPS encrypted variables to `ansible_facts`. The situation will hopefully improve in ansible-core 2.21 through the promised API that allows action plugins to set variables; community.sops will adapt to use it, which will make the warning go away. (The API was originally promised for ansible-core 2.20, but then delayed.) #### dellemc.openmanage[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#dellemc-openmanage "Link to this heading") * Formal qualification of module ome\_smart\_fabric\_info for Ansible Core version 2.19 is still pending. * idrac\_attributes - The module accepts both the string as well as integer value for the field “SNMP.1.AgentCommunity” for iDRAC10. * idrac\_diagnostics - This module does not support export of diagnostics file to HTTP and HTTPS share via SOCKS proxy. * idrac\_license - Due to API limitation, proxy parameters are ignored during the import operation. * idrac\_license - The module will fail to export license to NFS Share. * idrac\_license - The module will give different error messages for iDRAC9 and iDRAC10 when user imports license with invalid share name. * idrac\_os\_deployment - The module continues to return a 200 response and marks the job as completed, even when an outdated date is supplied in the Expose duration. * idrac\_redfish\_storage\_controller - PatrolReadRatePercent attribute cannot be set in iDRAC10. * idrac\_server\_config\_profile - When attempting to revert iDRAC settings using a previously exported SCP file, the import operation will complete with errors if a new user was created after the export (Instead of restoring the system to its previous state, including the removal of newly added users). * idrac\_system\_info - The module will show empty video list despite having Embedded VIDEO controller. * ome\_smart\_fabric\_uplink - The module supported by OpenManage Enterprise Modular, however it does not allow the creation of multiple uplinks of the same name. If an uplink is created using the same name as an existing uplink, then the existing uplink is modified. * redfish\_storage\_volume - Encryption type and block\_io\_size bytes will be read only property in iDRAC 9 and iDRAC 10 and hence the module ignores these parameters. * redfish\_storage\_volume - Encryption type and block\_io\_size bytes will be read only property in iDRAC9 and iDRAC10 and hence the module ignores these parameters. ### Breaking Changes[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id28 "Link to this heading") #### Ansible-core[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id29 "Link to this heading") * powershell - Removed code that tried to remote quotes from paths when performing Windows operations like copying and fetching file. This should not affect normal playbooks unless a value is quoted too many times. #### community.docker[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id30 "Link to this heading") * All doc fragments, module utils, and plugin utils are from now on private. They can change at any time, and have breaking changes even in bugfix releases ([https://github.com/ansible-collections/community.docker/pull/1144](https://github.com/ansible-collections/community.docker/pull/1144) ). #### community.general[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id31 "Link to this heading") * mh.base module utils - `debug` will now always be delegated to the underlying `AnsibleModule` object ([https://github.com/ansible-collections/community.general/pull/10883](https://github.com/ansible-collections/community.general/pull/10883) ). * oneview module utils - remove import of standard library `os` ([https://github.com/ansible-collections/community.general/pull/10644](https://github.com/ansible-collections/community.general/pull/10644) ). * slack - the default of `prepend_hash` changed from `auto` to `never` ([https://github.com/ansible-collections/community.general/pull/10883](https://github.com/ansible-collections/community.general/pull/10883) ). #### community.mysql[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id32 "Link to this heading") * Since version 4.0.0, the collection accepts code written in Python 3. Modules aren’t tested against Python 2 and might not work in Python 2 environments. * collection - stop testing against mysqlclient connector as its support was deprecated in this collection - use PyMySQL connector instead! It’ll stop working in 5.0.0 when we remove all related code ([https://github.com/ansible-collections/community.mysql/issues/654](https://github.com/ansible-collections/community.mysql/issues/654) ). * mysql\_db - the `pipefail` argument’s default value is set to `true`. If your target machines do not use `bash` as a default interpreter, set `pipefail` to `false` explicitly. However, we strongly recommend setting up `bash` as a default and `pipefail=true` as it will protect you from getting broken dumps you don’t know about ([https://github.com/ansible-collections/community.mysql/issues/407](https://github.com/ansible-collections/community.mysql/issues/407) ). * mysql\_info - The `users_info` filter does not return the `plugin_auth_string` field anymore. Use the plugin\_hash\_string return value instead ([https://github.com/ansible-collections/community.mysql/pull/629](https://github.com/ansible-collections/community.mysql/pull/629) ). * mysql\_role - the `column_case_sensitive` argument’s default value has been changed to `true`. If your playbook expected the column to be automatically uppercased for your users privileges, you should set this to `false` explicitly ([https://github.com/ansible-collections/community.mysql/issues/578](https://github.com/ansible-collections/community.mysql/issues/578) ). * mysql\_user - the `column_case_sensitive` argument’s default value has been changed to `true`. If your playbook expected the column to be automatically uppercased for your users privileges, you should set this to `false` explicitly ([https://github.com/ansible-collections/community.mysql/issues/577](https://github.com/ansible-collections/community.mysql/issues/577) ). #### community.vmware[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id33 "Link to this heading") * Removed support for ansible-core < 2.19.0. * Removed support for vmware.vmware < 2.0.0. * Replace the dependencies on `pyvmomi`, `vmware-vcenter` and `vmware-vapi-common-client` with `vcf-sdk` ([https://github.com/ansible-collections/community.vmware/pull/2457](https://github.com/ansible-collections/community.vmware/pull/2457) ). #### hetzner.hcloud[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id34 "Link to this heading") * Drop support for Python 3.9 * Drop support for ansible-core 2.17 #### ibm.storage\_virtualize[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#ibm-storage-virtualize "Link to this heading") * ibm\_sv\_manage\_flashsystem\_grid - The flashsystem grid module now uses newer FlashSystem REST APIs to perform tasks. ### Major Changes[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id35 "Link to this heading") #### Ansible-core[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id36 "Link to this heading") * ansible - Add support for Python 3.14. * ansible - Drop support for Python 3.11 on the controller. * ansible - Drop support for Python 3.8 on targets. #### community.vmware[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id37 "Link to this heading") * Re-use code from `vmware.vmware` ([https://github.com/ansible-collections/community.vmware/pull/2459](https://github.com/ansible-collections/community.vmware/pull/2459) ). * Replace `ansible.module_utils._text` ([https://github.com/ansible-collections/community.vmware/issues/2497](https://github.com/ansible-collections/community.vmware/issues/2497) ). * Replace `ansible.module_utils.common._collections_compat` ([https://github.com/ansible-collections/community.vmware/issues/2497](https://github.com/ansible-collections/community.vmware/issues/2497) ). * Replace `ansible.module_utils.six` ([https://github.com/ansible-collections/community.vmware/pull/2495](https://github.com/ansible-collections/community.vmware/pull/2495) ). #### containers.podman[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id38 "Link to this heading") * Add inventory plugins for buildah and podman * Add podman system connection modules #### dellemc.openmanage[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id39 "Link to this heading") * The OpenManage Enterprise, OpenManage Enterprise Modular and OpenManage Enterprise Integration for VMware vCenter modules are now compatible with Ansible Core version 2.19. * idrac\_certificate - This role is enhanced to support iDRAC10. * idrac\_export\_server\_config\_profile - This role is enhanced to support iDRAC10. * idrac\_firmware - This role is enhanced to support iDRAC10. * idrac\_import\_server\_config\_profile - This role is enhanced to support iDRAC10. * idrac\_license - This module is enhanced to support iDRAC10. * idrac\_os\_deployment - This module is enhanced to support iDRAC10. * idrac\_os\_deployment - This role is enhanced to support iDRAC10. * idrac\_redfish\_storage\_controller - This module is enhanced to support iDRAC10. * idrac\_server\_config\_profile - This module is enhanced to support iDRAC10. * idrac\_storage\_controller - This role is enhanced to support iDRAC10. * idrac\_storage\_volume - This module is enhanced to support iDRAC10. * redfish\_firmware - This role is enhanced to support iDRAC10. * redfish\_firmware\_rollback - This module is enhanced to support iDRAC10. * redfish\_storage\_volume - This module is enhanced to support iDRAC10. * redfish\_storage\_volume - This role is enhanced to support iDRAC10. #### fortinet.fortios[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id40 "Link to this heading") * Supported new versions 7.6.3 and 7.6.4. * Supported the authentication method when using username and password in v7.6.4. #### grafana.grafana[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#grafana-grafana "Link to this heading") * Add SUSE support to Alloy role by @pozsa in [https://github.com/grafana/grafana-ansible-collection/pull/423](https://github.com/grafana/grafana-ansible-collection/pull/423) * Fallback to empty dict in case grafana\_ini is undefined by @root-expert in [https://github.com/grafana/grafana-ansible-collection/pull/403](https://github.com/grafana/grafana-ansible-collection/pull/403) * Fix Mimir config file validation task by @Windos in [https://github.com/grafana/grafana-ansible-collection/pull/428](https://github.com/grafana/grafana-ansible-collection/pull/428) * Fixes issue by @digiserg in [https://github.com/grafana/grafana-ansible-collection/pull/421](https://github.com/grafana/grafana-ansible-collection/pull/421) * Fixes to foldersFromFilesStructure option by @root-expert in [https://github.com/grafana/grafana-ansible-collection/pull/351](https://github.com/grafana/grafana-ansible-collection/pull/351) * Import custom dashboards only when directory exists by @mahendrapaipuri in [https://github.com/grafana/grafana-ansible-collection/pull/430](https://github.com/grafana/grafana-ansible-collection/pull/430) * Migrate RedHat install to ansible.builtin.package by @r65535 in [https://github.com/grafana/grafana-ansible-collection/pull/431](https://github.com/grafana/grafana-ansible-collection/pull/431) * Restore default listen address and port in Mimir by @56quarters in [https://github.com/grafana/grafana-ansible-collection/pull/456](https://github.com/grafana/grafana-ansible-collection/pull/456) * Updated YUM repo urls from packages.grafana.com to rpm.grafana.com by @DejfCold in [https://github.com/grafana/grafana-ansible-collection/pull/414](https://github.com/grafana/grafana-ansible-collection/pull/414) * Use credentials from grafana\_ini when importing dashboards by @root-expert in [https://github.com/grafana/grafana-ansible-collection/pull/402](https://github.com/grafana/grafana-ansible-collection/pull/402) * add macOS support to alloy role by @l50 in [https://github.com/grafana/grafana-ansible-collection/pull/418](https://github.com/grafana/grafana-ansible-collection/pull/418) * do not skip scrape latest github version even in check\_mode by @cmehat in [https://github.com/grafana/grafana-ansible-collection/pull/408](https://github.com/grafana/grafana-ansible-collection/pull/408) * fix broken Grafana apt repository addition by @kleini in [https://github.com/grafana/grafana-ansible-collection/pull/454](https://github.com/grafana/grafana-ansible-collection/pull/454) * fix datasource documentation by @jeremad in [https://github.com/grafana/grafana-ansible-collection/pull/437](https://github.com/grafana/grafana-ansible-collection/pull/437) * fix mimir\_download\_url\_deb & mimir\_download\_url\_rpm by @germebl in [https://github.com/grafana/grafana-ansible-collection/pull/400](https://github.com/grafana/grafana-ansible-collection/pull/400) * replace None with \[\] for safe length checks by @voidquark in [https://github.com/grafana/grafana-ansible-collection/pull/426](https://github.com/grafana/grafana-ansible-collection/pull/426) * update catalog info by @Duologic in [https://github.com/grafana/grafana-ansible-collection/pull/434](https://github.com/grafana/grafana-ansible-collection/pull/434) * use deb822 for newer debian versions by @Lukas-Heindl in [https://github.com/grafana/grafana-ansible-collection/pull/440](https://github.com/grafana/grafana-ansible-collection/pull/440) #### ieisystem.inmanage[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#ieisystem-inmanage "Link to this heading") * The edit\_m6\_log\_setting.py module has added the ‘server\_status’ attribute; The edit\_network\_bond.py module modifies the attribute descriptions; The edit\_snmp.py and edit\_snmp\_trap.py module modifies the allowable value ranges for the auth\_protocol and priv\_protocol attributes. ([https://github.com/ieisystem/ieisystem.inmanage/pull/30](https://github.com/ieisystem/ieisystem.inmanage/pull/30) ). #### ngine\_io.cloudstack[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#ngine-io-cloudstack "Link to this heading") * Ensuring backwards compatibility and integration tests with CloudStack 4.17 and 4.18. * General overhaul (black code style) and renaming of all modules (dropping `cs_` prefix) ([https://github.com/ngine-io/ansible-collection-cloudstack/pull/141](https://github.com/ngine-io/ansible-collection-cloudstack/pull/141) ). * Update cs dependency to >=3.4.0. ### Removed Collections[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#removed-collections "Link to this heading") * community.digitalocean (previously included version: 1.27.0) * ibm.qradar (previously included version: 4.0.0) You can still install a removed collection manually with `ansible-galaxy collection install `. ### Removed Features[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id41 "Link to this heading") * The deprecated `community.digitalocean` collection has been removed ([https://forum.ansible.com/t/44602](https://forum.ansible.com/t/44602) ). * The deprecated `ibm.qradar` collection has been removed ([https://forum.ansible.com/t/44259](https://forum.ansible.com/t/44259) ). #### Ansible-core[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id42 "Link to this heading") * Removed the option to set the `DEFAULT_TRANSPORT` configuration to `smart` that selects the default transport as either `ssh` or `paramiko` based on the underlying platform configuraton. * `vault`/`unvault` filters - remove the deprecated `vaultid` parameter. * ansible-doc - role entrypoint attributes are no longer shown * ansible-galaxy - remove support for resolvelib >= 0.5.3, < 0.8.0. * ansible-galaxy - removed the v2 Galaxy server API. Galaxy servers hosting collections must support v3. * dnf/dnf5 - remove deprecated `install_repoquery` option. * encrypt - remove deprecated passlib\_or\_crypt API. * paramiko - Removed the `PARAMIKO_HOST_KEY_AUTO_ADD` and `PARAMIKO_LOOK_FOR_KEYS` configuration keys, which were previously deprecated. * py3compat - remove deprecated `py3compat.environ` call. * vars plugins - removed the deprecated `get_host_vars` or `get_group_vars` fallback for vars plugins that do not inherit from `BaseVarsPlugin` and define a `get_vars` method. * yum\_repository - remove deprecated `keepcache` option. #### community.docker[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id43 "Link to this heading") * Remove support for Docker SDK for Python version 1.x.y, also known as `docker-py`. Modules and plugins that use Docker SDK for Python require version 2.0.0+ ([https://github.com/ansible-collections/community.docker/pull/1171](https://github.com/ansible-collections/community.docker/pull/1171) ). * The collection no longer supports Python 3.6 and before. Note that this coincides with the Python requirements of ansible-core 2.17+ ([https://github.com/ansible-collections/community.docker/pull/1123](https://github.com/ansible-collections/community.docker/pull/1123) ). * The collection no longer supports ansible-core 2.15 and 2.16. You need ansible-core 2.17.0 or newer to use community.docker 5.x.y ([https://github.com/ansible-collections/community.docker/pull/1123](https://github.com/ansible-collections/community.docker/pull/1123) ). #### community.general[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id44 "Link to this heading") * Ansible-core 2.16 is no longer supported. This also means that the collection now requires Python 3.7+ ([https://github.com/ansible-collections/community.general/pull/10884](https://github.com/ansible-collections/community.general/pull/10884) ). * bearychat - the module has been removed as the chat service is no longer available ([https://github.com/ansible-collections/community.general/pull/10883](https://github.com/ansible-collections/community.general/pull/10883) ). * cmd\_runner module utils - the parameter `ignore_value_none` to `CmdRunner.__call__()` has been removed ([https://github.com/ansible-collections/community.general/pull/10883](https://github.com/ansible-collections/community.general/pull/10883) ). * cmd\_runner\_fmt module utils - the parameter `ctx_ignore_none` to argument formatters has been removed ([https://github.com/ansible-collections/community.general/pull/10883](https://github.com/ansible-collections/community.general/pull/10883) ). * facter - the module has been replaced by `community.general.facter_facts` ([https://github.com/ansible-collections/community.general/pull/10883](https://github.com/ansible-collections/community.general/pull/10883) ). * mh.deco module utils - the parameters `on_success` and `on_failure` of `cause()` have been removed; use `when="success"` and `when="failure"` instead ([https://github.com/ansible-collections/community.general/pull/10883](https://github.com/ansible-collections/community.general/pull/10883) ). * opkg - the value `""` for the option `force` is no longer allowed. Omit `force` instead ([https://github.com/ansible-collections/community.general/pull/10883](https://github.com/ansible-collections/community.general/pull/10883) ). * pacemaker\_cluster - the option `state` is now required ([https://github.com/ansible-collections/community.general/pull/10883](https://github.com/ansible-collections/community.general/pull/10883) ). * pure module utils - the modules using this module utils have been removed from community.general 3.0.0 ([https://github.com/ansible-collections/community.general/pull/10883](https://github.com/ansible-collections/community.general/pull/10883) ). * purestorage doc fragment - the modules using this doc fragment have been removed from community.general 3.0.0 ([https://github.com/ansible-collections/community.general/pull/10883](https://github.com/ansible-collections/community.general/pull/10883) ). * yaml callback plugin - the deprecated plugin has been removed. Use the default callback with `result_format=yaml` instead ([https://github.com/ansible-collections/community.general/pull/10883](https://github.com/ansible-collections/community.general/pull/10883) ). #### community.vmware[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id45 "Link to this heading") * vmware\_cluster - The deprecated module has been removed. Use `vmware.vmware.cluster` instead ([https://github.com/ansible-collections/community.vmware/pull/2455](https://github.com/ansible-collections/community.vmware/pull/2455) ). * vmware\_cluster\_dpm - The deprecated module has been removed. Use `vmware.vmware.cluster_dpm` instead ([https://github.com/ansible-collections/community.vmware/pull/2455](https://github.com/ansible-collections/community.vmware/pull/2455) ). * vmware\_cluster\_drs - The deprecated module has been removed. Use `vmware.vmware.cluster_drs` instead ([https://github.com/ansible-collections/community.vmware/pull/2455](https://github.com/ansible-collections/community.vmware/pull/2455) ). * vmware\_cluster\_drs\_recommendations - The deprecated module has been removed. Use `vmware.vmware.cluster_drs_recommendations` instead ([https://github.com/ansible-collections/community.vmware/pull/2455](https://github.com/ansible-collections/community.vmware/pull/2455) ). * vmware\_cluster\_vcls - The deprecated module has been removed. Use `vmware.vmware.cluster_vcls` instead ([https://github.com/ansible-collections/community.vmware/pull/2455](https://github.com/ansible-collections/community.vmware/pull/2455) ). ### Deprecated Features[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id46 "Link to this heading") #### Ansible-core[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id47 "Link to this heading") * Deprecated the shell plugin’s `wrap_for_exec` function. This API is not used in Ansible or any known collection and is being removed to simplify the plugin API. Plugin authors should wrap their command to execute within an explicit shell or other known executable. * INJECT\_FACTS\_AS\_VARS configuration currently defaults to `True`, this is now deprecated and it will switch to `False` by Ansible 2.24. You will only get notified if you are accessing ‘injected’ facts (for example, ansible\_os\_distribution vs ansible\_facts\[‘os\_distribution’\]). * hash\_params function in roles/\_\_init\_\_ is being deprecated as it is not in use. * include\_vars - Specifying ‘ignore\_files’ as a string is deprecated. * vars, the internal variable cache will be removed in 2.24. This cache, once used internally exposes variables in inconsistent states, the ‘vars’ and ‘varnames’ lookups should be used instead. #### community.general[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id48 "Link to this heading") * catapult - module is deprecated and will be removed in community.general 13.0.0 ([https://github.com/ansible-collections/community.general/issues/10318](https://github.com/ansible-collections/community.general/issues/10318) , [https://github.com/ansible-collections/community.general/pull/10329](https://github.com/ansible-collections/community.general/pull/10329) ). * cpanm - deprecate `mode=compatibility`, `mode=new` should be used instead ([https://github.com/ansible-collections/community.general/pull/10434](https://github.com/ansible-collections/community.general/pull/10434) ). * dimensiondata doc\_fragments plugin - fragments is deprecated and will be removed in community.general 13.0.0 ([https://github.com/ansible-collections/community.general/pull/10986](https://github.com/ansible-collections/community.general/pull/10986) ). * dimensiondata module\_utils plugin - utils is deprecated and will be removed in community.general 13.0.0 ([https://github.com/ansible-collections/community.general/pull/10986](https://github.com/ansible-collections/community.general/pull/10986) ). * dimensiondata\_network - module is deprecated and will be removed in community.general 13.0.0 ([https://github.com/ansible-collections/community.general/pull/10986](https://github.com/ansible-collections/community.general/pull/10986) ). * dimensiondata\_vlan - module is deprecated and will be removed in community.general 13.0.0 ([https://github.com/ansible-collections/community.general/pull/10986](https://github.com/ansible-collections/community.general/pull/10986) ). * dimensiondata\_wait doc\_fragments plugin - fragments is deprecated and will be removed in community.general 13.0.0 ([https://github.com/ansible-collections/community.general/pull/10986](https://github.com/ansible-collections/community.general/pull/10986) ). * github\_repo - deprecate `force_defaults=true` ([https://github.com/ansible-collections/community.general/pull/10435](https://github.com/ansible-collections/community.general/pull/10435) ). * hiera lookup plugin - retrieving data with Hiera has been deprecated a long time ago; because of that this plugin will be removed from community.general 13.0.0. If you disagree with this deprecation, please create an issue in the community.general repository ([https://github.com/ansible-collections/community.general/issues/4462](https://github.com/ansible-collections/community.general/issues/4462) , [https://github.com/ansible-collections/community.general/pull/10779](https://github.com/ansible-collections/community.general/pull/10779) ). * oci\_utils module utils - utils is deprecated and will be removed in community.general 13.0.0 ([https://github.com/ansible-collections/community.general/issues/10318](https://github.com/ansible-collections/community.general/issues/10318) , [https://github.com/ansible-collections/community.general/pull/10652](https://github.com/ansible-collections/community.general/pull/10652) ). * oci\_vcn - module is deprecated and will be removed in community.general 13.0.0 ([https://github.com/ansible-collections/community.general/issues/10318](https://github.com/ansible-collections/community.general/issues/10318) , [https://github.com/ansible-collections/community.general/pull/10652](https://github.com/ansible-collections/community.general/pull/10652) ). * oneandone module utils - DNS fails to resolve the API endpoint used by the module. The module is deprecated and will be removed in community.general 13.0.0 ([https://github.com/ansible-collections/community.general/pull/10994](https://github.com/ansible-collections/community.general/pull/10994) ). * oneandone\_firewall\_policy - DNS fails to resolve the API endpoint used by the module. The module is deprecated and will be removed in community.general 13.0.0 ([https://github.com/ansible-collections/community.general/pull/10994](https://github.com/ansible-collections/community.general/pull/10994) ). * oneandone\_load\_balancer - DNS fails to resolve the API endpoint used by the module. The module is deprecated and will be removed in community.general 13.0.0 ([https://github.com/ansible-collections/community.general/pull/10994](https://github.com/ansible-collections/community.general/pull/10994) ). * oneandone\_monitoring\_policy - DNS fails to resolve the API endpoint used by the module. The module is deprecated and will be removed in community.general 13.0.0 ([https://github.com/ansible-collections/community.general/pull/10994](https://github.com/ansible-collections/community.general/pull/10994) ). * oneandone\_private\_network - DNS fails to resolve the API endpoint used by the module. The module is deprecated and will be removed in community.general 13.0.0 ([https://github.com/ansible-collections/community.general/pull/10994](https://github.com/ansible-collections/community.general/pull/10994) ). * oneandone\_public\_ip - DNS fails to resolve the API endpoint used by the module. The module is deprecated and will be removed in community.general 13.0.0 ([https://github.com/ansible-collections/community.general/pull/10994](https://github.com/ansible-collections/community.general/pull/10994) ). * oneandone\_server - DNS fails to resolve the API endpoint used by the module. The module is deprecated and will be removed in community.general 13.0.0 ([https://github.com/ansible-collections/community.general/pull/10994](https://github.com/ansible-collections/community.general/pull/10994) ). * oracle\* doc fragments - fragments are deprecated and will be removed in community.general 13.0.0 ([https://github.com/ansible-collections/community.general/issues/10318](https://github.com/ansible-collections/community.general/issues/10318) , [https://github.com/ansible-collections/community.general/pull/10652](https://github.com/ansible-collections/community.general/pull/10652) ). * pacemaker\_cluster - the state `cleanup` will be removed from community.general 14.0.0 ([https://github.com/ansible-collections/community.general/pull/10741](https://github.com/ansible-collections/community.general/pull/10741) ). * rocketchat - the default value for `is_pre740`, currently `true`, is deprecated and will change to `false` in community.general 13.0.0 ([https://github.com/ansible-collections/community.general/pull/10490](https://github.com/ansible-collections/community.general/pull/10490) ). * typetalk - module is deprecated and will be removed in community.general 13.0.0 ([https://github.com/ansible-collections/community.general/pull/9499](https://github.com/ansible-collections/community.general/pull/9499) ). #### community.hrobot[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#community-hrobot "Link to this heading") * storagebox\* modules - membership in the `community.hrobot.robot` action group (module defaults group) is deprecated; the modules will be removed from the group in community.hrobot 3.0.0. Use `community.hrobot.api` instead ([https://github.com/ansible-collections/community.hrobot/pull/178](https://github.com/ansible-collections/community.hrobot/pull/178) ). * storagebox\* modules - the `hetzner_token` option for these modules will be required from community.hrobot 3.0.0 on ([https://github.com/ansible-collections/community.hrobot/pull/178](https://github.com/ansible-collections/community.hrobot/pull/178) ). * storagebox\* modules - the `hetzner_user` and `hetzner_pass` options for these modules are deprecated; support will be removed in community.hrobot 3.0.0. Use `hetzner_token` instead ([https://github.com/ansible-collections/community.hrobot/pull/178](https://github.com/ansible-collections/community.hrobot/pull/178) ). * storagebox\_info - the `storageboxes[].login`, `storageboxes[].disk_quota`, `storageboxes[].disk_usage`, `storageboxes[].disk_usage_data`, `storageboxes[].disk_usage_snapshot`, `storageboxes[].webdav`, `storageboxes[].samba`, `storageboxes[].ssh`, `storageboxes[].external_reachability`, and `storageboxes[].zfs` return values are deprecated and will be removed from community.routeros. Check out the documentation to find out their new names according to the new API ([https://github.com/ansible-collections/community.hrobot/pull/178](https://github.com/ansible-collections/community.hrobot/pull/178) ). * storagebox\_snapshot\_info - the `snapshots[].timestamp`, `snapshots[].size`, `snapshots[].filesystem_size`, `snapshots[].automatic`, and `snapshots[].comment` return values are deprecated and will be removed from community.routeros. Check out the documentation to find out their new names according to the new API ([https://github.com/ansible-collections/community.hrobot/pull/178](https://github.com/ansible-collections/community.hrobot/pull/178) ). * storagebox\_snapshot\_plan - the `plans[].month` return value is deprecated, since it only returns `null` with the new API and cannot be set to any other value ([https://github.com/ansible-collections/community.hrobot/pull/178](https://github.com/ansible-collections/community.hrobot/pull/178) ). * storagebox\_snapshot\_plan\_info - the `plans[].month` return value is deprecated, since it only returns `null` with the new API and cannot be set to any other value ([https://github.com/ansible-collections/community.hrobot/pull/178](https://github.com/ansible-collections/community.hrobot/pull/178) ). * storagebox\_subaccount - `password_mode=set-to-random` is deprecated and will be removed from community.hrobot 3.0.0. Hetzner’s new API does not support this anyway, it can only be used with the legacy API ([https://github.com/ansible-collections/community.hrobot/pull/183](https://github.com/ansible-collections/community.hrobot/pull/183) ). * storagebox\_subaccount - the `subaccount.homedirectory`, `subaccount.samba`, `subaccount.ssh`, `subaccount.external_reachability`, `subaccount.webdav`, `subaccount.readonly`, `subaccount.createtime`, and `subaccount.comment` return values are deprecated and will be removed from community.routeros. Check out the documentation to find out their new names according to the new API ([https://github.com/ansible-collections/community.hrobot/pull/178](https://github.com/ansible-collections/community.hrobot/pull/178) ). * storagebox\_subaccount\_info - the `subaccounts[].accountid`, `subaccounts[].homedirectory`, `subaccounts[].samba`, `subaccounts[].ssh`, `subaccounts[].external_reachability`, `subaccounts[].webdav`, `subaccounts[].readonly`, `subaccounts[].createtime`, and `subaccounts[].comment` return values are deprecated and will be removed from community.routeros. Check out the documentation to find out their new names according to the new API ([https://github.com/ansible-collections/community.hrobot/pull/178](https://github.com/ansible-collections/community.hrobot/pull/178) ). #### community.vmware[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id49 "Link to this heading") * vmware\_guest\_snapshot - the module has been deprecated and will be removed in community.vmware 8.0.0 ([https://github.com/ansible-collections/community.vmware/pull/2467](https://github.com/ansible-collections/community.vmware/pull/2467) ). #### community.zabbix[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#community-zabbix "Link to this heading") * zabbix\_maintenance module - Depreicated minutes argument for time\_periods #### dellemc.powerflex[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#dellemc-powerflex "Link to this heading") * The device, info, protection\_domain, snapshot, storagepool and volume modules are supported only on PowerFlex Gen1. They are replaced by v2 modules on PowerFlex Gen2. * The fault\_set, replication\_consistency\_group, replication\_pair, resource\_group and sds modules are not supported on PowerFlex Gen2. #### hetzner.hcloud[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#id50 "Link to this heading") * server\_type\_info - Deprecate Server Type `deprecation` property. #### purestorage.flasharray[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_13.html#purestorage-flasharray "Link to this heading") * purefa\_volume\_tags - Deprecated due to removal of REST 1.x support. Will be removed in Collection 2.0.0 --- # Ansible 3 Porting Guide — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * [Ansible Porting Guides](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guides.html) * Ansible 3 Porting Guide * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/porting_guides/porting_guide_3.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Ansible 3 Porting Guide[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#ansible-3-porting-guide "Link to this heading") ================================================================================================================================================================ Ansible 3 is based on Ansible-Base 2.10, which is the same major release as Ansible 2.10. Therefore, there is no section on ansible-base in this porting guide. If you are upgrading from Ansible 2.9, please first consult the Ansible 2.10 porting guide before continuing with the Ansible 3 porting guide. We suggest you read this page along with the [Ansible 3 Changelog](https://github.com/ansible-community/ansible-build-data/blob/main/3/CHANGELOG-v3.rst) to understand what updates you may need to make. [Porting Guide for v3.4.0](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id45) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#porting-guide-for-v3-4-0 "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [Known Issues](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id46) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#known-issues "Link to this heading") #### dellemc.openmanage[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#dellemc-openmanage "Link to this heading") * idrac\_user - Issue(192043) Module may error out with the message `unable to perform the import or export operation because there are pending attribute changes or a configuration job is in progress`. Wait for the job to complete and run the task again. * ome\_configuration\_compliance\_info - Issue(195592) Module may error out with the message `unable to process the request because an error occurred`. If the issue persists, report it to the system administrator. * ome\_smart\_fabric - Issue(185322) Only three design types are supported by OpenManage Enterprise Modular but the module successfully creates a fabric when the design type is not supported. * ome\_smart\_fabric\_uplink - Issue(186024) ome\_smart\_fabric\_uplink module does not allow the creation of multiple uplinks of the same name even though this is supported by OpenManage Enterprise Modular. If an uplink is created using the same name as an existing uplink, the existing uplink is modified. ### [Major Changes](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id47) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#major-changes "Link to this heading") #### Ansible-base[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#ansible-base "Link to this heading") * ansible-test - Tests run with the `centos6` and `default` test containers now use a PyPI proxy container to access PyPI when Python 2.6 is used. This allows tests running under Python 2.6 to continue functioning even though PyPI is discontinuing support for non-SNI capable clients. #### community.postgresql[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#community-postgresql "Link to this heading") * postgresql\_query - the default value of the `as_single_query` option will be changed to `yes` in community.postgresql 2.0.0 ([https://github.com/ansible-collections/community.postgresql/issues/85](https://github.com/ansible-collections/community.postgresql/issues/85) ). #### netapp.ontap[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#netapp-ontap "Link to this heading") * na\_ontap\_autosupport - Added REST support to the module. ### [Deprecated Features](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id48) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#deprecated-features "Link to this heading") #### community.aws[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#community-aws "Link to this heading") * ec2\_vpc\_endpoint\_info - the `query` option has been deprecated and will be removed after 2022-12-01 ([https://github.com/ansible-collections/community.aws/pull/346](https://github.com/ansible-collections/community.aws/pull/346) ). The ec2\_vpc\_endpoint\_info now defaults to listing information about endpoints. The ability to search for information about available services has been moved to the dedicated module `ec2_vpc_endpoint_service_info`. #### community.docker[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#community-docker "Link to this heading") * docker\_\* modules and plugins, except `docker_swarm` connection plugin and `docker_compose` and ```docker_stack*` modules - the current default ``localhost``` for `tls_hostname` is deprecated. In community.docker 2.0.0 it will be computed from `docker_host` instead ([https://github.com/ansible-collections/community.docker/pull/134](https://github.com/ansible-collections/community.docker/pull/134) ). [Porting Guide for v3.3.0](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id49) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#porting-guide-for-v3-3-0 "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [Major Changes](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id50) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id1 "Link to this heading") #### community.mysql[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#community-mysql "Link to this heading") * mysql\_user - the `REQUIRESSL` is an alias for the `ssl` key in the `tls_requires` option in `community.mysql` 2.0.0 and support will be dropped altogether in `community.mysql` 3.0.0 ([https://github.com/ansible-collections/community.mysql/issues/121](https://github.com/ansible-collections/community.mysql/issues/121) ). ### [Deprecated Features](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id51) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id2 "Link to this heading") #### community.vmware[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#community-vmware "Link to this heading") * vmware\_vmkernel\_ip\_config - deprecate in favor of vmware\_vmkernel ([https://github.com/ansible-collections/community.vmware/pull/667](https://github.com/ansible-collections/community.vmware/pull/667) ). #### f5networks.f5\_modules[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#f5networks-f5-modules "Link to this heading") * Support for Python versions earlier than 3.5 is being deprecated [Porting Guide for v3.2.0](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id52) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#porting-guide-for-v3-2-0 "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [Known Issues](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id53) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id3 "Link to this heading") #### dellemc.openmanage[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id4 "Link to this heading") * idrac\_user - Issue(192043) Module may error out with the message `unable to perform the import or export operation because there are pending attribute changes or a configuration job is in progress`. Wait for the job to complete and run the task again. * ome\_configuration\_compliance\_info - Issue(195592) Module may error out with the message `unable to process the request because an error occurred`. If the issue persists, report it to the system administrator. * ome\_smart\_fabric - Issue(185322) Only three design types are supported by OpenManage Enterprise Modular but the module successfully creates a fabric when the design type is not supported. * ome\_smart\_fabric\_uplink - Issue(186024) ome\_smart\_fabric\_uplink module does not allow the creation of multiple uplinks of the same name even though this is supported by OpenManage Enterprise Modular. If an uplink is created using the same name as an existing uplink, the existing uplink is modified. ### [Breaking Changes](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id54) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#breaking-changes "Link to this heading") #### community.docker[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id5 "Link to this heading") * docker\_swarm - if `join_token` is specified, a returned join token with the same value will be replaced by `VALUE_SPECIFIED_IN_NO_LOG_PARAMETER`. Make sure that you do not blindly use the join tokens from the return value of this module when the module is invoked with `join_token` specified! This breaking change appears in a minor release since it is necessary to fix a security issue ([https://github.com/ansible-collections/community.docker/pull/103](https://github.com/ansible-collections/community.docker/pull/103) ). ### [Deprecated Features](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id55) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id6 "Link to this heading") #### community.crypto[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#community-crypto "Link to this heading") * acme module\_utils - the `acme` module\_utils (`ansible_collections.community.crypto.plugins.module_utils.acme`) is deprecated and will be removed in community.crypto 2.0.0. Use the new Python modules in the `acme` package instead (`ansible_collections.community.crypto.plugins.module_utils.acme.xxx`) ([https://github.com/ansible-collections/community.crypto/pull/184](https://github.com/ansible-collections/community.crypto/pull/184) ). [Porting Guide for v3.1.0](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id56) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#porting-guide-for-v3-1-0 "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [Known Issues](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id57) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id7 "Link to this heading") #### dellemc.openmanage[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id8 "Link to this heading") * ome\_smart\_fabric - Issue(185322) Only three design types are supported by OpenManage Enterprise Modular but the module successfully creates a fabric when the design type is not supported. * ome\_smart\_fabric\_uplink - Issue(186024) ome\_smart\_fabric\_uplink module does not allow the creation of multiple uplinks of the same name even though this is supported by OpenManage Enterprise Modular. If an uplink is created using the same name as an existing uplink, the existing uplink is modified. ### [Major Changes](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id58) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id9 "Link to this heading") #### community.grafana[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#community-grafana "Link to this heading") * introduce “skip\_version\_check” parameter in grafana\_teams and grafana\_folder modules (#147) #### community.mysql[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id10 "Link to this heading") * mysql\_replication - the mode options values `getslave`, `startslave`, `stopslave`, `resetslave`, ```resetslaveall` and the master_use_gtid option ``slave_pos``` are deprecated (see the alternative values) and will be removed in `community.mysql` 3.0.0 ([https://github.com/ansible-collections/community.mysql/pull/97](https://github.com/ansible-collections/community.mysql/pull/97) ). * mysql\_replication - the word `SLAVE` in messages returned by the module will be changed to `REPLICA` in `community.mysql` 2.0.0 ([https://github.com/ansible-collections/community.mysql/issues/98](https://github.com/ansible-collections/community.mysql/issues/98) ). ### [Removed Features](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id59) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#removed-features "Link to this heading") #### f5networks.f5\_modules[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id11 "Link to this heading") * Removed TMOS v11 support for bigip\_gtm\_pool and bigip\_gtm\_wide\_ip modules * Removed quorum and monitor\_type parameters in bigip\_node module. See porting guides section at [https://clouddocs.f5.com/products/orchestration/ansible/devel/usage/porting-guides.html](https://clouddocs.f5.com/products/orchestration/ansible/devel/usage/porting-guides.html) * Removed syslog\_settings and pool\_settings parameters in bigip\_log\_destination moduke. See porting guides section at [https://clouddocs.f5.com/products/orchestration/ansible/devel/usage/porting-guides.html](https://clouddocs.f5.com/products/orchestration/ansible/devel/usage/porting-guides.html) ### [Deprecated Features](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id60) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id12 "Link to this heading") #### cloudscale\_ch.cloud[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#cloudscale-ch-cloud "Link to this heading") * The aliases `server_uuids` and `server_uuid` of the servers parameter in the volume module will be removed in version 3.0.0. #### community.aws[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id13 "Link to this heading") * ec2\_eip - formally deprecate the `instance_id` alias for `device_id` ([https://github.com/ansible-collections/community.aws/pull/349](https://github.com/ansible-collections/community.aws/pull/349) ). * ec2\_vpc\_endpoint - deprecate the policy\_file option and recommend using policy with a lookup ([https://github.com/ansible-collections/community.aws/pull/366](https://github.com/ansible-collections/community.aws/pull/366) ). #### community.crypto[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id14 "Link to this heading") * acme\_account\_info - when `retrieve_orders=url_list`, `orders` will no longer be returned in community.crypto 2.0.0. Use `order_uris` instead ([https://github.com/ansible-collections/community.crypto/pull/178](https://github.com/ansible-collections/community.crypto/pull/178) ). #### community.general[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#community-general "Link to this heading") * apt\_rpm - deprecated invalid parameter alias `update-cache`, will be removed in 5.0.0 ([https://github.com/ansible-collections/community.general/pull/1927](https://github.com/ansible-collections/community.general/pull/1927) ). * composer - deprecated invalid parameter aliases `working-dir`, `global-command`, `prefer-source`, `prefer-dist`, `no-dev`, `no-scripts`, `no-plugins`, `optimize-autoloader`, `classmap-authoritative`, `apcu-autoloader`, `ignore-platform-reqs`, will be removed in 5.0.0 ([https://github.com/ansible-collections/community.general/pull/1927](https://github.com/ansible-collections/community.general/pull/1927) ). * github\_deploy\_key - deprecated invalid parameter alias `2fa_token`, will be removed in 5.0.0 ([https://github.com/ansible-collections/community.general/pull/1927](https://github.com/ansible-collections/community.general/pull/1927) ). * grove - the option `message` will be removed in community.general 4.0.0. Use the new option `message_content` instead ([https://github.com/ansible-collections/community.general/pull/1929](https://github.com/ansible-collections/community.general/pull/1929) ). * homebrew - deprecated invalid parameter alias `update-brew`, will be removed in 5.0.0 ([https://github.com/ansible-collections/community.general/pull/1927](https://github.com/ansible-collections/community.general/pull/1927) ). * homebrew\_cask - deprecated invalid parameter alias `update-brew`, will be removed in 5.0.0 ([https://github.com/ansible-collections/community.general/pull/1927](https://github.com/ansible-collections/community.general/pull/1927) ). * opkg - deprecated invalid parameter alias `update-cache`, will be removed in 5.0.0 ([https://github.com/ansible-collections/community.general/pull/1927](https://github.com/ansible-collections/community.general/pull/1927) ). * pacman - deprecated invalid parameter alias `update-cache`, will be removed in 5.0.0 ([https://github.com/ansible-collections/community.general/pull/1927](https://github.com/ansible-collections/community.general/pull/1927) ). * puppet - deprecated undocumented parameter `show_diff`, will be removed in 7.0.0. ([https://github.com/ansible-collections/community.general/pull/1927](https://github.com/ansible-collections/community.general/pull/1927) ). * runit - unused parameter `dist` marked for deprecation ([https://github.com/ansible-collections/community.general/pull/1830](https://github.com/ansible-collections/community.general/pull/1830) ). * slackpkg - deprecated invalid parameter alias `update-cache`, will be removed in 5.0.0 ([https://github.com/ansible-collections/community.general/pull/1927](https://github.com/ansible-collections/community.general/pull/1927) ). * urpmi - deprecated invalid parameter aliases `update-cache` and `no-recommends`, will be removed in 5.0.0 ([https://github.com/ansible-collections/community.general/pull/1927](https://github.com/ansible-collections/community.general/pull/1927) ). * xbps - deprecated invalid parameter alias `update-cache`, will be removed in 5.0.0 ([https://github.com/ansible-collections/community.general/pull/1927](https://github.com/ansible-collections/community.general/pull/1927) ). * xfconf - returning output as facts is deprecated, this will be removed in community.general 4.0.0. Please register the task output in a variable and use it instead. You can already switch to the new behavior now by using the new `disable_facts` option ([https://github.com/ansible-collections/community.general/pull/1747](https://github.com/ansible-collections/community.general/pull/1747) ). [Porting Guide for v3.0.0](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id61) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#porting-guide-for-v3-0-0 "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [Known Issues](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id62) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id15 "Link to this heading") #### dellemc.openmanage[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id16 "Link to this heading") * Issue 1(186024): ome\_smart\_fabric\_uplink module does not allow the creation of multiple uplinks of the same name even though this is supported by OpenManage Enterprise Modular. If an uplink is created using the same name as an existing uplink, the existing uplink is modified. * Issue 2(187956): If an invalid job\_id is provided, idrac\_lifecycle\_controller\_job\_status\_info returns an error message. This error message does not contain information about the exact issue with the invalid job\_id. * Issue 3(188267): While updating the iDRAC firmware, the idrac\_firmware module completes execution before the firmware update job is completed. An incorrect message is displayed in the task output as ‘DRAC WSMAN endpoint returned HTTP code ‘400’ Reason ‘Bad Request’’. This issue may occur if the target iDRAC firmware version is less than 3.30.30.30 ### [Breaking Changes](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id63) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id17 "Link to this heading") #### Ansible-base[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id18 "Link to this heading") * ansible-galaxy login command has been removed ( see [issue 71560](https://github.com/ansible/ansible/issues/71560) ) #### ansible.utils[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#ansible-utils "Link to this heading") * If added custom sub plugins in your collection move from old location plugins/ to the new location plugins/sub\_plugins/ and update the imports as required * Move sub plugins cli\_parsers, fact\_diff and validate to plugins/sub\_plugins folder * The cli\_parsers sub plugins folder name is changed to cli\_parse to have consistent naming convention, that is all the cli\_parse subplugins will now be in plugins/sub\_plugins/cli\_parse folder #### cloudscale\_ch.cloud[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id19 "Link to this heading") * floating\_ip - `name` is required for assigning a new floating IP. #### community.general[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id20 "Link to this heading") * If you use Ansible 2.9 and the Google cloud plugins or modules from this collection, community.general 2.0.0 results in errors when trying to use the Google cloud content by FQCN, like `community.general.gce_img`. Since Ansible 2.9 is not able to use redirections, you will have to adjust your playbooks and roles manually to use the new FQCNs (`community.google.gce_img` for the previous example) and to make sure that you have `community.google` installed. If you use ansible-base 2.10 or newer and did not install Ansible 3.0.0, but installed (and/or upgraded) community.general manually, you need to make sure to also install the `community.google` or `google.cloud` collections if you are using any of the Google cloud plugins or modules. While ansible-base 2.10 or newer can use the redirects that community.general 2.0.0 adds, the collection they point to (such as community.google) must be installed for them to work. * If you use Ansible 2.9 and the Kubevirt plugins or modules from this collection, community.general 2.0.0 results in errors when trying to use the Kubevirt content by FQCN, like `community.general.kubevirt_vm`. Since Ansible 2.9 is not able to use redirections, you will have to adjust your playbooks and roles manually to use the new FQCNs (`community.kubevirt.kubevirt_vm` for the previous example) and to make sure that you have `community.kubevirt` installed. If you use ansible-base 2.10 or newer and did not install Ansible 3.0.0, but installed (and/or upgraded) community.general manually, you need to make sure to also install the `community.kubevirt` collection if you are using any of the Kubevirt plugins or modules. While ansible-base 2.10 or newer can use the redirects that community.general 2.0.0 adds, the collection they point to (such as community.google) must be installed for them to work. * If you use Ansible 2.9 and the `docker` plugins or modules from this collections, community.general 2.0.0 results in errors when trying to use the docker content by FQCN, like `community.general.docker_container`. Since Ansible 2.9 is not able to use redirections, you will have to adjust your playbooks and roles manually to use the new FQCNs (`community.docker.docker_container` for the previous example) and to make sure that you have `community.docker` installed. If you use ansible-base 2.10 or newer and did not install Ansible 3.0.0, but installed (and/or upgraded) community.general manually, you need to make sure to also install `community.docker` if you are using any of the `docker` plugins or modules. While ansible-base 2.10 or newer can use the redirects that community.general 2.0.0 adds, the collection they point to (community.docker) must be installed for them to work. * If you use Ansible 2.9 and the `hashi_vault` lookup plugin from this collections, community.general 2.0.0 results in errors when trying to use the Hashi Vault content by FQCN, like `community.general.hashi_vault`. Since Ansible 2.9 is not able to use redirections, you will have to adjust your inventories, variable files, playbooks and roles manually to use the new FQCN (`community.hashi_vault.hashi_vault`) and to make sure that you have `community.hashi_vault` installed. If you use ansible-base 2.10 or newer and did not install Ansible 3.0.0, but installed (and/or upgraded) community.general manually, you need to make sure to also install `community.hashi_vault` if you are using the `hashi_vault` plugin. While ansible-base 2.10 or newer can use the redirects that community.general 2.0.0 adds, the collection they point to (community.hashi\_vault) must be installed for them to work. * If you use Ansible 2.9 and the `hetzner` modules from this collections, community.general 2.0.0 results in errors when trying to use the hetzner content by FQCN, like `community.general.hetzner_firewall`. Since Ansible 2.9 is not able to use redirections, you will have to adjust your playbooks and roles manually to use the new FQCNs (`community.hrobot.firewall` for the previous example) and to make sure that you have `community.hrobot` installed. If you use ansible-base 2.10 or newer and did not install Ansible 3.0.0, but installed (and/or upgraded) community.general manually, you need to make sure to also install `community.hrobot` if you are using any of the `hetzner` modules. While ansible-base 2.10 or newer can use the redirects that community.general 2.0.0 adds, the collection they point to (community.hrobot) must be installed for them to work. * If you use Ansible 2.9 and the `oc` connection plugin from this collections, community.general 2.0.0 results in errors when trying to use the oc content by FQCN, like `community.general.oc`. Since Ansible 2.9 is not able to use redirections, you will have to adjust your inventories, variable files, playbooks and roles manually to use the new FQCN (`community.okd.oc`) and to make sure that you have `community.okd` installed. If you use ansible-base 2.10 or newer and did not install Ansible 3.0.0, but installed (and/or upgraded) community.general manually, you need to make sure to also install `community.okd` if you are using the `oc` plugin. While ansible-base 2.10 or newer can use the redirects that community.general 2.0.0 adds, the collection they point to (community.okd) must be installed for them to work. * If you use Ansible 2.9 and the `postgresql` modules from this collections, community.general 2.0.0 results in errors when trying to use the postgresql content by FQCN, like `community.general.postgresql_info`. Since Ansible 2.9 is not able to use redirections, you will have to adjust your playbooks and roles manually to use the new FQCNs (`community.postgresql.postgresql_info` for the previous example) and to make sure that you have `community.postgresql` installed. If you use ansible-base 2.10 or newer and did not install Ansible 3.0.0, but installed (and/or upgraded) community.general manually, you need to make sure to also install `community.postgresql` if you are using any of the `postgresql` modules. While ansible-base 2.10 or newer can use the redirects that community.general 2.0.0 adds, the collection they point to (community.postgresql) must be installed for them to work. * The Google cloud inventory script `gce.py` has been migrated to the `community.google` collection. Install the `community.google` collection in order to continue using it. * archive - remove path folder itself when `remove` parameter is true ([https://github.com/ansible-collections/community.general/issues/1041](https://github.com/ansible-collections/community.general/issues/1041) ). * log\_plays callback - add missing information to the logs generated by the callback plugin. This changes the log message format ([https://github.com/ansible-collections/community.general/pull/442](https://github.com/ansible-collections/community.general/pull/442) ). * passwordstore lookup plugin - now parsing a password store entry as YAML if possible, skipping the first line (which by convention only contains the password and nothing else). If it cannot be parsed as YAML, the old `key: value` parser will be used to process the entry. Can break backwards compatibility if YAML formatted code was parsed in a non-YAML interpreted way, for example `foo: [bar, baz]`, will become a list with two elements in the new version, but a string `'[bar, baz]'` in the old ([https://github.com/ansible-collections/community.general/issues/1673](https://github.com/ansible-collections/community.general/issues/1673) ). * pkgng - passing `name: *` with `state: absent` will no longer remove every installed package from the system. It is now a noop. ([https://github.com/ansible-collections/community.general/pull/569](https://github.com/ansible-collections/community.general/pull/569) ). * pkgng - passing `name: *` with `state: latest` or `state: present` will no longer install every package from the configured package repositories. Instead, `name: *, state: latest` will upgrade all already-installed packages, and `name: *, state: present` is a noop. ([https://github.com/ansible-collections/community.general/pull/569](https://github.com/ansible-collections/community.general/pull/569) ). * proxmox\_kvm - recognize `force=yes` in conjunction with `state=absent` to forcibly remove a running VM ([https://github.com/ansible-collections/community.general/pull/849](https://github.com/ansible-collections/community.general/pull/849) ). * utm\_proxy\_auth\_profile - the `frontend_cookie_secret` return value now contains a placeholder string instead of the module’s `frontend_cookie_secret` parameter ([https://github.com/ansible-collections/community.general/pull/1736](https://github.com/ansible-collections/community.general/pull/1736) ). #### community.hashi\_vault[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#community-hashi-vault "Link to this heading") * hashi\_vault - the `VAULT_ADDR` environment variable is now checked last for the `url` parameter. For details on which use cases are impacted, see ([https://github.com/ansible-collections/community.hashi\_vault/issues/8](https://github.com/ansible-collections/community.hashi_vault/issues/8) ). #### community.hrobot[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#community-hrobot "Link to this heading") * firewall - now requires the [ipaddress](https://pypi.org/project/ipaddress/) library ([https://github.com/ansible-collections/community.hrobot/pull/2](https://github.com/ansible-collections/community.hrobot/pull/2) ). #### community.network[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#community-network "Link to this heading") * If you use Ansible 2.9 and the FortiOS modules from this collection, community.network 2.0.0 results in errors when trying to use the FortiOS content by FQCN, like `community.network.fmgr_device`. Since Ansible 2.9 is not able to use redirections, you will have to adjust your playbooks and roles manually to use the new FQCNs (`community.fortios.fmgr_device` for the previous example) and to make sure that you have `community.fortios` installed. If you use ansible-base 2.10 or newer and did not install Ansible 3.0.0, but installed (and/or upgraded) community.network manually, you need to make sure to also install `community.fortios` if you are using any of the FortiOS modules. While ansible-base 2.10 or newer can use the redirects that community.network 2.0.0 adds, the collection they point to (community.fortios) must be installed for them to work. * If you use Ansible 2.9 and the `cp_publish` module from this collection, community.network 2.0.0 results in errors when trying to use the module by FQCN, that is `community.network.cp_publish`. Since Ansible 2.9 is not able to use redirections, you will have to adjust your playbooks and roles manually to use the new FQCNs (`check_point.mgmt.cp_mgmt_publish`) and to make sure that you have `check_point.mgmt` installed. If you use ansible-base 2.10 or newer and did not install Ansible 3.0.0, but installed (and/or upgraded) community.network manually, you need to make sure to also install `check_point.mgmt` if you are using the `cp_publish` module. While ansible-base 2.10 or newer can use the redirects that community.network 2.0.0 adds, the collection they point to (check\_point.mgmt) must be installed for them to work. * If you use Ansible 2.9 and the `fortimanager` httpapi plugin from this collection, community.network 2.0.0 results in errors when trying to use it by FQCN (`community.network.fortimanager`). Since Ansible 2.9 is not able to use redirections, you will have to adjust your playbooks and roles manually to use the new FQCN `fortinet.fortimanager.fortimanager` and to make sure that you have `fortinet.fortimanager` installed. If you use ansible-base 2.10 or newer and did not install Ansible 3.0.0, but installed (and/or upgraded) community.network manually, you need to make sure to also install `fortinet.fortimanager` if you are using the `fortimanager` httpapi plugin. While ansible-base 2.10 or newer can use the redirect that community.network 2.0.0 adds, the collection they point to (fortinet.fortimanager) must be installed for it to work. * If you use Ansible 2.9 and the `nso` modules from this collection, community.network 2.0.0 results in errors when trying to use the nso content by FQCN, like `community.network.nso_config`. Since Ansible 2.9 is not able to use redirections, you will have to adjust your playbooks and roles manually to use the new FQCNs (`cisco.nso.nso_config` for the previous example) and to make sure that you have `cisco.nso` installed. If you use ansible-base 2.10 or newer and did not install Ansible 3.0.0, but installed (and/or upgraded) community.network manually, you need to make sure to also install `cisco.nso` if you are using any of the `nso` modules. While ansible-base 2.10 or newer can use the redirects that community.network 2.0.0 adds, the collection they point to (cisco.nso) must be installed for them to work. * If you use Ansible 2.9 and the `routeros` plugins or modules from this collections, community.network 2.0.0 results in errors when trying to use the routeros content by FQCN, like `community.network.routeros_command`. Since Ansible 2.9 is not able to use redirections, you will have to adjust your playbooks and roles manually to use the new FQCNs (`community.routeros.command` for the previous example) and to make sure that you have `community.routeros` installed. If you use ansible-base 2.10 or newer and did not install Ansible 3.0.0, but installed (and/or upgraded) community.network manually, you need to make sure to also install `community.routeros` if you are using any of the `routeros` plugins or modules. While ansible-base 2.10 or newer can use the redirects that community.network 2.0.0 adds, the collection they point to (community.routeros) must be installed for them to work. * cnos\_static\_route - move ipaddress import from ansible.netcommon to builtin or package before ipaddress is removed from ansible.netcommon. You need to make sure to have the ipaddress package installed if you are using this module on Python 2.7 ([https://github.com/ansible-collections/community.network/pull/129](https://github.com/ansible-collections/community.network/pull/129) ). #### dellemc.os10[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#dellemc-os10 "Link to this heading") * os10\_bgp - Changed “subnet” key as list format instead of dictionary format under “listen” key to support multiple neighbor prefix for listen command * os10\_bgp - Changed “vrf” key as list format instead of dictionary format to support multiple VRF in router BGP and changed the “vrf” key name to “vrfs” #### ngine\_io.cloudstack[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#ngine-io-cloudstack "Link to this heading") * Authentication option using INI files for example `cloudstack.ini`, has been removed. The only supported option to authenticate is by using the module params with fallback to the ENV variables. * default zone deprecation - The zone param default value, across multiple modules, has been deprecated due to unreliable API ([https://github.com/ngine-io/ansible-collection-cloudstack/pull/62](https://github.com/ngine-io/ansible-collection-cloudstack/pull/62) ). ### [Major Changes](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id64) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id21 "Link to this heading") #### cisco.aci[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#cisco-aci "Link to this heading") * Change certificate\_name to name in aci\_aaa\_user\_certificate module for query operation #### community.general[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id22 "Link to this heading") * For community.general 3.0.0, the `ome_device_info`, `idrac_firmware` and `idrac_server_config_profile` modules will be moved to the [dellemc.openmanage](https://galaxy.ansible.com/dellemc/openmanage) collection. A redirection will be inserted so that users using ansible-base 2.10 or newer do not have to change anything. If you use Ansible 2.9 and explicitly use the DellEMC modules mentioned above from this collection, you will need to adjust your playbooks and roles to use FQCNs starting with `dellemc.openmanage.` instead of `community.general.`, for example replace `community.general.ome_device_info` in a task by `dellemc.openmanage.ome_device_info`. If you use ansible-base and installed `community.general` manually and rely on the DellEMC modules mentioned above, you have to make sure to install the `dellemc.openmanage` collection as well. If you are using FQCNs, for example `community.general.ome_device_info` instead of `ome_device_info`, it will continue working, but we still recommend to adjust the FQCNs as well. * The community.general collection no longer depends on the ansible.netcommon collection ([https://github.com/ansible-collections/community.general/pull/1561](https://github.com/ansible-collections/community.general/pull/1561) ). * The community.general collection no longer depends on the ansible.posix collection ([https://github.com/ansible-collections/community.general/pull/1157](https://github.com/ansible-collections/community.general/pull/1157) ). #### community.kubernetes[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#community-kubernetes "Link to this heading") * k8s - Add support for template parameter ([https://github.com/ansible-collections/community.kubernetes/pull/230](https://github.com/ansible-collections/community.kubernetes/pull/230) ). * k8s\_\* - Add support for vaulted kubeconfig and src ([https://github.com/ansible-collections/community.kubernetes/pull/193](https://github.com/ansible-collections/community.kubernetes/pull/193) ). #### community.okd[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#community-okd "Link to this heading") * Add custom k8s module, integrate better Molecule tests ([https://github.com/ansible-collections/community.okd/pull/7](https://github.com/ansible-collections/community.okd/pull/7) ). * Add downstream build scripts to build redhat.openshift ([https://github.com/ansible-collections/community.okd/pull/20](https://github.com/ansible-collections/community.okd/pull/20) ). * Add openshift connection plugin, update inventory plugin to use it ([https://github.com/ansible-collections/community.okd/pull/18](https://github.com/ansible-collections/community.okd/pull/18) ). * Add openshift\_process module for template rendering and optional application of rendered resources ([https://github.com/ansible-collections/community.okd/pull/44](https://github.com/ansible-collections/community.okd/pull/44) ). * Add openshift\_route module for creating routes from services ([https://github.com/ansible-collections/community.okd/pull/40](https://github.com/ansible-collections/community.okd/pull/40) ). * Initial content migration from community.kubernetes ([https://github.com/ansible-collections/community.okd/pull/3](https://github.com/ansible-collections/community.okd/pull/3) ). * openshift\_auth - new module (migrated from k8s\_auth in community.kubernetes) ([https://github.com/ansible-collections/community.okd/pull/33](https://github.com/ansible-collections/community.okd/pull/33) ). #### dellemc.openmanage[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id24 "Link to this heading") * Removed the existing deprecated modules. * Standardization of ten iDRAC ansible modules based on ansible guidelines. * Support for OpenManage Enterprise Modular. #### dellemc.os10[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id25 "Link to this heading") * os10\_bgp - Enhanced router bgp keyword support for non-default vrf which are supported for default vrf and additional keyword to support both default and non-default vrf * os10\_snmp role - Added support for snmp V3 features in community, group, host, engineID #### f5networks.f5\_modules[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id26 "Link to this heading") * Add phone home Teem integration into all modules, functionality can be disabled by setting up F5\_TEEM environment variable or no\_f5\_teem provider parameter * Added async\_timeout parameter to bigip\_ucs\_fetch module to allow customization of module wait for async interface * Changed bigip\_ucs\_fetch module to use asynchronous interface when generating UCS files #### kubernetes.core[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#kubernetes-core "Link to this heading") * Add changelog and fragments and document changelog process ([https://github.com/ansible-collections/kubernetes.core/pull/131](https://github.com/ansible-collections/kubernetes.core/pull/131) ). * helm - New module for managing Helm charts ([https://github.com/ansible-collections/kubernetes.core/pull/61](https://github.com/ansible-collections/kubernetes.core/pull/61) ). * helm\_info - New module for retrieving Helm chart information ([https://github.com/ansible-collections/kubernetes.core/pull/61](https://github.com/ansible-collections/kubernetes.core/pull/61) ). * helm\_plugin - new module to manage Helm plugins ([https://github.com/ansible-collections/kubernetes.core/pull/154](https://github.com/ansible-collections/kubernetes.core/pull/154) ). * helm\_plugin\_info - new modules to gather information about Helm plugins ([https://github.com/ansible-collections/kubernetes.core/pull/154](https://github.com/ansible-collections/kubernetes.core/pull/154) ). * helm\_repository - New module for managing Helm repositories ([https://github.com/ansible-collections/kubernetes.core/pull/61](https://github.com/ansible-collections/kubernetes.core/pull/61) ). * k8s - Add support for template parameter ([https://github.com/ansible-collections/kubernetes.core/pull/230](https://github.com/ansible-collections/kubernetes.core/pull/230) ). * k8s - Inventory source migrated from Ansible 2.9 to Kubernetes collection. * k8s - Lookup plugin migrated from Ansible 2.9 to Kubernetes collection. * k8s - Module migrated from Ansible 2.9 to Kubernetes collection. * k8s\_\* - Add support for vaulted kubeconfig and src ([https://github.com/ansible-collections/kubernetes.core/pull/193](https://github.com/ansible-collections/kubernetes.core/pull/193) ). * k8s\_auth - Module migrated from Ansible 2.9 to Kubernetes collection. * k8s\_config\_resource\_name - Filter plugin migrated from Ansible 2.9 to Kubernetes collection. * k8s\_exec - New module for executing commands on pods through Kubernetes API ([https://github.com/ansible-collections/kubernetes.core/pull/14](https://github.com/ansible-collections/kubernetes.core/pull/14) ). * k8s\_exec - Return rc for the command executed ([https://github.com/ansible-collections/kubernetes.core/pull/158](https://github.com/ansible-collections/kubernetes.core/pull/158) ). * k8s\_info - Module migrated from Ansible 2.9 to Kubernetes collection. * k8s\_log - New module for retrieving pod logs ([https://github.com/ansible-collections/kubernetes.core/pull/16](https://github.com/ansible-collections/kubernetes.core/pull/16) ). * k8s\_scale - Module migrated from Ansible 2.9 to Kubernetes collection. * k8s\_service - Module migrated from Ansible 2.9 to Kubernetes collection. * kubectl - Connection plugin migrated from Ansible 2.9 to Kubernetes collection. * openshift - Inventory source migrated from Ansible 2.9 to Kubernetes collection. #### netbox.netbox[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#netbox-netbox "Link to this heading") * nb\_inventory - Add `dns_name` option that adds `dns_name` to the host when `True` and device has a primary IP address. (#394) * nb\_inventory - Add `status` as a `group_by` option. (398) * nb\_inventory - Move around `extracted_primary_ip` to allow for `config_context` or `custom_field` to overwrite. (#377) * nb\_inventory - Services are now a list of integers due to NetBox 2.10 changes. (#396) * nb\_lookup - Allow ID to be passed in and use `.get` instead of `.filter`. (#376) * nb\_lookup - Allow `api_endpoint` and `token` to be found through env. (#391) #### ovirt.ovirt[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#ovirt-ovirt "Link to this heading") * cluster\_upgrade - Migrate role ([https://github.com/oVirt/ovirt-ansible-collection/pull/94](https://github.com/oVirt/ovirt-ansible-collection/pull/94) ). * disaster\_recovery - Migrate role ([https://github.com/oVirt/ovirt-ansible-collection/pull/134](https://github.com/oVirt/ovirt-ansible-collection/pull/134) ). * engine\_setup - Migrate role ([https://github.com/oVirt/ovirt-ansible-collection/pull/69](https://github.com/oVirt/ovirt-ansible-collection/pull/69) ). * hosted\_engine\_setup - Migrate role ([https://github.com/oVirt/ovirt-ansible-collection/pull/106](https://github.com/oVirt/ovirt-ansible-collection/pull/106) ). * image\_template - Migrate role ([https://github.com/oVirt/ovirt-ansible-collection/pull/95](https://github.com/oVirt/ovirt-ansible-collection/pull/95) ). * infra - Migrate role ([https://github.com/oVirt/ovirt-ansible-collection/pull/92](https://github.com/oVirt/ovirt-ansible-collection/pull/92) ). * manageiq - Migrate role ([https://github.com/oVirt/ovirt-ansible-collection/pull/97](https://github.com/oVirt/ovirt-ansible-collection/pull/97) ). * ovirt\_system\_option\_info - Add new module ([https://github.com/oVirt/ovirt-ansible-collection/pull/206](https://github.com/oVirt/ovirt-ansible-collection/pull/206) ). * repositories - Migrate role ([https://github.com/oVirt/ovirt-ansible-collection/pull/96](https://github.com/oVirt/ovirt-ansible-collection/pull/96) ). * shutdown\_env - Migrate role ([https://github.com/oVirt/ovirt-ansible-collection/pull/112](https://github.com/oVirt/ovirt-ansible-collection/pull/112) ). * vm\_infra - Migrate role ([https://github.com/oVirt/ovirt-ansible-collection/pull/93](https://github.com/oVirt/ovirt-ansible-collection/pull/93) ). #### servicenow.servicenow[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#servicenow-servicenow "Link to this heading") * add new tests (find with no result, search many) * add related tests * add support for ServiceNOW table api display\_value exclude\_reference\_link and suppress\_pagination\_header * use new API for pysnow >=0.6.0 ### [Removed Features](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id65) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id27 "Link to this heading") #### community.docker[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id28 "Link to this heading") * docker\_container - no longer returns `ansible_facts` ([https://github.com/ansible-collections/community.docker/pull/1](https://github.com/ansible-collections/community.docker/pull/1) ). * docker\_container - the default of `networks_cli_compatible` changed to `true` ([https://github.com/ansible-collections/community.docker/pull/1](https://github.com/ansible-collections/community.docker/pull/1) ). * docker\_container - the unused option `trust_image_content` has been removed ([https://github.com/ansible-collections/community.docker/pull/1](https://github.com/ansible-collections/community.docker/pull/1) ). * docker\_image - `state=build` has been removed. Use `present` instead ([https://github.com/ansible-collections/community.docker/pull/1](https://github.com/ansible-collections/community.docker/pull/1) ). * docker\_image - the `container_limits`, `dockerfile`, `http_timeout`, `nocache`, `rm`, `path`, `buildargs`, `pull` have been removed. Use the corresponding suboptions of `build` instead ([https://github.com/ansible-collections/community.docker/pull/1](https://github.com/ansible-collections/community.docker/pull/1) ). * docker\_image - the `force` option has been removed. Use the more specific `force_*` options instead ([https://github.com/ansible-collections/community.docker/pull/1](https://github.com/ansible-collections/community.docker/pull/1) ). * docker\_image - the `source` option is now mandatory ([https://github.com/ansible-collections/community.docker/pull/1](https://github.com/ansible-collections/community.docker/pull/1) ). * docker\_image - the `use_tls` option has been removed. Use `tls` and `validate_certs` instead ([https://github.com/ansible-collections/community.docker/pull/1](https://github.com/ansible-collections/community.docker/pull/1) ). * docker\_image - the default of the `build.pull` option changed to `false` ([https://github.com/ansible-collections/community.docker/pull/1](https://github.com/ansible-collections/community.docker/pull/1) ). * docker\_image\_facts - this alias is on longer available, use `docker_image_info` instead ([https://github.com/ansible-collections/community.docker/pull/1](https://github.com/ansible-collections/community.docker/pull/1) ). * docker\_network - no longer returns `ansible_facts` ([https://github.com/ansible-collections/community.docker/pull/1](https://github.com/ansible-collections/community.docker/pull/1) ). * docker\_network - the `ipam_options` option has been removed. Use `ipam_config` instead ([https://github.com/ansible-collections/community.docker/pull/1](https://github.com/ansible-collections/community.docker/pull/1) ). * docker\_service - no longer returns `ansible_facts` ([https://github.com/ansible-collections/community.docker/pull/1](https://github.com/ansible-collections/community.docker/pull/1) ). * docker\_swarm - `state=inspect` has been removed. Use `docker_swarm_info` instead ([https://github.com/ansible-collections/community.docker/pull/1](https://github.com/ansible-collections/community.docker/pull/1) ). * docker\_swarm\_service - the `constraints` option has been removed. Use `placement.constraints` instead ([https://github.com/ansible-collections/community.docker/pull/1](https://github.com/ansible-collections/community.docker/pull/1) ). * docker\_swarm\_service - the `limit_cpu` and `limit_memory` options has been removed. Use the corresponding suboptions in `limits` instead ([https://github.com/ansible-collections/community.docker/pull/1](https://github.com/ansible-collections/community.docker/pull/1) ). * docker\_swarm\_service - the `log_driver` and `log_driver_options` options has been removed. Use the corresponding suboptions in `logging` instead ([https://github.com/ansible-collections/community.docker/pull/1](https://github.com/ansible-collections/community.docker/pull/1) ). * docker\_swarm\_service - the `reserve_cpu` and `reserve_memory` options has been removed. Use the corresponding suboptions in `reservations` instead ([https://github.com/ansible-collections/community.docker/pull/1](https://github.com/ansible-collections/community.docker/pull/1) ). * docker\_swarm\_service - the `restart_policy`, `restart_policy_attempts`, `restart_policy_delay` and `restart_policy_window` options has been removed. Use the corresponding suboptions in `restart_config` instead ([https://github.com/ansible-collections/community.docker/pull/1](https://github.com/ansible-collections/community.docker/pull/1) ). * docker\_swarm\_service - the `update_delay`, `update_parallelism`, `update_failure_action`, `update_monitor`, `update_max_failure_ratio` and `update_order` options has been removed. Use the corresponding suboptions in `update_config` instead ([https://github.com/ansible-collections/community.docker/pull/1](https://github.com/ansible-collections/community.docker/pull/1) ). * docker\_volume - no longer returns `ansible_facts` ([https://github.com/ansible-collections/community.docker/pull/1](https://github.com/ansible-collections/community.docker/pull/1) ). * docker\_volume - the `force` option has been removed. Use `recreate` instead ([https://github.com/ansible-collections/community.docker/pull/1](https://github.com/ansible-collections/community.docker/pull/1) ). #### community.general[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id29 "Link to this heading") * All Google cloud modules and plugins have now been migrated away from this collection. They can be found in either the [community.google](https://galaxy.ansible.com/community/google) or [google.cloud](https://galaxy.ansible.com/google/cloud) collections. If you use ansible-base 2.10 or newer, redirections have been provided. If you use Ansible 2.9 and installed this collection, you need to adjust the FQCNs (`community.general.gce_img` → `community.google.gce_img`) and make sure to install the community.google or google.cloud collections as appropriate. * All Kubevirt modules and plugins have now been migrated from community.general to the [community.kubevirt](https://galaxy.ansible.com/community/kubevirt) Ansible collection. If you use ansible-base 2.10 or newer, redirections have been provided. If you use Ansible 2.9 and installed this collection, you need to adjust the FQCNs (`community.general.kubevirt_vm` → `community.kubevirt.kubevirt_vm`) and make sure to install the community.kubevirt collection. * All `docker` modules and plugins have been removed from this collection. They have been migrated to the [community.docker](https://galaxy.ansible.com/community/docker) collection. If you use ansible-base 2.10 or newer, redirections have been provided. If you use Ansible 2.9 and installed this collection, you need to adjust the FQCNs (`community.general.docker_container` → `community.docker.docker_container`) and make sure to install the community.docker collection. * All `hetzner` modules have been removed from this collection. They have been migrated to the [community.hrobot](https://galaxy.ansible.com/community/hrobot) collection. If you use ansible-base 2.10 or newer, redirections have been provided. If you use Ansible 2.9 and installed this collection, you need to adjust the FQCNs (`community.general.hetzner_firewall` → `community.hrobot.firewall`) and make sure to install the community.hrobot collection. * All `postgresql` modules have been removed from this collection. They have been migrated to the [community.postgresql](https://galaxy.ansible.com/community/postgresql) collection. If you use ansible-base 2.10 or newer, redirections have been provided. If you use Ansible 2.9 and installed this collection, you need to adjust the FQCNs (`community.general.postgresql_info` → `community.postgresql.postgresql_info`) and make sure to install the community.postgresql collection. * The Google cloud inventory script `gce.py` has been migrated to the `community.google` collection. Install the `community.google` collection in order to continue using it. * The `hashi_vault` lookup plugin has been removed from this collection. It has been migrated to the [community.hashi\_vault](https://galaxy.ansible.com/community/hashi_vault) collection. If you use ansible-base 2.10 or newer, redirections have been provided. If you use Ansible 2.9 and installed this collection, you need to adjust the FQCNs (`community.general.hashi_vault` → `community.hashi_vault.hashi_vault`) and make sure to install the community.hashi\_vault collection. * The `oc` connection plugin has been removed from this collection. It has been migrated to the [community.okd](https://galaxy.ansible.com/community/okd) collection. If you use ansible-base 2.10 or newer, redirections have been provided. If you use Ansible 2.9 and installed this collection, you need to adjust the FQCNs (`community.general.oc` → `community.okd.oc`) and make sure to install the community.okd collection. * The deprecated `actionable` callback plugin has been removed. Use the `ansible.builtin.default` callback plugin with `display_skipped_hosts = no` and `display_ok_hosts = no` options instead ([https://github.com/ansible-collections/community.general/pull/1347](https://github.com/ansible-collections/community.general/pull/1347) ). * The deprecated `foreman` module has been removed. Use the modules from the theforeman.foreman collection instead ([https://github.com/ansible-collections/community.general/pull/1347](https://github.com/ansible-collections/community.general/pull/1347) ) ([https://github.com/ansible-collections/community.general/pull/1347](https://github.com/ansible-collections/community.general/pull/1347) ). * The deprecated `full_skip` callback plugin has been removed. Use the `ansible.builtin.default` callback plugin with `display_skipped_hosts = no` option instead ([https://github.com/ansible-collections/community.general/pull/1347](https://github.com/ansible-collections/community.general/pull/1347) ). * The deprecated `gcdns_record` module has been removed. Use `google.cloud.gcp_dns_resource_record_set` instead ([https://github.com/ansible-collections/community.general/pull/1370](https://github.com/ansible-collections/community.general/pull/1370) ). * The deprecated `gcdns_zone` module has been removed. Use `google.cloud.gcp_dns_managed_zone` instead ([https://github.com/ansible-collections/community.general/pull/1370](https://github.com/ansible-collections/community.general/pull/1370) ). * The deprecated `gce` module has been removed. Use `google.cloud.gcp_compute_instance` instead ([https://github.com/ansible-collections/community.general/pull/1370](https://github.com/ansible-collections/community.general/pull/1370) ). * The deprecated `gcp_backend_service` module has been removed. Use `google.cloud.gcp_compute_backend_service` instead ([https://github.com/ansible-collections/community.general/pull/1370](https://github.com/ansible-collections/community.general/pull/1370) ). * The deprecated `gcp_forwarding_rule` module has been removed. Use `google.cloud.gcp_compute_forwarding_rule` or `google.cloud.gcp_compute_global_forwarding_rule` instead ([https://github.com/ansible-collections/community.general/pull/1370](https://github.com/ansible-collections/community.general/pull/1370) ). * The deprecated `gcp_healthcheck` module has been removed. Use `google.cloud.gcp_compute_health_check`, `google.cloud.gcp_compute_http_health_check` or `google.cloud.gcp_compute_https_health_check` instead ([https://github.com/ansible-collections/community.general/pull/1370](https://github.com/ansible-collections/community.general/pull/1370) ). * The deprecated `gcp_target_proxy` module has been removed. Use `google.cloud.gcp_compute_target_http_proxy` instead ([https://github.com/ansible-collections/community.general/pull/1370](https://github.com/ansible-collections/community.general/pull/1370) ). * The deprecated `gcp_url_map` module has been removed. Use `google.cloud.gcp_compute_url_map` instead ([https://github.com/ansible-collections/community.general/pull/1370](https://github.com/ansible-collections/community.general/pull/1370) ). * The deprecated `gcspanner` module has been removed. Use `google.cloud.gcp_spanner_database` and/or `google.cloud.gcp_spanner_instance` instead ([https://github.com/ansible-collections/community.general/pull/1370](https://github.com/ansible-collections/community.general/pull/1370) ). * The deprecated `github_hooks` module has been removed. Use `community.general.github_webhook` and `community.general.github_webhook_info` instead ([https://github.com/ansible-collections/community.general/pull/1347](https://github.com/ansible-collections/community.general/pull/1347) ). * The deprecated `katello` module has been removed. Use the modules from the theforeman.foreman collection instead ([https://github.com/ansible-collections/community.general/pull/1347](https://github.com/ansible-collections/community.general/pull/1347) ). * The deprecated `na_cdot_aggregate` module has been removed. Use netapp.ontap.na\_ontap\_aggregate instead ([https://github.com/ansible-collections/community.general/pull/1347](https://github.com/ansible-collections/community.general/pull/1347) ). * The deprecated `na_cdot_license` module has been removed. Use netapp.ontap.na\_ontap\_license instead ([https://github.com/ansible-collections/community.general/pull/1347](https://github.com/ansible-collections/community.general/pull/1347) ). * The deprecated `na_cdot_lun` module has been removed. Use netapp.ontap.na\_ontap\_lun instead ([https://github.com/ansible-collections/community.general/pull/1347](https://github.com/ansible-collections/community.general/pull/1347) ). * The deprecated `na_cdot_qtree` module has been removed. Use netapp.ontap.na\_ontap\_qtree instead ([https://github.com/ansible-collections/community.general/pull/1347](https://github.com/ansible-collections/community.general/pull/1347) ). * The deprecated `na_cdot_svm` module has been removed. Use netapp.ontap.na\_ontap\_svm instead ([https://github.com/ansible-collections/community.general/pull/1347](https://github.com/ansible-collections/community.general/pull/1347) ). * The deprecated `na_cdot_user_role` module has been removed. Use netapp.ontap.na\_ontap\_user\_role instead ([https://github.com/ansible-collections/community.general/pull/1347](https://github.com/ansible-collections/community.general/pull/1347) ). * The deprecated `na_cdot_user` module has been removed. Use netapp.ontap.na\_ontap\_user instead ([https://github.com/ansible-collections/community.general/pull/1347](https://github.com/ansible-collections/community.general/pull/1347) ). * The deprecated `na_cdot_volume` module has been removed. Use netapp.ontap.na\_ontap\_volume instead ([https://github.com/ansible-collections/community.general/pull/1347](https://github.com/ansible-collections/community.general/pull/1347) ). * The deprecated `sf_account_manager` module has been removed. Use netapp.elementsw.na\_elementsw\_account instead ([https://github.com/ansible-collections/community.general/pull/1347](https://github.com/ansible-collections/community.general/pull/1347) ). * The deprecated `sf_check_connections` module has been removed. Use netapp.elementsw.na\_elementsw\_check\_connections instead ([https://github.com/ansible-collections/community.general/pull/1347](https://github.com/ansible-collections/community.general/pull/1347) ). * The deprecated `sf_snapshot_schedule_manager` module has been removed. Use netapp.elementsw.na\_elementsw\_snapshot\_schedule instead ([https://github.com/ansible-collections/community.general/pull/1347](https://github.com/ansible-collections/community.general/pull/1347) ). * The deprecated `sf_volume_access_group_manager` module has been removed. Use netapp.elementsw.na\_elementsw\_access\_group instead ([https://github.com/ansible-collections/community.general/pull/1347](https://github.com/ansible-collections/community.general/pull/1347) ). * The deprecated `sf_volume_manager` module has been removed. Use netapp.elementsw.na\_elementsw\_volume instead ([https://github.com/ansible-collections/community.general/pull/1347](https://github.com/ansible-collections/community.general/pull/1347) ). * The deprecated `stderr` callback plugin has been removed. Use the `ansible.builtin.default` callback plugin with `display_failed_stderr = yes` option instead ([https://github.com/ansible-collections/community.general/pull/1347](https://github.com/ansible-collections/community.general/pull/1347) ). * The redirect of the `conjur_variable` lookup plugin to `cyberark.conjur.conjur_variable` collection was removed ([https://github.com/ansible-collections/community.general/pull/1346](https://github.com/ansible-collections/community.general/pull/1346) ). * The redirect of the `firewalld` module and the `firewalld` module\_utils to the `ansible.posix` collection was removed ([https://github.com/ansible-collections/community.general/pull/1346](https://github.com/ansible-collections/community.general/pull/1346) ). * The redirect to the `community.digitalocean` collection was removed for: the `digital_ocean` doc fragment, the `digital_ocean` module\_utils, and the following modules: `digital_ocean`, `digital_ocean_account_facts`, `digital_ocean_account_info`, `digital_ocean_block_storage`, `digital_ocean_certificate`, `digital_ocean_certificate_facts`, `digital_ocean_certificate_info`, `digital_ocean_domain`, `digital_ocean_domain_facts`, `digital_ocean_domain_info`, `digital_ocean_droplet`, `digital_ocean_firewall_facts`, `digital_ocean_firewall_info`, `digital_ocean_floating_ip`, `digital_ocean_floating_ip_facts`, `digital_ocean_floating_ip_info`, `digital_ocean_image_facts`, `digital_ocean_image_info`, `digital_ocean_load_balancer_facts`, `digital_ocean_load_balancer_info`, `digital_ocean_region_facts`, `digital_ocean_region_info`, `digital_ocean_size_facts`, `digital_ocean_size_info`, `digital_ocean_snapshot_facts`, `digital_ocean_snapshot_info`, `digital_ocean_sshkey`, `digital_ocean_sshkey_facts`, `digital_ocean_sshkey_info`, `digital_ocean_tag`, `digital_ocean_tag_facts`, `digital_ocean_tag_info`, `digital_ocean_volume_facts`, `digital_ocean_volume_info` ([https://github.com/ansible-collections/community.general/pull/1346](https://github.com/ansible-collections/community.general/pull/1346) ). * The redirect to the `community.mysql` collection was removed for: the `mysql` doc fragment, the `mysql` module\_utils, and the following modules: `mysql_db`, `mysql_info`, `mysql_query`, `mysql_replication`, `mysql_user`, `mysql_variables` ([https://github.com/ansible-collections/community.general/pull/1346](https://github.com/ansible-collections/community.general/pull/1346) ). * The redirect to the `community.proxysql` collection was removed for: the `proxysql` doc fragment, and the following modules: `proxysql_backend_servers`, `proxysql_global_variables`, `proxysql_manage_config`, `proxysql_mysql_users`, `proxysql_query_rules`, `proxysql_replication_hostgroups`, `proxysql_scheduler` ([https://github.com/ansible-collections/community.general/pull/1346](https://github.com/ansible-collections/community.general/pull/1346) ). * The redirect to the `infinidat.infinibox` collection was removed for: the `infinibox` doc fragment, the `infinibox` module\_utils, and the following modules: `infini_export`, `infini_export_client`, `infini_fs`, `infini_host`, `infini_pool`, `infini_vol` ([https://github.com/ansible-collections/community.general/pull/1346](https://github.com/ansible-collections/community.general/pull/1346) ). * conjur\_variable lookup - has been moved to the `cyberark.conjur` collection. A redirection is active, which will be removed in version 2.0.0 ([https://github.com/ansible-collections/community.general/pull/570](https://github.com/ansible-collections/community.general/pull/570) ). * digital\_ocean\_\* - all DigitalOcean modules have been moved to the `community.digitalocean` collection. A redirection is active, which will be removed in version 2.0.0 ([https://github.com/ansible-collections/community.general/pull/622](https://github.com/ansible-collections/community.general/pull/622) ). * infini\_\* - all infinidat modules have been moved to the `infinidat.infinibox` collection. A redirection is active, which will be removed in version 2.0.0 ([https://github.com/ansible-collections/community.general/pull/607](https://github.com/ansible-collections/community.general/pull/607) ). * iptables\_state - the `ANSIBLE_ASYNC_DIR` environment is no longer supported, use the `async_dir` shell option instead ([https://github.com/ansible-collections/community.general/pull/1371](https://github.com/ansible-collections/community.general/pull/1371) ). * logicmonitor - the module has been removed in 1.0.0 since it is unmaintained and the API used by the module has been turned off in 2017 ([https://github.com/ansible-collections/community.general/issues/539](https://github.com/ansible-collections/community.general/issues/539) , [https://github.com/ansible-collections/community.general/pull/541](https://github.com/ansible-collections/community.general/pull/541) ). * logicmonitor\_facts - the module has been removed in 1.0.0 since it is unmaintained and the API used by the module has been turned off in 2017 ([https://github.com/ansible-collections/community.general/issues/539](https://github.com/ansible-collections/community.general/issues/539) , [https://github.com/ansible-collections/community.general/pull/541](https://github.com/ansible-collections/community.general/pull/541) ). * memcached cache plugin - do not import `CacheModule``s directly. Use ``ansible.plugins.loader.cache_loader` instead ([https://github.com/ansible-collections/community.general/pull/1371](https://github.com/ansible-collections/community.general/pull/1371) ). * mysql\_\* - all MySQL modules have been moved to the `community.mysql` collection. A redirection is active, which will be removed in version 2.0.0 ([https://github.com/ansible-collections/community.general/pull/633](https://github.com/ansible-collections/community.general/pull/633) ). * proxysql\_\* - all ProxySQL modules have been moved to the `community.proxysql` collection. A redirection is active, which will be removed in version 2.0.0 ([https://github.com/ansible-collections/community.general/pull/624](https://github.com/ansible-collections/community.general/pull/624) ). * redis cache plugin - do not import `CacheModule``s directly. Use ``ansible.plugins.loader.cache_loader` instead ([https://github.com/ansible-collections/community.general/pull/1371](https://github.com/ansible-collections/community.general/pull/1371) ). * xml - when `content=attribute`, the `attribute` option is ignored ([https://github.com/ansible-collections/community.general/pull/1371](https://github.com/ansible-collections/community.general/pull/1371) ). #### community.network[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id35 "Link to this heading") * All FortiOS modules and plugins have been removed from this collection. They have been migrated to the [community.fortios](https://galaxy.ansible.com/community/fortios) collection. If you use ansible-base 2.10 or newer, redirections have been provided. If you use Ansible 2.9 and installed this collection, you need to adjust the FQCNs (`community.network.fmgr_device` → `community.fortios.fmgr_device`) and make sure to install the community.fortios collection. * All `nso` modules have been removed from this collection. They have been migrated to the [cisco.nso](https://galaxy.ansible.com/cisco/nso) collection. If you use ansible-base 2.10 or newer, redirections have been provided. If you use Ansible 2.9 and installed this collection, you need to adjust the FQCNs (`community.network.nso_config` → `cisco.nso.nso_config`) and make sure to install the cisco.nso collection. * All `routeros` modules and plugins have been removed from this collection. They have been migrated to the [community.routeros](https://galaxy.ansible.com/community/routeros) collection. If you use ansible-base 2.10 or newer, redirections have been provided. If you use Ansible 2.9 and installed this collection, you need to adjust the FQCNs (`community.network.routeros_command` → `community.routeros.command`) and make sure to install the community.routeros collection. * The `cp_publish` module has been removed from this collection. It was a duplicate of `check_point.mgmt.cp_mgmt_publish` in the [check\_point.mgmt](https://galaxy.ansible.com/check_point/mgmt) collection. If you use ansible-base 2.10 or newer, redirections have been provided. If you use Ansible 2.9 and installed this collection, you need to adjust the FQCNs (`community.network.cp_publish` → `check_point.mgmt.cp_mgmt_publish`) and make sure to install the check\_point.mgmt collection. * The `fortimanager` httpapi plugin has been removed from this collection. It was a duplicate of the one in the [fortinet.fortimanager](https://galaxy.ansible.com/fortinet/fortimanager) collection. If you use ansible-base 2.10 or newer, a redirection has been provided. If you use Ansible 2.9 and installed this collection, you need to adjust the FQCNs (`community.network.fortimanager` → `fortinet.fortimanager.fortimanager`) and make sure to install the fortinet.fortimanager collection. * The dependency on the `check_point.mgmt` collection has been removed. If you depend on that installing `community.network` also installs `check_point.mgmt`, you have to make sure to install `check_point.mgmt` explicitly. * The deprecated Pluribus Networks modules `pn_cluster`, `pn_ospf`, `pn_ospfarea`, `pn_show`, `pn_trunk`, `pn_vlag`, `pn_vlan`, `pn_vrouter`, `pn_vrouterbgp`, `pn_vrouterif`, `pn_vrouterlbif` have been removed ([https://github.com/ansible-collections/community.network/pull/176](https://github.com/ansible-collections/community.network/pull/176) ). * The deprecated modules `panos_admin`, `panos_admpwd`, `panos_cert_gen_ssh`, `panos_check`, `panos_commit`, `panos_dag`, `panos_dag_tags`, `panos_import`, `panos_interface`, `panos_lic`, `panos_loadcfg`, `panos_match_rule`, `panos_mgtconfig`, `panos_nat_rule`, `panos_object`, `panos_op`, `panos_pg`, `panos_query_rules`, `panos_restart`, `panos_sag`, `panos_security_rule`, `panos_set` have been removed. Use modules from the [paloaltonetworks.panos collection](https://galaxy.ansible.com/paloaltonetworks/panos) instead ([https://github.com/ansible-collections/community.network/pull/176](https://github.com/ansible-collections/community.network/pull/176) ). * The redirect to the `mellanox.onyx` collection was removed for: the `onyx` cliconf plugin, terminal plugin, module\_utils, action plugin, doc fragment, and the following modules: `onyx_aaa`, `onyx_bfd`, `onyx_bgp`, `onyx_buffer_pool`, `onyx_command`, `onyx_config`, `onyx_facts`, `onyx_igmp`, `onyx_igmp_interface`, `onyx_igmp_vlan`, `onyx_interface`, `onyx_l2_interface`, `onyx_l3_interface`, `onyx_linkagg`, `onyx_lldp`, `onyx_lldp_interface`, `onyx_magp`, `onyx_mlag_ipl`, `onyx_mlag_vip`, `onyx_ntp`, `onyx_ntp_servers_peers`, `onyx_ospf`, `onyx_pfc_interface`, `onyx_protocol`, `onyx_ptp_global`, `onyx_ptp_interface`, `onyx_qos`, `onyx_snmp`, `onyx_snmp_hosts`, `onyx_snmp_users`, `onyx_syslog_files`, `onyx_syslog_remote`, `onyx_traffic_class`, `onyx_username`, `onyx_vlan`, `onyx_vxlan`, `onyx_wjh` ([https://github.com/ansible-collections/community.network/pull/175](https://github.com/ansible-collections/community.network/pull/175) ). * onyx - all onyx modules and plugins have been moved to the mellanox.onyx collection. Redirects have been added that will be removed in community.network 2.0.0 ([https://github.com/ansible-collections/community.network/pull/83](https://github.com/ansible-collections/community.network/pull/83) ). #### f5networks.f5\_modules[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id36 "Link to this heading") * Removed arp\_state parameter from the bigip\_virtual\_address module ### [Deprecated Features](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id66) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id37 "Link to this heading") #### cisco.nxos[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#cisco-nxos "Link to this heading") * Deprecated nxos\_bgp and nxos\_bgp\_neighbor modules in favor of nxos\_bgp\_global resource module. * Deprecated nxos\_interface\_ospf in favor of nxos\_ospf\_interfaces Resource Module. * Deprecated nxos\_smu in favor of nxos\_rpm module. * The nxos\_ospf\_vrf module is deprecated by nxos\_ospfv2 and nxos\_ospfv3 Resource Modules. #### community.aws[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id38 "Link to this heading") * ec2\_vpc\_igw\_info - After 2022-06-22 the `convert_tags` parameter default value will change from `False` to `True` to match the collection standard behavior ([https://github.com/ansible-collections/community.aws/pull/318](https://github.com/ansible-collections/community.aws/pull/318) ). #### community.docker[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id39 "Link to this heading") * docker\_container - currently `published_ports` can contain port mappings next to the special value `all`, in which case the port mappings are ignored. This behavior is deprecated for community.docker 2.0.0, at which point it will either be forbidden, or this behavior will be properly implemented similar to how the Docker CLI tool handles this ([https://github.com/ansible-collections/community.docker/issues/8](https://github.com/ansible-collections/community.docker/issues/8) , [https://github.com/ansible-collections/community.docker/pull/60](https://github.com/ansible-collections/community.docker/pull/60) ). #### community.general[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id40 "Link to this heading") * The `gluster_heal_info`, `gluster_peer` and `gluster_volume` modules have migrated to the [gluster.gluster](https://galaxy.ansible.com/gluster/gluster) collection. Ansible-base 2.10.1 adjusted the routing target to point to the modules in that collection, so we will remove these modules in community.general 3.0.0. If you use Ansible 2.9, or use FQCNs `community.general.gluster_*` in your playbooks and/or roles, please update them to use the modules from `gluster.gluster` instead. * The ldap\_attr module has been deprecated and will be removed in a later release; use ldap\_attrs instead. * django\_manage - the parameter `liveserver` relates to a no longer maintained third-party module for django. It is now deprecated, and will be remove in community.general 3.0.0 ([https://github.com/ansible-collections/community.general/pull/1154](https://github.com/ansible-collections/community.general/pull/1154) ). * proxmox - the default of the new `proxmox_default_behavior` option will change from `compatibility` to `no_defaults` in community.general 4.0.0. Set the option to an explicit value to avoid a deprecation warning ([https://github.com/ansible-collections/community.general/pull/850](https://github.com/ansible-collections/community.general/pull/850) ). * proxmox\_kvm - the default of the new `proxmox_default_behavior` option will change from `compatibility` to `no_defaults` in community.general 4.0.0. Set the option to an explicit value to avoid a deprecation warning ([https://github.com/ansible-collections/community.general/pull/850](https://github.com/ansible-collections/community.general/pull/850) ). * syspatch - deprecate the redundant `apply` argument ([https://github.com/ansible-collections/community.general/pull/360](https://github.com/ansible-collections/community.general/pull/360) ). * xbps - the `force` option never had any effect. It is now deprecated, and will be removed in 3.0.0 ([https://github.com/ansible-collections/community.general/pull/568](https://github.com/ansible-collections/community.general/pull/568) ). #### community.hashi\_vault[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id41 "Link to this heading") * hashi\_vault - `VAULT_ADDR` environment variable for option `url` will have its precedence lowered in 1.0.0; use `ANSIBLE_HASHI_VAULT_ADDR` to intentionally override a config value ([https://github.com/ansible-collections/community.hashi\_vault/issues/8](https://github.com/ansible-collections/community.hashi_vault/issues/8) ). * hashi\_vault - `VAULT_AUTH_METHOD` environment variable for option `auth_method` will be removed in 2.0.0, use `ANSIBLE_HASHI_VAULT_AUTH_METHOD` instead ([https://github.com/ansible-collections/community.hashi\_vault/issues/17](https://github.com/ansible-collections/community.hashi_vault/issues/17) ). * hashi\_vault - `VAULT_ROLE_ID` environment variable for option `role_id` will be removed in 2.0.0, use `ANSIBLE_HASHI_VAULT_ROLE_ID` instead ([https://github.com/ansible-collections/community.hashi\_vault/issues/20](https://github.com/ansible-collections/community.hashi_vault/issues/20) ). * hashi\_vault - `VAULT_SECRET_ID` environment variable for option `secret_id` will be removed in 2.0.0, use `ANSIBLE_HASHI_VAULT_SECRET_ID` instead ([https://github.com/ansible-collections/community.hashi\_vault/issues/20](https://github.com/ansible-collections/community.hashi_vault/issues/20) ). * hashi\_vault - `VAULT_TOKEN_FILE` environment variable for option `token_file` will be removed in 2.0.0, use `ANSIBLE_HASHI_VAULT_TOKEN_FILE` instead ([https://github.com/ansible-collections/community.hashi\_vault/issues/15](https://github.com/ansible-collections/community.hashi_vault/issues/15) ). * hashi\_vault - `VAULT_TOKEN_PATH` environment variable for option `token_path` will be removed in 2.0.0, use `ANSIBLE_HASHI_VAULT_TOKEN_PATH` instead ([https://github.com/ansible-collections/community.hashi\_vault/issues/15](https://github.com/ansible-collections/community.hashi_vault/issues/15) ). #### community.network[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id42 "Link to this heading") * Deprecate connection=local support for network platforms using persistent framework ([https://github.com/ansible-collections/community.network/pull/120](https://github.com/ansible-collections/community.network/pull/120) ). #### community.vmware[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id43 "Link to this heading") * vmware\_host\_firewall\_manager - the creation of new rule with no `allowed_ip` entry in the `allowed_hosts` dictionary won’t be allowed after 2.0.0 release. #### dellemc.openmanage[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_3.html#id44 "Link to this heading") * The `dellemc_get_firmware_inventory` module is deprecated and replaced with `idrac_firmware_info`. * The `dellemc_get_system_inventory` module is deprecated and replaced with `idrac_system_info`. * The dellemc\_change\_power\_state module is deprecated and replaced with the redfish\_powerstate module. * The dellemc\_configure\_bios module is deprecated and replaced with the idrac\_bios module. * The dellemc\_configure\_idrac\_network module is deprecated and replaced with the idrac\_network module. * The dellemc\_configure\_idrac\_timezone module is deprecated and replaced with the idrac\_timezone\_ntp module. * The dellemc\_configure\_idrac\_users module is deprecated and replaced with the idrac\_user module. * The dellemc\_delete\_lc\_job and dellemc\_delete\_lc\_job\_queue modules are deprecated and replaced with the idrac\_lifecycle\_controller\_jobs module. * The dellemc\_export\_lc\_logs module is deprecated and replaced with the idrac\_lifecycle\_controller\_logs module. * The dellemc\_get\_lc\_job\_status module is deprecated and replaced with the idrac\_lifecycle\_controller\_job\_status\_info module. * The dellemc\_get\_lcstatus module is deprecated and replaced with the idrac\_lifecycle\_controller\_status\_info module. * The dellemc\_idrac\_reset module is deprecated and replaced with the idrac\_reset module. * The dellemc\_setup\_idrac\_syslog module is deprecated and replaced with the idrac\_syslog module. --- # Ansible 4 Porting Guide — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * [Ansible Porting Guides](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guides.html) * Ansible 4 Porting Guide * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/porting_guides/porting_guide_4.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Ansible 4 Porting Guide[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#ansible-4-porting-guide "Link to this heading") ================================================================================================================================================================ We suggest you read this page along with the [Ansible 4 Changelog](https://github.com/ansible-community/ansible-build-data/blob/main/4/CHANGELOG-v4.rst) to understand what updates you may need to make. [Playbook](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id79) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#playbook "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * The `jinja2_native` setting now does not affect the template module which implicitly returns strings. For the template lookup there is a new argument `jinja2_native` (off by default) to control that functionality. The rest of the Jinja2 expressions still operate based on the `jinja2_native` setting. [Command Line](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id80) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#command-line "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * The `ansible-galaxy login` command has been removed, as the underlying API it used for GitHub auth has been shut down. Publishing roles or collections to Galaxy with `ansible-galaxy` now requires that a Galaxy API token be passed to the CLI using a token file (default location `~/.ansible/galaxy_token`) or (insecurely) with the `--token` argument to `ansible-galaxy`. [Deprecated](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id81) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#deprecated "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ The constant `ansible.module_utils.basic._CHECK_ARGUMENT_TYPES_DISPATCHER` is deprecated. Use [`ansible.module_utils.common.parameters.DEFAULT_TYPE_VALIDATORS`](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.parameters.DEFAULT_TYPE_VALIDATORS "ansible.module_utils.common.parameters.DEFAULT_TYPE_VALIDATORS") instead. [Breaking Changes](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id82) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#breaking-changes "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ ### [Changes to `AnsibleModule`](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id83) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#changes-to-ansiblemodule "Link to this heading") With the move to [`ArgumentSpecValidator`](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.arg_spec.ArgumentSpecValidator "ansible.module_utils.common.arg_spec.ArgumentSpecValidator") for performing argument spec validation, the following private methods in [`AnsibleModule`](https://docs.ansible.com/projects/ansible/2.9/reference_appendices/module_utils.html#ansible.module_utils.basic.AnsibleModule "(in Ansible v2.9)") have been removed: > * `_check_argument_types()` > > * `_check_argument_values()` > > * `_check_arguments()` > > * `_check_mutually_exclusive()` –> [`ansible.module_utils.common.validation.check_mutually_exclusive()`](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_mutually_exclusive "ansible.module_utils.common.validation.check_mutually_exclusive") > > * `_check_required_arguments()` –> [`ansible.module_utils.common.validation.check_required_arguments()`](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_required_arguments "ansible.module_utils.common.validation.check_required_arguments") > > * `_check_required_by()` –> [`ansible.module_utils.common.validation.check_required_by()`](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_required_by "ansible.module_utils.common.validation.check_required_by") > > * `_check_required_if()` –> [`ansible.module_utils.common.validation.check_required_if()`](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_required_if "ansible.module_utils.common.validation.check_required_if") > > * `_check_required_one_of()` –> [`ansible.module_utils.common.validation.check_required_one_of()`](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_required_one_of "ansible.module_utils.common.validation.check_required_one_of") > > * `_check_required_together()` –> [`ansible.module_utils.common.validation.check_required_together()`](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_required_together "ansible.module_utils.common.validation.check_required_together") > > * `_check_type_bits()` –> [`ansible.module_utils.common.validation.check_type_bits()`](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_bits "ansible.module_utils.common.validation.check_type_bits") > > * `_check_type_bool()` –> [`ansible.module_utils.common.validation.check_type_bool()`](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_bool "ansible.module_utils.common.validation.check_type_bool") > > * `_check_type_bytes()` –> [`ansible.module_utils.common.validation.check_type_bytes()`](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_bytes "ansible.module_utils.common.validation.check_type_bytes") > > * `_check_type_dict()` –> [`ansible.module_utils.common.validation.check_type_dict()`](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_dict "ansible.module_utils.common.validation.check_type_dict") > > * `_check_type_float()` –> [`ansible.module_utils.common.validation.check_type_float()`](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_float "ansible.module_utils.common.validation.check_type_float") > > * `_check_type_int()` –> [`ansible.module_utils.common.validation.check_type_int()`](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_int "ansible.module_utils.common.validation.check_type_int") > > * `_check_type_jsonarg()` –> [`ansible.module_utils.common.validation.check_type_jsonarg()`](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_jsonarg "ansible.module_utils.common.validation.check_type_jsonarg") > > * `_check_type_list()` –> [`ansible.module_utils.common.validation.check_type_list()`](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_list "ansible.module_utils.common.validation.check_type_list") > > * `_check_type_path()` –> [`ansible.module_utils.common.validation.check_type_path()`](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_path "ansible.module_utils.common.validation.check_type_path") > > * `_check_type_raw()` –> [`ansible.module_utils.common.validation.check_type_raw()`](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_raw "ansible.module_utils.common.validation.check_type_raw") > > * `_check_type_str()` –> [`ansible.module_utils.common.validation.check_type_str()`](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.validation.check_type_str "ansible.module_utils.common.validation.check_type_str") > > * `_count_terms()` –> [`ansible.module_utils.common.validation.count_terms()`](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.validation.count_terms "ansible.module_utils.common.validation.count_terms") > > * `_get_wanted_type()` > > * `_handle_aliases()` > > * `_handle_no_log_values()` > > * `_handle_options()` > > * `_set_defaults()` > > * `_set_fallbacks()` > Modules or plugins using these private methods should use the public functions in [`ansible.module_utils.common.validation`](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#module-ansible.module_utils.common.validation "ansible.module_utils.common.validation") or [`ArgumentSpecValidator.validate()`](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.arg_spec.ArgumentSpecValidator.validate "ansible.module_utils.common.arg_spec.ArgumentSpecValidator.validate") if no public function was listed above. ### [Changes to](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id84) [`ansible.module_utils.common.parameters`](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#module-ansible.module_utils.common.parameters "ansible.module_utils.common.parameters") [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#changes-to-ansible-module-utils-common-parameters "Link to this heading") The following functions in [`ansible.module_utils.common.parameters`](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#module-ansible.module_utils.common.parameters "ansible.module_utils.common.parameters") are now private and should not be used directly. Use [`ArgumentSpecValidator.validate()`](https://docs.ansible.com/projects/ansible/latest/reference_appendices/module_utils.html#ansible.module_utils.common.arg_spec.ArgumentSpecValidator.validate "ansible.module_utils.common.arg_spec.ArgumentSpecValidator.validate") instead. > * `list_no_log_values` > > * `list_deprecations` > > * `handle_aliases` > [Other](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id85) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#other "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * **Upgrading**: If upgrading from `ansible < 2.10` or from `ansible-base` and using pip, you must `pip uninstall ansible` or `pip uninstall ansible-base` before installing `ansible-core` to avoid conflicts. * Python 3.8 on the controller node is a soft requirement for this release. `ansible-core` 2.11 still works with the same versions of Python that `ansible-base` 2.10 worked with, however 2.11 emits a warning when running on a controller node with a Python version less than 3.8. This warning can be disabled by setting `ANSIBLE_CONTROLLER_PYTHON_WARNING=False` in your environment. `ansible-core` 2.12 will require Python 3.8 or greater. * The configuration system now validates the `choices` field, so any settings that violate it and were ignored in 2.10 cause an error in 2.11. For example, `ANSIBLE_COLLECTIONS_ON_ANSIBLE_VERSION_MISMATCH=0` now causes an error (valid choices are `ignore`, `warn` or `error`). * The `ansible-galaxy` command now uses `resolvelib` for resolving dependencies. In most cases this should not make a user-facing difference beyond being more performant, but we note it here for posterity and completeness. * If you import Python `module_utils` into any modules you maintain, you may now mark the import as optional during the module payload build by wrapping the `import` statement in a `try` or `if` block. This allows modules to use `module_utils` that may not be present in all versions of Ansible or a collection, and to perform arbitrary recovery or fallback actions during module runtime. [Modules](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id86) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#modules "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ * The `apt_key` module has explicitly defined `file` as mutually exclusive with `data`, `keyserver` and `url`. They cannot be used together anymore. * The `meta` module now supports tags for user-defined tasks. Set the task’s tags to ‘always’ to maintain the previous behavior. Internal `meta` tasks continue to always run. ### [Modules removed](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id87) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#modules-removed "Link to this heading") The following modules no longer exist: * No notable changes ### [Deprecation notices](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id88) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#deprecation-notices "Link to this heading") No notable changes ### [Noteworthy module changes](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id89) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#noteworthy-module-changes "Link to this heading") * facts - On NetBSD, `ansible_virtualization_type` now tries to report a more accurate result than `xen` when virtualized and not running on Xen. * facts - Virtualization facts now include `virtualization_tech_guest` and `virtualization_tech_host` keys. These are lists of virtualization technologies that a guest is a part of, or that a host provides, respectively. As an example, if you set up a host to provide both KVM and VirtualBox, both values are included in `virtualization_tech_host`. Similarly, a podman container running on a VM powered by KVM has a `virtualization_tech_guest` of `["kvm", "podman", "container"]`. * The parameter `filter` type is changed from `string` to `list` in the [setup](https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/setup_module.html#setup-module) module in order to use more than one filter. Previous behavior (using a `string`) still remains and works as a single filter. [Plugins](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id90) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#plugins "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ * inventory plugins - `CachePluginAdjudicator.flush()` now calls the underlying cache plugin’s `flush()` instead of only deleting keys that it knows about. Inventory plugins should use `delete()` to remove any specific keys. As a user, this means that when an inventory plugin calls its `clear_cache()` method, facts could also be flushed from the cache. To work around this, users can configure inventory plugins to use a cache backend that is independent of the facts cache. * callback plugins - `meta` task execution is now sent to `v2_playbook_on_task_start` like any other task. By default, only explicit meta tasks are sent there. Callback plugins can opt-in to receiving internal, implicitly created tasks to act on those as well, as noted in the plugin development documentation. * The `choices` are now validated, so plugins that were using incorrect or incomplete choices issue an error in 2.11 if the value provided does not match. This has a simple fix: update the entries in `choices` to match reality. [Porting custom scripts](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id91) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#porting-custom-scripts "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ No notable changes [Porting Guide for v4.10.0](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id92) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#porting-guide-for-v4-10-0 "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ ### [Major Changes](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id93) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#major-changes "Link to this heading") #### containers.podman[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#containers-podman "Link to this heading") * Add podman\_tag module * Add secrets driver and driver opts support ### [Deprecated Features](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id94) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#deprecated-features "Link to this heading") #### cisco.nxos[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#cisco-nxos "Link to this heading") * Deprecated nxos\_snmp\_community module. * Deprecated nxos\_snmp\_contact module. * Deprecated nxos\_snmp\_host module. * Deprecated nxos\_snmp\_location module. * Deprecated nxos\_snmp\_traps module. * Deprecated nxos\_snmp\_user module. #### junipernetworks.junos[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#junipernetworks-junos "Link to this heading") * ‘router\_id’ options is deprecated from junos\_ospf\_interfaces, junos\_ospfv2 and junos\_ospfv3 resource module. [Porting Guide for v4.9.0](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id95) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#porting-guide-for-v4-9-0 "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [Known Issues](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id96) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#known-issues "Link to this heading") #### purestorage.flashblade[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#purestorage-flashblade "Link to this heading") * purefb\_lag - The mac\_address field in the response is not populated. This will be fixed in a future FlashBlade update. ### [Major Changes](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id97) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id1 "Link to this heading") #### fortinet.fortios[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#fortinet-fortios "Link to this heading") * Add real-world use cases in the example section for some configuration modules. * Collect the current configurations of the modules and convert them into playbooks. * Support FortiOS 7.0.1. * Support member operation (delete/add extra members) on an object that has a list of members in it. * Support selectors feature in `fortios_monitor_fact` and `fortios_log_fact`. [Porting Guide for v4.8.0](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id98) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#porting-guide-for-v4-8-0 "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [Breaking Changes](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id99) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id2 "Link to this heading") #### community.zabbix[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#community-zabbix "Link to this heading") * all roles now reference other roles and modules through their fully qualified collection names, which makes Ansible 2.10 minimum supported version for roles (see [issue 477](https://github.com/ansible-collections/community.zabbix/pull/477) ). ### [Deprecated Features](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id100) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id3 "Link to this heading") #### community.azure[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#community-azure "Link to this heading") * All community.azure.azure\_rm\_\_facts modules are deprecated. Use azure.azcollection.azure\_rm\_\_info modules instead ([https://github.com/ansible-collections/community.azure/pull/24](https://github.com/ansible-collections/community.azure/pull/24) ). * All community.azure.azure\_rm\_\_info modules are deprecated. Use azure.azcollection.azure\_rm\_\_info modules instead ([https://github.com/ansible-collections/community.azure/pull/24](https://github.com/ansible-collections/community.azure/pull/24) ). * community.azure.azure\_rm\_managed\_disk and community.azure.azure\_rm\_manageddisk are deprecated. Use azure.azcollection.azure\_rm\_manageddisk instead ([https://github.com/ansible-collections/community.azure/pull/24](https://github.com/ansible-collections/community.azure/pull/24) ). * community.azure.azure\_rm\_virtualmachine\_extension and community.azure.azure\_rm\_virtualmachineextension are deprecated. Use azure.azcollection.azure\_rm\_virtualmachineextension instead ([https://github.com/ansible-collections/community.azure/pull/24](https://github.com/ansible-collections/community.azure/pull/24) ). * community.azure.azure\_rm\_virtualmachine\_scaleset and community.azure.azure\_rm\_virtualmachinescaleset are deprecated. Use azure.azcollection.azure\_rm\_virtualmachinescaleset instead ([https://github.com/ansible-collections/community.azure/pull/24](https://github.com/ansible-collections/community.azure/pull/24) ). #### community.hashi\_vault[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#community-hashi-vault "Link to this heading") * lookup hashi\_vault - the `[lookup_hashi_vault]` section in the `ansible.cfg` file is deprecated and will be removed in collection version `3.0.0`. Instead, the section `[hashi_vault_collection]` can be used, which will apply to all plugins in the collection going forward ([https://github.com/ansible-collections/community.hashi\_vault/pull/144](https://github.com/ansible-collections/community.hashi_vault/pull/144) ). [Porting Guide for v4.7.0](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id101) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#porting-guide-for-v4-7-0 "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [Major Changes](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id102) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id4 "Link to this heading") #### openvswitch.openvswitch[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#openvswitch-openvswitch "Link to this heading") * By mistake we tagged the repo to 2.0.0 and as it wasn’t intended and cannot be reverted we’re releasing 2.0.1 to make the community aware of the major version update. ### [Deprecated Features](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id103) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id5 "Link to this heading") #### cisco.ios[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#cisco-ios "Link to this heading") * Deprecated ios\_ntp modules. #### cisco.nxos[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id6 "Link to this heading") * Deprecated nxos\_ntp, nxos\_ntp\_options, nxos\_ntp\_auth modules. #### community.vmware[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#community-vmware "Link to this heading") * vmware\_guest\_vnc - Sphere 7.0 removed the built-in VNC server ([https://docs.vmware.com/en/VMware-vSphere/7.0/rn/vsphere-esxi-vcenter-server-70-release-notes.html#productsupport](https://docs.vmware.com/en/VMware-vSphere/7.0/rn/vsphere-esxi-vcenter-server-70-release-notes.html#productsupport) ). #### junipernetworks.junos[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id7 "Link to this heading") * Deprecated router\_id from ospfv2 resource module. [Porting Guide for v4.6.0](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id104) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#porting-guide-for-v4-6-0 "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [Major Changes](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id105) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id8 "Link to this heading") #### containers.podman[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id9 "Link to this heading") * Add systemd generation for pods * Generate systemd service files for containers #### gluster.gluster[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#gluster-gluster "Link to this heading") * enable client.ssl,server.ssl before starting the gluster volume ([https://github.com/gluster/gluster-ansible-collection/pull/19](https://github.com/gluster/gluster-ansible-collection/pull/19) ) ### [Deprecated Features](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id106) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id10 "Link to this heading") #### community.grafana[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#community-grafana "Link to this heading") * grafana\_dashboard lookup - Providing a mangled version of the API key is no longer preferred. [Porting Guide for v4.5.0](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id107) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#porting-guide-for-v4-5-0 "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [Major Changes](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id108) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id11 "Link to this heading") #### hetzner.hcloud[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#hetzner-hcloud "Link to this heading") * Introduction of placement groups #### ovirt.ovirt[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#ovirt-ovirt "Link to this heading") * remove\_stale\_lun - Add role for removing stale LUN ([https://bugzilla.redhat.com/1966873](https://bugzilla.redhat.com/1966873) ). ### [Deprecated Features](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id109) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id12 "Link to this heading") #### ansible.netcommon[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#ansible-netcommon "Link to this heading") * network\_cli - The paramiko\_ssh setting `look_for_keys` was set automatically based on the values of the `password` and `private_key_file` options passed to network\_cli. This option can now be set explicitly, and the automatic setting of `look_for_keys` will be removed after 2024-01-01 ([https://github.com/ansible-collections/ansible.netcommon/pull/271](https://github.com/ansible-collections/ansible.netcommon/pull/271) ). #### cisco.ios[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id13 "Link to this heading") * Deprecated ios\_bgp in favor of ios\_bgp\_global and ios\_bgp\_address\_family. * Remove testing with provider for ansible-test integration jobs. This helps prepare us to move to network-ee integration tests. #### junipernetworks.junos[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id14 "Link to this heading") * Deprecated router\_id from ospfv3 resource module. [Porting Guide for v4.4.0](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id110) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#porting-guide-for-v4-4-0 "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [Known Issues](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id111) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id15 "Link to this heading") #### dellemc.openmanage[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#dellemc-openmanage "Link to this heading") * idrac\_user - Issue(192043) Module may error out with the message `unable to perform the import or export operation because there are pending attribute changes or a configuration job is in progress`. Wait for the job to complete and run the task again. ### [Deprecated Features](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id112) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id16 "Link to this heading") #### cisco.iosxr[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#cisco-iosxr "Link to this heading") * The iosxr\_logging module has been deprecated in favor of the new iosxr\_logging\_global resource module and will be removed in a release after ‘2023-08-01’. #### cisco.nxos[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id17 "Link to this heading") * The nxos\_logging module has been deprecated in favor of the new nxos\_logging\_global resource module and will be removed in a release after ‘2023-08-01’. #### community.docker[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#community-docker "Link to this heading") * docker\_container - the new `command_handling`’s default value, `compatibility`, is deprecated and will change to `correct` in community.docker 3.0.0. A deprecation warning is emitted by the module in cases where the behavior will change. Please note that ansible-core will output a deprecation warning only once, so if it is shown for an earlier task, there could be more tasks with this warning where it is not shown ([https://github.com/ansible-collections/community.docker/pull/186](https://github.com/ansible-collections/community.docker/pull/186) ). #### junipernetworks.junos[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id18 "Link to this heading") * The junos\_logging module has been deprecated in favor of the new junos\_logging\_global resource module and will be removed in a release after ‘2023-08-01’. #### vyos.vyos[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#vyos-vyos "Link to this heading") * The vyos\_logging module has been deprecated in favor of the new vyos\_logging\_global resource module and will be removed in a release after “2023-08-01”. [Porting Guide for v4.3.0](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id113) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#porting-guide-for-v4-3-0 "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [Major Changes](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id114) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id19 "Link to this heading") #### netapp.cloudmanager[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#netapp-cloudmanager "Link to this heading") * Adding stage environment to all modules in cloudmanager ### [Deprecated Features](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id115) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id20 "Link to this heading") #### community.hashi\_vault[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id21 "Link to this heading") * hashi\_vault collection - support for Python 3.5 will be dropped in version `2.0.0` of `community.hashi_vault` ([https://github.com/ansible-collections/community.hashi\_vault/issues/81](https://github.com/ansible-collections/community.hashi_vault/issues/81) ). [Porting Guide for v4.2.0](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id116) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#porting-guide-for-v4-2-0 "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [Known Issues](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id117) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id22 "Link to this heading") #### dellemc.openmanage[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id23 "Link to this heading") * idrac\_user - Issue(192043) Module may error out with the message `unable to perform the import or export operation because there are pending attribute changes or a configuration job is in progress`. Wait for the job to complete and run the task again. * ome\_smart\_fabric\_uplink - Issue(186024) ome\_smart\_fabric\_uplink module does not allow the creation of multiple uplinks of the same name even though this is supported by OpenManage Enterprise Modular. If an uplink is created using the same name as an existing uplink, the existing uplink is modified. ### [Major Changes](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id118) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id24 "Link to this heading") #### community.vmware[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id25 "Link to this heading") * vmware\_object\_custom\_attributes\_info - added a new module to gather custom attributes of an object ([https://github.com/ansible-collections/community.vmware/pull/851](https://github.com/ansible-collections/community.vmware/pull/851) ). #### dellemc.openmanage[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id26 "Link to this heading") * idrac\_server\_config\_profile - Added support for exporting and importing Server Configuration Profile through HTTP/HTTPS share. * ome\_device\_group - Added support for adding devices to a group using the IP addresses of the devices and group ID. #### fortinet.fortios[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id27 "Link to this heading") * New module fortios\_monitor\_fact. * Support Fortios 7.0. * Support Log APIs. ### [Deprecated Features](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id119) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id28 "Link to this heading") * The community.kubernetes collection is being renamed to kubernetes.core. In Ansible 5, community.kubernetes will be replaced by an empty collection which has deprecated redirects for all the current content to kubernetes.core. If you are using FQCNs starting with `community.kubernetes.`, please update them to `kubernetes.core.` now. Note that kubernetes.core has been included in Ansible since Ansible 3.0.0 ([https://github.com/ansible-community/community-topics/issues/22](https://github.com/ansible-community/community-topics/issues/22) ). #### ansible.windows[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#ansible-windows "Link to this heading") * win\_updates - Deprecated the `filtered_reason` return value for each filtered up in favour of `filtered_reasons`. This has been done to show all the reasons why an update was filtered and not just the first reason. * win\_updates - Deprecated the `use_scheduled_task` option as it is no longer used. * win\_updates - Deprecated the `whitelist` and `blacklist` options in favour of `accept_list` and `reject_list` respectively to conform to the new standards used in Ansible for these types of options. #### community.general[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#community-general "Link to this heading") * ali\_instance\_info - marked removal version of deprecated parameters `availability_zone` and `instance_names` ([https://github.com/ansible-collections/community.general/issues/2429](https://github.com/ansible-collections/community.general/issues/2429) ). * serverless - deprecating parameter `functions` because it was not used in the code ([https://github.com/ansible-collections/community.general/pull/2845](https://github.com/ansible-collections/community.general/pull/2845) ). #### community.hashi\_vault[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id29 "Link to this heading") * hashi\_vault collection - support for Python 2 will be dropped in version `2.0.0` of `community.hashi_vault` ([https://github.com/ansible-collections/community.hashi\_vault/issues/81](https://github.com/ansible-collections/community.hashi_vault/issues/81) ). [Porting Guide for v4.1.0](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id120) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#porting-guide-for-v4-1-0 "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [Known Issues](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id121) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id30 "Link to this heading") #### dellemc.openmanage[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id31 "Link to this heading") * idrac\_user - Issue(192043) Module may error out with the message `unable to perform the import or export operation because there are pending attribute changes or a configuration job is in progress`. Wait for the job to complete and run the task again. * ome\_smart\_fabric\_uplink - Issue(186024) ome\_smart\_fabric\_uplink module does not allow the creation of multiple uplinks of the same name even though this is supported by OpenManage Enterprise Modular. If an uplink is created using the same name as an existing uplink, the existing uplink is modified. ### [Major Changes](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id122) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id32 "Link to this heading") #### cloudscale\_ch.cloud[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#cloudscale-ch-cloud "Link to this heading") * Add custom\_image module #### community.postgresql[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#community-postgresql "Link to this heading") * postgresql\_query - the default value of the `as_single_query` option will be changed to `yes` in community.postgresql 2.0.0 ([https://github.com/ansible-collections/community.postgresql/issues/85](https://github.com/ansible-collections/community.postgresql/issues/85) ). #### dellemc.openmanage[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id33 "Link to this heading") * ome\_firmware\_baseline - Module supports check mode, and allows the modification and deletion of firmware baselines. * ome\_firmware\_catalog - Module supports check mode, and allows the modification and deletion of firmware catalogs. #### fortinet.fortios[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id34 "Link to this heading") * Improve `fortios_configuration_fact` to use multiple selectors concurrently. * Support `check_mode` in all cofigurationAPI-based modules. * Support filtering for fact gathering modules `fortios_configuration_fact` and `fortios_monitor_fact`. * Support moving policy in `firewall_central_snat_map`. * Unify schemas for monitor API. #### netbox.netbox[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#netbox-netbox "Link to this heading") * packages is now a required Python package and gets installed through Ansible 2.10+. ### [Removed Features](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id123) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#removed-features "Link to this heading") #### ansible.windows[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id35 "Link to this heading") * win\_reboot - Removed `shutdown_timeout` and `shutdown_timeout_sec` which has not done anything since Ansible 2.5. ### [Deprecated Features](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id124) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id36 "Link to this heading") #### ansible.windows[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id37 "Link to this heading") * win\_reboot - Unreachable hosts can be ignored with `ignore_errors: True`, this ability will be removed in a future version. Use `ignore_unreachable: True` to ignore unreachable hosts instead. - [https://github.com/ansible-collections/ansible.windows/issues/62](https://github.com/ansible-collections/ansible.windows/issues/62) #### community.docker[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id38 "Link to this heading") * docker\_\* modules and plugins, except `docker_swarm` connection plugin and `docker_compose` and ```docker_stack*` modules - the current default ``localhost``` for `tls_hostname` is deprecated. In community.docker 2.0.0 it will be computed from `docker_host` instead ([https://github.com/ansible-collections/community.docker/pull/134](https://github.com/ansible-collections/community.docker/pull/134) ). #### community.general[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id39 "Link to this heading") * All inventory and vault scripts will be removed from community.general in version 4.0.0. If you are referencing them, please update your references to the new [contrib-scripts GitHub repository](https://github.com/ansible-community/contrib-scripts) so your workflow will not break once community.general 4.0.0 is released ([https://github.com/ansible-collections/community.general/pull/2697](https://github.com/ansible-collections/community.general/pull/2697) ). * The nios, nios\_next\_ip, nios\_next\_network lookup plugins, the nios documentation fragment, and the nios\_host\_record, nios\_ptr\_record, nios\_mx\_record, nios\_fixed\_address, nios\_zone, nios\_member, nios\_a\_record, nios\_aaaa\_record, nios\_network, nios\_dns\_view, nios\_txt\_record, nios\_naptr\_record, nios\_srv\_record, nios\_cname\_record, nios\_nsgroup, and nios\_network\_view module have been deprecated and will be removed from community.general 5.0.0. Please install the [infoblox.nios\_modules](https://galaxy.ansible.com/infoblox/nios_modules) collection instead and use its plugins and modules ([https://github.com/ansible-collections/community.general/pull/2458](https://github.com/ansible-collections/community.general/pull/2458) ). * The vendored copy of `ipaddress` will be removed in community.general 4.0.0. Please switch to `ipaddress` from the Python 3 standard library, or [from pypi](https://pypi.org/project/ipaddress/) , if your code relies on the vendored version of `ipaddress` ([https://github.com/ansible-collections/community.general/pull/2459](https://github.com/ansible-collections/community.general/pull/2459) ). * linode - parameter `backupsenabled` is deprecated and will be removed in community.general 5.0.0 ([https://github.com/ansible-collections/community.general/pull/2410](https://github.com/ansible-collections/community.general/pull/2410) ). * lxd inventory plugin - the plugin will require `ipaddress` installed when used with Python 2 from community.general 4.0.0 on. `ipaddress` is part of the Python 3 standard library, but can be installed for Python 2 from pypi ([https://github.com/ansible-collections/community.general/pull/2459](https://github.com/ansible-collections/community.general/pull/2459) ). * scaleway\_security\_group\_rule - the module will require `ipaddress` installed when used with Python 2 from community.general 4.0.0 on. `ipaddress` is part of the Python 3 standard library, but can be installed for Python 2 from pypi ([https://github.com/ansible-collections/community.general/pull/2459](https://github.com/ansible-collections/community.general/pull/2459) ). #### inspur.sm[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#inspur-sm "Link to this heading") * add\_ad\_group - This feature will be removed in inspur.sm.add\_ad\_group 3.0.0. replaced with inspur.sm.ad\_group. * add\_ldap\_group - This feature will be removed in inspur.sm.add\_ldap\_group 3.0.0. replaced with inspur.sm.ldap\_group. * add\_user - This feature will be removed in inspur.sm.add\_user 3.0.0. replaced with inspur.sm.user. * add\_user\_group - This feature will be removed in inspur.sm.add\_user\_group 3.0.0. replaced with inspur.sm.user\_group. * del\_ad\_group - This feature will be removed in inspur.sm.del\_ad\_group 3.0.0. replaced with inspur.sm.ad\_group. * del\_ldap\_group - This feature will be removed in inspur.sm.del\_ldap\_group 3.0.0. replaced with inspur.sm.ldap\_group. * del\_user - This feature will be removed in inspur.sm.del\_user 3.0.0. replaced with inspur.sm.user. * del\_user\_group - This feature will be removed in inspur.sm.del\_user\_group 3.0.0. replaced with inspur.sm.user\_group. * edit\_ad\_group - This feature will be removed in inspur.sm.edit\_ad\_group 3.0.0. replaced with inspur.sm.ad\_group. * edit\_ldap\_group - This feature will be removed in inspur.sm.edit\_ldap\_group 3.0.0. replaced with inspur.sm.ldap\_group. * edit\_user - This feature will be removed in inspur.sm.edit\_user 3.0.0. replaced with inspur.sm.user. * edit\_user\_group - This feature will be removed in inspur.sm.edit\_user\_group 3.0.0. replaced with inspur.sm.user\_group. [Porting Guide for v4.0.0](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id125) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#porting-guide-for-v4-0-0 "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [Known Issues](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id126) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id40 "Link to this heading") #### Ansible-core[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#ansible-core "Link to this heading") * ansible-test - The `pylint` sanity test no longer correctly detects “bad” variable names for non-constants. See [issue 3701](https://github.com/PyCQA/pylint/issues/3701) for additional details. #### dellemc.openmanage[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id41 "Link to this heading") * idrac\_user - Issue(192043) Module may error out with the message `unable to perform the import or export operation because there are pending attribute changes or a configuration job is in progress`. Wait for the job to complete and run the task again. * ome\_configuration\_compliance\_info - Issue(195592) Module may error out with the message `unable to process the request because an error occurred`. If the issue persists, report it to the system administrator. * ome\_smart\_fabric - Issue(185322) Only three design types are supported by OpenManage Enterprise Modular but the module successfully creates a fabric when the design type is not supported. * ome\_smart\_fabric\_uplink - Issue(186024) ome\_smart\_fabric\_uplink module does not allow the creation of multiple uplinks of the same name even though this is supported by OpenManage Enterprise Modular. If an uplink is created using the same name as an existing uplink, the existing uplink is modified. #### fortinet.fortios[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id42 "Link to this heading") * Modules for monitor API are not versioned yet. ### [Breaking Changes](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id127) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id43 "Link to this heading") #### Ansible-core[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id44 "Link to this heading") * Made SCM collections be reinstalled regardless of `--force` being present. * NetBSD virtualization facts (specifically `ansible_virtualization_type`) now returns a more accurate value by checking the value of the `machdep.hypervisor` `sysctl` key. This change is breaking because in some cases previously, we would erroneously report `xen` even when the target is not running on Xen. This prevents that behavior in most cases. ([https://github.com/ansible/ansible/issues/69352](https://github.com/ansible/ansible/issues/69352) ) * Replaced the in-tree dependency resolver with an external implementation that pip >= 20.3 uses now by default — `resolvelib`. ([https://github.com/ansible/ansible/issues/71784](https://github.com/ansible/ansible/issues/71784) ) * The `meta` module now supports tags for user-defined tasks. Internal `meta` tasks continue to always run. ([https://github.com/ansible/ansible/issues/64558](https://github.com/ansible/ansible/issues/64558) ) * ansible-galaxy login command has been removed (see [issue 71560](https://github.com/ansible/ansible/issues/71560) ) #### ansible.netcommon[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id45 "Link to this heading") * Removed vendored ipaddress package from collection. If you use ansible\_collections.ansible.netcommon.plugins.module\_utils.compat.ipaddress in your collection, you will need to change this to import ipaddress instead. If your content using ipaddress supports Python 2.7, you will additionally need to make sure that the user has the ipaddress package installed. Please refer to [https://docs.ansible.com/ansible/latest/dev\_guide/developing\_modules\_best\_practices.html#importing-and-using-shared-code](https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_best_practices.html#importing-and-using-shared-code) to see how to safely import external packages that may be missing from the user’s system A backport of ipaddress for Python 2.7 is available at [https://pypi.org/project/ipaddress/](https://pypi.org/project/ipaddress/) #### community.docker[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id46 "Link to this heading") * docker\_swarm - if `join_token` is specified, a returned join token with the same value will be replaced by `VALUE_SPECIFIED_IN_NO_LOG_PARAMETER`. Make sure that you do not blindly use the join tokens from the return value of this module when the module is invoked with `join_token` specified! This breaking change appears in a minor release since it is necessary to fix a security issue ([https://github.com/ansible-collections/community.docker/pull/103](https://github.com/ansible-collections/community.docker/pull/103) ). #### community.general[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id47 "Link to this heading") * If you use Ansible 2.9 and these plugins or modules from this collection, community.general 3.0.0 results in errors when trying to use the DellEMC content by FQCN, like `community.general.idrac_firmware`. Since Ansible 2.9 is not able to use redirections, you will have to adjust your playbooks and roles manually to use the new FQCNs (`dellemc.openmanage.idrac_firmware` for the previous example) and to make sure that you have `dellemc.openmanage` installed. If you use ansible-base 2.10 or newer and did not install Ansible 4.0.0, but installed (and/or upgraded) community.general manually, you need to make sure to also install the `dellemc.openmanage` collection if you are using any of these plugins or modules. While ansible-base 2.10 or newer can use the redirects that community.general 3.0.0 adds, the collection they point to (such as dellemc.openmanage) must be installed for them to work. * gitlab\_deploy\_key - if for an already existing key title a different public key was given as parameter nothing happened, now this changed so that the public key is updated to the new value ([https://github.com/ansible-collections/community.general/pull/1661](https://github.com/ansible-collections/community.general/pull/1661) ). * java\_keystore - instead of failing, now overwrites keystore if the alias (name) is changed. This was originally the intended behavior, but did not work due to a logic error. Make sure that your playbooks and roles do not depend on the old behavior of failing instead of overwriting ([https://github.com/ansible-collections/community.general/issues/1671](https://github.com/ansible-collections/community.general/issues/1671) ). * java\_keystore - instead of failing, now overwrites keystore if the passphrase is changed. Make sure that your playbooks and roles do not depend on the old behavior of failing instead of overwriting ([https://github.com/ansible-collections/community.general/issues/1671](https://github.com/ansible-collections/community.general/issues/1671) ). * one\_image - use pyone instead of python-oca ([https://github.com/ansible-collections/community.general/pull/2032](https://github.com/ansible-collections/community.general/pull/2032) ). * utm\_proxy\_auth\_profile - the `frontend_cookie_secret` return value now contains a placeholder string instead of the module’s `frontend_cookie_secret` parameter ([https://github.com/ansible-collections/community.general/pull/1736](https://github.com/ansible-collections/community.general/pull/1736) ). #### fortinet.fortios[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id48 "Link to this heading") * Generic FortiOS Module - FOS module to issue generic request with Ansible. * Support for FOS Monitor API - several modules are new for monitor API. * Unified Collection - The fortios collection itself will be adapting any FOS platforms. #### servicenow.servicenow[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#servicenow-servicenow "Link to this heading") * auth field now required for anything other than Basic authentication #### theforeman.foreman[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#theforeman-foreman "Link to this heading") * All role variables are now prefixed with `foreman_` to avoid clashes with similarly named variables from roles outside this collection. ### [Major Changes](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id128) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id49 "Link to this heading") #### Ansible-core[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id50 "Link to this heading") * A collection can be reinstalled with new version requirements without using the `--force` flag. The collection’s dependencies will also be updated if necessary with the new requirements. Use `--upgrade` to force transitive dependency updates. * AnsibleModule - use `ArgumentSpecValidator` class for validating argument spec and remove private methods related to argument spec validation. Any modules using private methods should now use the `ArgumentSpecValidator` class or the appropriate validation function. * Declared `resolvelib >= 0.5.3, < 0.6.0` a direct dependency of ansible-core. Refs: - [https://github.com/sarugaku/resolvelib](https://github.com/sarugaku/resolvelib) - [https://pypi.org/p/resolvelib](https://pypi.org/p/resolvelib) - [https://pradyunsg.me/blog/2020/03/27/pip-resolver-testing](https://pradyunsg.me/blog/2020/03/27/pip-resolver-testing) * It became possible to install Ansible Collections from local folders and namespaces folder similar to SCM structure with multiple collections. * It became possible to upgrade Ansible collections from Galaxy servers using the `--upgrade` option with `ansible-galaxy collection install`. * Support for role argument specification validation at role execution time. When a role contains an argument spec, an implicit validation task is inserted at the start of role execution. * add `ArgumentSpecValidator` class for validating parameters against an argument spec outside of `AnsibleModule` ([https://github.com/ansible/ansible/pull/73335](https://github.com/ansible/ansible/pull/73335) ) * ansible-test - Tests run with the `centos6` and `default` test containers now use a PyPI proxy container to access PyPI when Python 2.6 is used. This allows tests running under Python 2.6 to continue functioning even though PyPI is discontinuing support for non-SNI capable clients. #### ansible.netcommon[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id51 "Link to this heading") * Remove deprecated connection arguments from netconf\_config #### arista.eos[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#arista-eos "Link to this heading") * Requires ansible.netcommon v2.0.0+ to support ansible\_network\_single\_user\_mode and ansible\_network\_import\_modules - Please refer to ansible.netcommon [changelog](https://github.com/ansible-collections/ansible.netcommon/blob/main/changelogs/CHANGELOG.rst#ansible-netcommon-collection-release-notes) for more details. #### cisco.asa[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#cisco-asa "Link to this heading") * Please refer to ansible.netcommon changelog for more details. * Requires ansible.netcommon v2.0.0+ to support ansible\_network\_single\_user\_mode and ansible\_network\_import\_modules. #### cisco.ios[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id52 "Link to this heading") * Please refer to ansible.netcommon [changelog](https://github.com/ansible-collections/ansible.netcommon/blob/main/changelogs/CHANGELOG.rst#ansible-netcommon-collection-release-notes) for more details. * Requires ansible.netcommon v2.0.0+ to support ansible\_network\_single\_user\_mode and ansible\_network\_import\_modules. #### cisco.iosxr[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id54 "Link to this heading") * Please refer to ansible.netcommon [changelog](https://github.com/ansible-collections/ansible.netcommon/blob/main/changelogs/CHANGELOG.rst#ansible-netcommon-collection-release-notes) for more details. * Requires ansible.netcommon v2.0.0+ to support ansible\_network\_single\_user\_mode and ansible\_network\_import\_modules. * ipaddress is no longer in ansible.netcommon. For Python versions without ipaddress (< 3.0), the ipaddress package is now required. #### cisco.nxos[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id56 "Link to this heading") * Please refer to ansible.netcommon [changelog](https://github.com/ansible-collections/ansible.netcommon/blob/main/changelogs/CHANGELOG.rst#ansible-netcommon-collection-release-notes) for more details. * Requires ansible.netcommon v2.0.0+ to support ansible\_network\_single\_user\_mode and ansible\_network\_import\_modules. #### community.grafana[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id58 "Link to this heading") * introduce “skip\_version\_check” parameter in grafana\_teams and grafana\_folder modules (#147) #### community.mysql[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#community-mysql "Link to this heading") * mysql\_replication - add deprecation warning that the `Is_Slave` and `Is_Master` return values will be replaced with `Is_Primary` and `Is_Replica` in `community.mysql` 3.0.0 ([https://github.com/ansible-collections/community.mysql/pull/147](https://github.com/ansible-collections/community.mysql/pull/147) ). * mysql\_replication - the choices of the `state` option containing `master` will be finally replaced with the alternative `primary` choices in `community.mysql` 3.0.0, add deprecation warnings ([https://github.com/ansible-collections/community.mysql/pull/150](https://github.com/ansible-collections/community.mysql/pull/150) ). * mysql\_replication - the mode options values `getslave`, `startslave`, `stopslave`, `resetslave`, ```resetslaveall` and the master_use_gtid option ``slave_pos``` are deprecated (see the alternative values) and will be removed in `community.mysql` 3.0.0 ([https://github.com/ansible-collections/community.mysql/pull/97](https://github.com/ansible-collections/community.mysql/pull/97) ). * mysql\_replication - the return value `Is_Slave` and `Is_Master` will be replaced with `Is_Replica` and `Is_Primary` in `community.mysql` 3.0.0 ([https://github.com/ansible-collections/community.mysql/issues/145](https://github.com/ansible-collections/community.mysql/issues/145) ). * mysql\_replication - the word `SLAVE` in messages returned by the module will be changed to `REPLICA` in `community.mysql` 2.0.0 ([https://github.com/ansible-collections/community.mysql/issues/98](https://github.com/ansible-collections/community.mysql/issues/98) ). * mysql\_replication - the word `master` in messages returned by the module will be replaced with `primary` in `community.mysql` 3.0.0 ([https://github.com/ansible-collections/community.mysql/issues/145](https://github.com/ansible-collections/community.mysql/issues/145) ). * mysql\_replication - the word `slave` in messages returned by the module replaced with `replica` ([https://github.com/ansible-collections/community.mysql/issues/98](https://github.com/ansible-collections/community.mysql/issues/98) ). * mysql\_user - the `REQUIRESSL` is an alias for the `ssl` key in the `tls_requires` option in `community.mysql` 2.0.0 and support will be dropped altogether in `community.mysql` 3.0.0 ([https://github.com/ansible-collections/community.mysql/issues/121](https://github.com/ansible-collections/community.mysql/issues/121) ). #### fortinet.fortios[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id59 "Link to this heading") * New module fortios\_configuration\_fact * New module fortios\_json\_generic * New module fortios\_monitor * New module fortios\_monitor\_fact #### junipernetworks.junos[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id60 "Link to this heading") * Please refer to ansible.netcommon [changelog](https://github.com/ansible-collections/ansible.netcommon/blob/main/changelogs/CHANGELOG.rst#ansible-netcommon-collection-release-notes) for more details. * Requires ansible.netcommon v2.0.0+ to support ansible\_network\_single\_user\_mode and ansible\_network\_import\_modules. #### netapp.ontap[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#netapp-ontap "Link to this heading") * na\_ontap\_autosupport - Added REST support to the module. #### openvswitch.openvswitch[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id62 "Link to this heading") * There is no major changes for this particular release and it was tagged by mistake and cannot be reverted. #### servicenow.servicenow[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id63 "Link to this heading") * refactored client to inherit from AnsibleModule * supports OpenID Connect authentication protocol * supports bearer tokens for authentication #### vyos.vyos[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id64 "Link to this heading") * Please refer to ansible.netcommon [changelog](https://github.com/ansible-collections/ansible.netcommon/blob/main/changelogs/CHANGELOG.rst#ansible-netcommon-collection-release-notes) for more details. * Requires ansible.netcommon v2.0.0+ to support ansible\_network\_single\_user\_mode and ansible\_network\_import\_modules * ipaddress is no longer in ansible.netcommon. For Python versions without ipaddress (< 3.0), the ipaddress package is now required. ### [Removed Features](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id129) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id66 "Link to this heading") #### Ansible-core[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id67 "Link to this heading") * Removed SharedPluginLoaderObj class from ansible.plugins.strategy. It was deprecated in favor of using the standard plugin loader. * Removed \_get\_item() alias from callback plugin base class which had been deprecated in favor of \_get\_item\_label(). * The “user” parameter was previously deprecated and is now removed in favor of “scope” * The deprecated `ansible.constants.BECOME_METHODS` has been removed. * The deprecated `ansible.constants.get_config()` has been removed. * The deprecated `ansible.constants.mk_boolean()` has been removed. * with\_\* loops are no longer optimized for modules whose name parameters can take lists (mostly package managers). Use name instead of looping over individual names with with\_items and friends. #### community.general[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id68 "Link to this heading") * The `ome_device_info`, `idrac_firmware` and `idrac_server_config_profile` modules have now been migrated from community.general to the [dellemc.openmanage](https://galaxy.ansible.com/dellemc/openmanage) Ansible collection. If you use ansible-base 2.10 or newer, redirections have been provided. If you use Ansible 2.9 and installed this collection, you need to adjust the FQCNs (`community.general.idrac_firmware` → `dellemc.openmanage.idrac_firmware`) and make sure to install the dellemc.openmanage collection. * The deprecated ali\_instance\_facts module has been removed. Use ali\_instance\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated gluster\_heal\_info module has been removed. Use gluster.gluster.gluster\_heal\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated gluster\_peer module has been removed. Use gluster.gluster.gluster\_peer instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated gluster\_volume module has been removed. Use gluster.gluster.gluster\_volume instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated helm module has been removed. Use community.kubernetes.helm instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated hpilo\_facts module has been removed. Use hpilo\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated idrac\_redfish\_facts module has been removed. Use idrac\_redfish\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated jenkins\_job\_facts module has been removed. Use jenkins\_job\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated ldap\_attr module has been removed. Use ldap\_attrs instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated memset\_memstore\_facts module has been removed. Use memset\_memstore\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated memset\_server\_facts module has been removed. Use memset\_server\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated na\_ontap\_gather\_facts module has been removed. Use netapp.ontap.na\_ontap\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated nginx\_status\_facts module has been removed. Use nginx\_status\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated one\_image\_facts module has been removed. Use one\_image\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated onepassword\_facts module has been removed. Use onepassword\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated oneview\_datacenter\_facts module has been removed. Use oneview\_datacenter\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated oneview\_enclosure\_facts module has been removed. Use oneview\_enclosure\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated oneview\_ethernet\_network\_facts module has been removed. Use oneview\_ethernet\_network\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated oneview\_fc\_network\_facts module has been removed. Use oneview\_fc\_network\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated oneview\_fcoe\_network\_facts module has been removed. Use oneview\_fcoe\_network\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated oneview\_logical\_interconnect\_group\_facts module has been removed. Use oneview\_logical\_interconnect\_group\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated oneview\_network\_set\_facts module has been removed. Use oneview\_network\_set\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated oneview\_san\_manager\_facts module has been removed. Use oneview\_san\_manager\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated online\_server\_facts module has been removed. Use online\_server\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated online\_user\_facts module has been removed. Use online\_user\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated ovirt module has been removed. Use ovirt.ovirt.ovirt\_vm instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated ovirt\_affinity\_label\_facts module has been removed. Use ovirt.ovirt.ovirt\_affinity\_label\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated ovirt\_api\_facts module has been removed. Use ovirt.ovirt.ovirt\_api\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated ovirt\_cluster\_facts module has been removed. Use ovirt.ovirt.ovirt\_cluster\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated ovirt\_datacenter\_facts module has been removed. Use ovirt.ovirt.ovirt\_datacenter\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated ovirt\_disk\_facts module has been removed. Use ovirt.ovirt.ovirt\_disk\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated ovirt\_event\_facts module has been removed. Use ovirt.ovirt.ovirt\_event\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated ovirt\_external\_provider\_facts module has been removed. Use ovirt.ovirt.ovirt\_external\_provider\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated ovirt\_group\_facts module has been removed. Use ovirt.ovirt.ovirt\_group\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated ovirt\_host\_facts module has been removed. Use ovirt.ovirt.ovirt\_host\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated ovirt\_host\_storage\_facts module has been removed. Use ovirt.ovirt.ovirt\_host\_storage\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated ovirt\_network\_facts module has been removed. Use ovirt.ovirt.ovirt\_network\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated ovirt\_nic\_facts module has been removed. Use ovirt.ovirt.ovirt\_nic\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated ovirt\_permission\_facts module has been removed. Use ovirt.ovirt.ovirt\_permission\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated ovirt\_quota\_facts module has been removed. Use ovirt.ovirt.ovirt\_quota\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated ovirt\_scheduling\_policy\_facts module has been removed. Use ovirt.ovirt.ovirt\_scheduling\_policy\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated ovirt\_snapshot\_facts module has been removed. Use ovirt.ovirt.ovirt\_snapshot\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated ovirt\_storage\_domain\_facts module has been removed. Use ovirt.ovirt.ovirt\_storage\_domain\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated ovirt\_storage\_template\_facts module has been removed. Use ovirt.ovirt.ovirt\_storage\_template\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated ovirt\_storage\_vm\_facts module has been removed. Use ovirt.ovirt.ovirt\_storage\_vm\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated ovirt\_tag\_facts module has been removed. Use ovirt.ovirt.ovirt\_tag\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated ovirt\_template\_facts module has been removed. Use ovirt.ovirt.ovirt\_template\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated ovirt\_user\_facts module has been removed. Use ovirt.ovirt.ovirt\_user\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated ovirt\_vm\_facts module has been removed. Use ovirt.ovirt.ovirt\_vm\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated ovirt\_vmpool\_facts module has been removed. Use ovirt.ovirt.ovirt\_vmpool\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated purefa\_facts module has been removed. Use purestorage.flasharray.purefa\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated purefb\_facts module has been removed. Use purestorage.flasharray.purefb\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated python\_requirements\_facts module has been removed. Use python\_requirements\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated redfish\_facts module has been removed. Use redfish\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated scaleway\_image\_facts module has been removed. Use scaleway\_image\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated scaleway\_ip\_facts module has been removed. Use scaleway\_ip\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated scaleway\_organization\_facts module has been removed. Use scaleway\_organization\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated scaleway\_security\_group\_facts module has been removed. Use scaleway\_security\_group\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated scaleway\_server\_facts module has been removed. Use scaleway\_server\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated scaleway\_snapshot\_facts module has been removed. Use scaleway\_snapshot\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated scaleway\_volume\_facts module has been removed. Use scaleway\_volume\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated smartos\_image\_facts module has been removed. Use smartos\_image\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated vertica\_facts module has been removed. Use vertica\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The deprecated xenserver\_guest\_facts module has been removed. Use xenserver\_guest\_info instead ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * The ovirt\_facts docs fragment has been removed ([https://github.com/ansible-collections/community.general/pull/1924](https://github.com/ansible-collections/community.general/pull/1924) ). * airbrake\_deployment - removed deprecated `token` parameter. Use `project_id` and `project_key` instead ([https://github.com/ansible-collections/community.general/pull/1926](https://github.com/ansible-collections/community.general/pull/1926) ). * bigpanda - the alias `message` has been removed. Use `deployment_message` instead ([https://github.com/ansible-collections/community.general/pull/1926](https://github.com/ansible-collections/community.general/pull/1926) ). * cisco\_spark, cisco\_webex - the alias `message` has been removed. Use `msg` instead ([https://github.com/ansible-collections/community.general/pull/1926](https://github.com/ansible-collections/community.general/pull/1926) ). * clc\_aa\_policy - the `wait` parameter has been removed. It did not have any effect ([https://github.com/ansible-collections/community.general/pull/1926](https://github.com/ansible-collections/community.general/pull/1926) ). * datadog\_monitor - the alias `message` has been removed. Use `notification_message` instead ([https://github.com/ansible-collections/community.general/pull/1926](https://github.com/ansible-collections/community.general/pull/1926) ). * django\_manage - the parameter `liveserver` has been removed ([https://github.com/ansible-collections/community.general/pull/1926](https://github.com/ansible-collections/community.general/pull/1926) ). * idrac\_redfish\_config - the parameters `manager_attribute_name` and `manager_attribute_value` have been removed. Use `manager_attributes` instead ([https://github.com/ansible-collections/community.general/pull/1926](https://github.com/ansible-collections/community.general/pull/1926) ). * iso\_extract - the alias `thirsty` has been removed. Use `force` instead ([https://github.com/ansible-collections/community.general/pull/1926](https://github.com/ansible-collections/community.general/pull/1926) ). * ldap\_entry - the `params` parameter is now completely removed. Using it already triggered an error since community.general 0.1.2 ([https://github.com/ansible-collections/community.general/pull/2257](https://github.com/ansible-collections/community.general/pull/2257) ). * pulp\_repo - the `feed_client_cert` parameter no longer defaults to the value of the `client_cert` parameter ([https://github.com/ansible-collections/community.general/pull/1926](https://github.com/ansible-collections/community.general/pull/1926) ). * pulp\_repo - the `feed_client_key` parameter no longer defaults to the value of the `client_key` parameter ([https://github.com/ansible-collections/community.general/pull/1926](https://github.com/ansible-collections/community.general/pull/1926) ). * pulp\_repo - the alias `ca_cert` has been removed. Use `feed_ca_cert` instead ([https://github.com/ansible-collections/community.general/pull/1926](https://github.com/ansible-collections/community.general/pull/1926) ). * rax - unused parameter `service` removed ([https://github.com/ansible-collections/community.general/pull/2020](https://github.com/ansible-collections/community.general/pull/2020) ). * redfish modules - issuing a data modification command without specifying the ID of the target System, Chassis or Manager resource when there is more than one is no longer allowed. Use the `resource_id` option to specify the target ID ([https://github.com/ansible-collections/community.general/pull/1926](https://github.com/ansible-collections/community.general/pull/1926) ). * redfish\_config - the parameters `bios_attribute_name` and `bios_attribute_value` have been removed. Use `bios_attributes` instead ([https://github.com/ansible-collections/community.general/pull/1926](https://github.com/ansible-collections/community.general/pull/1926) ). * syspatch - the `apply` parameter has been removed. This is the default mode, so simply removing it will not change the behavior ([https://github.com/ansible-collections/community.general/pull/1926](https://github.com/ansible-collections/community.general/pull/1926) ). * xbps - the `force` parameter has been removed. It did not have any effect ([https://github.com/ansible-collections/community.general/pull/1926](https://github.com/ansible-collections/community.general/pull/1926) ). #### community.network[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#community-network "Link to this heading") * The deprecated `community.network.ce_sflow` parameters: `rate_limit`, `rate_limit_slot`, and `forward_enp_slot` have been removed ([https://github.com/ansible-collections/community.network/pull/255](https://github.com/ansible-collections/community.network/pull/255) ). * The deprecated `community.network.sros` netconf plugin has been removed. Use `nokia.sros.md` instead ([https://github.com/ansible-collections/community.network/pull/255](https://github.com/ansible-collections/community.network/pull/255) ). #### f5networks.f5\_modules[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#f5networks-f5-modules "Link to this heading") * Removed TMOS v11 support for bigip\_gtm\_pool and bigip\_gtm\_wide\_ip modules * Removed quorum and monitor\_type parameters in bigip\_node module. See porting guides section at [https://clouddocs.f5.com/products/orchestration/ansible/devel/usage/porting-guides.html](https://clouddocs.f5.com/products/orchestration/ansible/devel/usage/porting-guides.html) * Removed syslog\_settings and pool\_settings parameters in bigip\_log\_destination moduke. See porting guides section at [https://clouddocs.f5.com/products/orchestration/ansible/devel/usage/porting-guides.html](https://clouddocs.f5.com/products/orchestration/ansible/devel/usage/porting-guides.html) #### fortinet.fortios[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id70 "Link to this heading") * Removed module fortios\_facts * Removed module fortios\_registration\_forticare * Removed module fortios\_registration\_vdom * Removed module fortios\_system\_config\_backup\_restore * Removed module fortios\_system\_vmlicense ### [Deprecated Features](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id130) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id71 "Link to this heading") #### Ansible-core[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id72 "Link to this heading") * Starting in 2.14, shell and command modules will no longer have the option to warn and suggest modules in lieu of commands. The `warn` parameter to these modules is now deprecated and defaults to `False`. Similarly, the `COMMAND_WARNINGS` configuration option is also deprecated and defaults to `False`. These will be removed and their presence will become an error in 2.14. * apt\_key - the parameter `key` does not have any effect, has been deprecated and will be removed in ansible-core version 2.14 ([https://github.com/ansible/ansible/pull/70319](https://github.com/ansible/ansible/pull/70319) ). * psrp - Set the minimum version of `pypsrp` to `0.4.0`. #### ansible.netcommon[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id73 "Link to this heading") * Deprecate cli\_parse module and textfsm, ttp, xml, json parser plugins as they are moved to ansible.utils collection ([https://github.com/ansible-collections/ansible.netcommon/pull/182](https://github.com/ansible-collections/ansible.netcommon/pull/182) [https://github.com/ansible-collections/ansible.utils/pull/28](https://github.com/ansible-collections/ansible.utils/pull/28) ) #### cisco.nxos[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id74 "Link to this heading") * Deprecated nxos\_bgp\_af in favour of nxos\_bgp\_address\_family resource module. * Deprecated nxos\_bgp\_neighbor\_af in favour of nxos\_bgp\_neighbor\_address\_family resource module. #### cloudscale\_ch.cloud[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id75 "Link to this heading") * The aliases `server_uuids` and `server_uuid` of the servers parameter in the volume module will be removed in version 3.0.0. #### community.aws[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#community-aws "Link to this heading") * ec2\_eip - formally deprecate the `instance_id` alias for `device_id` ([https://github.com/ansible-collections/community.aws/pull/349](https://github.com/ansible-collections/community.aws/pull/349) ). * ec2\_vpc\_endpoint - deprecate the policy\_file option and recommend using policy with a lookup ([https://github.com/ansible-collections/community.aws/pull/366](https://github.com/ansible-collections/community.aws/pull/366) ). * ec2\_vpc\_endpoint\_info - the `query` option has been deprecated and will be removed after 2022-12-01 ([https://github.com/ansible-collections/community.aws/pull/346](https://github.com/ansible-collections/community.aws/pull/346) ). The ec2\_vpc\_endpoint\_info now defaults to listing information about endpoints. The ability to search for information about available services has been moved to the dedicated module `ec2_vpc_endpoint_service_info`. #### community.crypto[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#community-crypto "Link to this heading") * acme module\_utils - the `acme` module\_utils (`ansible_collections.community.crypto.plugins.module_utils.acme`) is deprecated and will be removed in community.crypto 2.0.0. Use the new Python modules in the `acme` package instead (`ansible_collections.community.crypto.plugins.module_utils.acme.xxx`) ([https://github.com/ansible-collections/community.crypto/pull/184](https://github.com/ansible-collections/community.crypto/pull/184) ). * acme\_account\_info - when `retrieve_orders=url_list`, `orders` will no longer be returned in community.crypto 2.0.0. Use `order_uris` instead ([https://github.com/ansible-collections/community.crypto/pull/178](https://github.com/ansible-collections/community.crypto/pull/178) ). #### community.general[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id76 "Link to this heading") * apt\_rpm - deprecated invalid parameter alias `update-cache`, will be removed in 5.0.0 ([https://github.com/ansible-collections/community.general/pull/1927](https://github.com/ansible-collections/community.general/pull/1927) ). * composer - deprecated invalid parameter aliases `working-dir`, `global-command`, `prefer-source`, `prefer-dist`, `no-dev`, `no-scripts`, `no-plugins`, `optimize-autoloader`, `classmap-authoritative`, `apcu-autoloader`, `ignore-platform-reqs`, will be removed in 5.0.0 ([https://github.com/ansible-collections/community.general/pull/1927](https://github.com/ansible-collections/community.general/pull/1927) ). * cpanm - parameter `system_lib` deprecated in favor of using `become` ([https://github.com/ansible-collections/community.general/pull/2218](https://github.com/ansible-collections/community.general/pull/2218) ). * github\_deploy\_key - deprecated invalid parameter alias `2fa_token`, will be removed in 5.0.0 ([https://github.com/ansible-collections/community.general/pull/1927](https://github.com/ansible-collections/community.general/pull/1927) ). * grove - the option `message` will be removed in community.general 4.0.0. Use the new option `message_content` instead ([https://github.com/ansible-collections/community.general/pull/1929](https://github.com/ansible-collections/community.general/pull/1929) ). * homebrew - deprecated invalid parameter alias `update-brew`, will be removed in 5.0.0 ([https://github.com/ansible-collections/community.general/pull/1927](https://github.com/ansible-collections/community.general/pull/1927) ). * homebrew\_cask - deprecated invalid parameter alias `update-brew`, will be removed in 5.0.0 ([https://github.com/ansible-collections/community.general/pull/1927](https://github.com/ansible-collections/community.general/pull/1927) ). * opkg - deprecated invalid parameter alias `update-cache`, will be removed in 5.0.0 ([https://github.com/ansible-collections/community.general/pull/1927](https://github.com/ansible-collections/community.general/pull/1927) ). * pacman - deprecated invalid parameter alias `update-cache`, will be removed in 5.0.0 ([https://github.com/ansible-collections/community.general/pull/1927](https://github.com/ansible-collections/community.general/pull/1927) ). * puppet - deprecated undocumented parameter `show_diff`, will be removed in 7.0.0. ([https://github.com/ansible-collections/community.general/pull/1927](https://github.com/ansible-collections/community.general/pull/1927) ). * runit - unused parameter `dist` marked for deprecation ([https://github.com/ansible-collections/community.general/pull/1830](https://github.com/ansible-collections/community.general/pull/1830) ). * slackpkg - deprecated invalid parameter alias `update-cache`, will be removed in 5.0.0 ([https://github.com/ansible-collections/community.general/pull/1927](https://github.com/ansible-collections/community.general/pull/1927) ). * urpmi - deprecated invalid parameter aliases `update-cache` and `no-recommends`, will be removed in 5.0.0 ([https://github.com/ansible-collections/community.general/pull/1927](https://github.com/ansible-collections/community.general/pull/1927) ). * xbps - deprecated invalid parameter alias `update-cache`, will be removed in 5.0.0 ([https://github.com/ansible-collections/community.general/pull/1927](https://github.com/ansible-collections/community.general/pull/1927) ). * xfconf - returning output as facts is deprecated, this will be removed in community.general 4.0.0. Please register the task output in a variable and use it instead. You can already switch to the new behavior now by using the new `disable_facts` option ([https://github.com/ansible-collections/community.general/pull/1747](https://github.com/ansible-collections/community.general/pull/1747) ). #### community.vmware[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id77 "Link to this heading") * vmware\_vmkernel\_ip\_config - deprecate in favor of vmware\_vmkernel ([https://github.com/ansible-collections/community.vmware/pull/667](https://github.com/ansible-collections/community.vmware/pull/667) ). #### f5networks.f5\_modules[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_4.html#id78 "Link to this heading") * Support for Python versions earlier than 3.5 is being deprecated --- # Ansible 10 Porting Guide — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * [Ansible Porting Guides](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guides.html) * Ansible 10 Porting Guide * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/porting_guides/porting_guide_10.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * [Ansible 10 Porting Guide](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id77) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#ansible-10-porting-guide "Link to this heading") ================================================================================================================================================================================================================================================================== Ansible 10 is based on Ansible-core 2.17. We suggest you read this page along with the [Ansible 10 Changelog](https://github.com/ansible-community/ansible-build-data/blob/main/10/CHANGELOG-v10.md) to understand what updates you may need to make. [Playbook](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id78) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#playbook "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * Conditionals - due to mitigation of security issue CVE-2023-5764 in ansible-core 2.16.1, conditional expressions with embedded template blocks can fail with the message “`Conditional is marked as unsafe, and cannot be evaluated.`” when an embedded template consults data from untrusted sources like module results or vars marked `!unsafe`. Conditionals with embedded templates can be a source of malicious template injection when referencing untrusted data, and can nearly always be rewritten without embedded templates. Playbook task conditional keywords such as `when` and `until` have long displayed warnings discouraging use of embedded templates in conditionals; this warning has been expanded to non-task conditionals as well, such as the `assert` action. \- name: task with a module result (always untrusted by Ansible) shell: echo "hi mom" register: untrusted\_result \# don't do it this way... \# - name: insecure conditional with embedded template consulting untrusted data \# assert: \# that: '"hi mom" is in {{ untrusted\_result.stdout }}' \- name: securely access untrusted values directly as Jinja variables instead assert: that: '"hi mom" is in untrusted\_result.stdout' * `any_errors_fatal` - when a task in a block with a `rescue` section fails on a host, the `rescue` section is executed on all hosts. This occurs because `any_errors_fatal` automatically fails all hosts. [Command Line](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id79) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#command-line "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ * Python 2.7 and Python 3.6 are no longer supported remote versions. Python 3.7+ is now required for target execution. [Deprecated](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id80) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#deprecated "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- No notable changes [Modules](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id81) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#modules "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- No notable changes ### Modules removed[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#modules-removed "Link to this heading") The following modules no longer exist: * No notable changes ### Deprecation notices[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#deprecation-notices "Link to this heading") No notable changes ### Noteworthy module changes[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#noteworthy-module-changes "Link to this heading") No notable changes [Plugins](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id82) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#plugins "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- No notable changes [Porting custom scripts](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id83) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#porting-custom-scripts "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- No notable changes [Networking](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id84) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#networking "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- No notable changes [Porting Guide for v10.7.0](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id85) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#porting-guide-for-v10-7-0 "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Known Issues[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#known-issues "Link to this heading") #### dellemc.openmanage[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#dellemc-openmanage "Link to this heading") * idrac\_diagnostics - Issue(285322) - This module doesn’t support export of diagnostics file to HTTP and HTTPS share via SOCKS proxy. * idrac\_firmware - Issue(279282) - This module does not support firmware update using HTTP, HTTPS, and FTP shares with authentication on iDRAC8. * ome\_smart\_fabric\_uplink - Issue(186024) - The module supported by OpenManage Enterprise Modular, however it does not allow the creation of multiple uplinks of the same name. If an uplink is created using the same name as an existing uplink, then the existing uplink is modified. ### Major Changes[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#major-changes "Link to this heading") * The removal of netapp.storagegrid was cancelled. The collection will not be removed from Ansible 11 ([https://forum.ansible.com/t/2811](https://forum.ansible.com/t/2811) ). Maintenance of the collection has been taken over by another team at NetApp. #### dellemc.openmanage[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id1 "Link to this heading") * omevv\_baseline\_profile - This module allows to manage baseline profile. * omevv\_baseline\_profile\_info - This module allows to retrieve baseline profile information. * omevv\_compliance\_info - This module allows to retrieve firmware compliance reports. ### Deprecated Features[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#deprecated-features "Link to this heading") * The collection `ibm.spectrum_virtualize` was renamed to `ibm.storage_virtualize`. For now both collections are included in Ansible. The collection will be completely removed from Ansible 12. Please update your FQCNs from `ibm.spectrum_virtualize` to `ibm.storage_virtualize`. [Porting Guide for v10.6.0](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id86) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#porting-guide-for-v10-6-0 "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Known Issues[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id2 "Link to this heading") #### dellemc.openmanage[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id3 "Link to this heading") * idrac\_diagnostics - Issue(285322) - This module doesn’t support export of diagnostics file to HTTP and HTTPS share via SOCKS proxy. * idrac\_firmware - Issue(279282) - This module does not support firmware update using HTTP, HTTPS, and FTP shares with authentication on iDRAC8. * ome\_smart\_fabric\_uplink - Issue(186024) - The module supported by OpenManage Enterprise Modular, however it does not allow the creation of multiple uplinks of the same name. If an uplink is created using the same name as an existing uplink, then the existing uplink is modified. ### Major Changes[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id4 "Link to this heading") #### ansible.posix[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#ansible-posix "Link to this heading") * Dropping support for Ansible 2.9, ansible-core 2.15 will be minimum required version for this release #### dellemc.openmanage[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id5 "Link to this heading") * omevv\_firmware\_repository\_profile - This module allows to manage firmware repository profile. * omevv\_firmware\_repository\_profile\_info - This module allows to retrieve firmware repository profile information. * omevv\_vcenter\_info - This module allows to retrieve vCenter information. #### fortinet.fortios[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#fortinet-fortios "Link to this heading") * Improve the logic for SET function to send GET request first then PUT or POST * Mantis * Support new FOS versions 7.6.0. #### grafana.grafana[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#grafana-grafana "Link to this heading") * Adding “distributor” section support to mimir config file by @HamzaKhait in [https://github.com/grafana/grafana-ansible-collection/pull/247](https://github.com/grafana/grafana-ansible-collection/pull/247) * Allow alloy\_user\_groups variable again by @pjezek in [https://github.com/grafana/grafana-ansible-collection/pull/276](https://github.com/grafana/grafana-ansible-collection/pull/276) * Alloy Role Improvements by @voidquark in [https://github.com/grafana/grafana-ansible-collection/pull/281](https://github.com/grafana/grafana-ansible-collection/pull/281) * Bump ansible-lint from 24.6.0 to 24.9.2 by @dependabot in [https://github.com/grafana/grafana-ansible-collection/pull/270](https://github.com/grafana/grafana-ansible-collection/pull/270) * Bump pylint from 3.2.5 to 3.3.1 by @dependabot in [https://github.com/grafana/grafana-ansible-collection/pull/273](https://github.com/grafana/grafana-ansible-collection/pull/273) * Ensure check-mode works for otel collector by @pieterlexis-tomtom in [https://github.com/grafana/grafana-ansible-collection/pull/264](https://github.com/grafana/grafana-ansible-collection/pull/264) * Fix message argument of dashboard task by @Nemental in [https://github.com/grafana/grafana-ansible-collection/pull/256](https://github.com/grafana/grafana-ansible-collection/pull/256) * Update Alloy variables to use the grafana\_alloy\_ namespace so they are unique by @Aethylred in [https://github.com/grafana/grafana-ansible-collection/pull/209](https://github.com/grafana/grafana-ansible-collection/pull/209) * Update README.md by @aioue in [https://github.com/grafana/grafana-ansible-collection/pull/272](https://github.com/grafana/grafana-ansible-collection/pull/272) * Update README.md by @aioue in [https://github.com/grafana/grafana-ansible-collection/pull/275](https://github.com/grafana/grafana-ansible-collection/pull/275) * Update main.yml by @aioue in [https://github.com/grafana/grafana-ansible-collection/pull/274](https://github.com/grafana/grafana-ansible-collection/pull/274) * add grafana\_plugins\_ops to defaults and docs by @weakcamel in [https://github.com/grafana/grafana-ansible-collection/pull/251](https://github.com/grafana/grafana-ansible-collection/pull/251) * add option to populate google\_analytics\_4\_id value by @copolycube in [https://github.com/grafana/grafana-ansible-collection/pull/249](https://github.com/grafana/grafana-ansible-collection/pull/249) * fix ansible-lint warnings on Forbidden implicit octal value “0640” by @copolycube in [https://github.com/grafana/grafana-ansible-collection/pull/279](https://github.com/grafana/grafana-ansible-collection/pull/279) ### Deprecated Features[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id6 "Link to this heading") * The `community.network` collection has been deprecated. It will be removed from Ansible 12 if no one starts maintaining it again before Ansible 12. See [Collections Removal Process for unmaintained collections](https://docs.ansible.com/ansible/devel/community/collection_contributors/collection_package_removal.html#unmaintained-collections) for more details ([https://forum.ansible.com/t/8030](https://forum.ansible.com/t/8030) ). * The google.cloud collection will be removed from Ansible 12 due to violations of the Ansible inclusion requirements. The collection has [unresolved sanity test failures](https://github.com/ansible-collections/google.cloud/issues/613) . See [Collections Removal Process for collections not satisfying the collection requirements](https://docs.ansible.com/ansible/devel/community/collection_contributors/collection_package_removal.html#collections-not-satisfying-the-collection-requirements) for more details, including for how this can be cancelled ([https://forum.ansible.com/t/8609](https://forum.ansible.com/t/8609) ). #### community.network[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#community-network "Link to this heading") * This collection and all content in it is unmaintained and deprecated ([https://forum.ansible.com/t/8030](https://forum.ansible.com/t/8030) ). If you are interested in maintaining parts of the collection, please copy them to your own repository, and tell others about in the Forum discussion. See the [collection creator path](https://docs.ansible.com/ansible/devel/dev_guide/developing_collections_path.html) for details. #### community.vmware[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#community-vmware "Link to this heading") * vmware\_cluster\_dpm - the module has been deprecated and will be removed in community.vmware 6.0.0 ([https://github.com/ansible-collections/community.vmware/pull/2217](https://github.com/ansible-collections/community.vmware/pull/2217) ). * vmware\_cluster\_drs\_recommendations - the module has been deprecated and will be removed in community.vmware 6.0.0 ([https://github.com/ansible-collections/community.vmware/pull/2218](https://github.com/ansible-collections/community.vmware/pull/2218) ). [Porting Guide for v10.5.0](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id87) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#porting-guide-for-v10-5-0 "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Known Issues[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id7 "Link to this heading") #### dellemc.openmanage[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id8 "Link to this heading") * idrac\_diagnostics - Issue(285322) - This module doesn’t support export of diagnostics file to HTTP and HTTPS share via SOCKS proxy. * idrac\_firmware - Issue(279282) - This module does not support firmware update using HTTP, HTTPS, and FTP shares with authentication on iDRAC8. * idrac\_storage\_volume - Issue(290766) - The module will report success instead of showing failure for new virtual creation on the BOSS-N1 controller if a virtual disk is already present on the same controller. * idrac\_support\_assist - Issue(308550) - This module fails when the NFS share path contains sub directory. * ome\_diagnostics - Issue(279193) - Export of SupportAssist collection logs to the share location fails on OME version 4.0.0. * ome\_smart\_fabric\_uplink - Issue(186024) - The module supported by OpenManage Enterprise Modular, however it does not allow the creation of multiple uplinks of the same name. If an uplink is created using the same name as an existing uplink, then the existing uplink is modified. ### Major Changes[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id9 "Link to this heading") #### dellemc.openmanage[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id10 "Link to this heading") * idrac\_secure\_boot - This module allows to Configure attributes, import, or export secure boot certificate, and reset keys. * idrac\_system\_erase - This module allows to Erase system and storage components of the server on iDRAC. ### Deprecated Features[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id11 "Link to this heading") * The `ngine_io.exoscale` collection has been deprecated. It will be removed from Ansible 11 if no one starts maintaining it again before Ansible 11. See [Collections Removal Process for unmaintained collections](https://docs.ansible.com/ansible/devel/community/collection_contributors/collection_package_removal.html#unmaintained-collections) for more details ([https://forum.ansible.com/t/2572](https://forum.ansible.com/t/2572) ). * The collection `t_systems_mms.icinga_director` was renamed to `telekom_mms.icinga_director`. For now both collections are included in Ansible. The content in `t_systems_mms.icinga_director` has been replaced by deprecated redirects in Ansible 9.0.0. The collection will be completely removed from Ansible 11. Please update your FQCNs from `t_systems_mms.icinga_director` to `telekom_mms.icinga_director`. * The sensu.sensu\_go collection will be removed from Ansible 12 due to violations of the Ansible inclusion requirements. The collection has [unresolved sanity test failures](https://github.com/sensu/sensu-go-ansible/issues/362) . See [Collections Removal Process for collections not satisfying the collection requirements](https://docs.ansible.com/ansible/devel/community/collection_contributors/collection_package_removal.html#collections-not-satisfying-the-collection-requirements) for more details, including for how this can be cancelled ([https://forum.ansible.com/t/8380](https://forum.ansible.com/t/8380) ). #### community.general[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#community-general "Link to this heading") * hipchat - the hipchat service has been discontinued and the self-hosted variant has been End of Life since 2020. The module is therefore deprecated and will be removed from community.general 11.0.0 if nobody provides compelling reasons to still keep it ([https://github.com/ansible-collections/community.general/pull/8919](https://github.com/ansible-collections/community.general/pull/8919) ). [Porting Guide for v10.4.0](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id88) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#porting-guide-for-v10-4-0 "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Known Issues[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id12 "Link to this heading") #### dellemc.openmanage[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id13 "Link to this heading") * idrac\_diagnostics - Issue(285322) - This module doesn’t support export of diagnostics file to HTTP and HTTPS share via SOCKS proxy. * idrac\_firmware - Issue(279282) - This module does not support firmware update using HTTP, HTTPS, and FTP shares with authentication on iDRAC8. * idrac\_storage\_volume - Issue(290766) - The module will report success instead of showing failure for new virtual creation on the BOSS-N1 controller if a virtual disk is already present on the same controller. * idrac\_support\_assist - Issue(308550) - This module fails when the NFS share path contains sub directory. * ome\_diagnostics - Issue(279193) - Export of SupportAssist collection logs to the share location fails on OME version 4.0.0. * ome\_smart\_fabric\_uplink - Issue(186024) - The module supported by OpenManage Enterprise Modular, however it does not allow the creation of multiple uplinks of the same name. If an uplink is created using the same name as an existing uplink, then the existing uplink is modified. ### Major Changes[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id14 "Link to this heading") #### dellemc.openmanage[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id15 "Link to this heading") * idrac\_secure\_boot - This module allows to import the secure boot certificate. * idrac\_support\_assist - This module allows to run and export SupportAssist collection logs on iDRAC. #### grafana.grafana[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id16 "Link to this heading") * fix:mimir molecule should use ansible core 2.16 by @GVengelen in https://github.com/grafana/grafana-ansible-collection/pull/254 ### Deprecated Features[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id17 "Link to this heading") #### amazon.aws[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#amazon-aws "Link to this heading") * iam\_role - support for creating and deleting IAM instance profiles using the `create_instance_profile` and `delete_instance_profile` options has been deprecated and will be removed in a release after 2026-05-01. To manage IAM instance profiles the `amazon.aws.iam_instance_profile` module can be used instead ([https://github.com/ansible-collections/amazon.aws/pull/2221](https://github.com/ansible-collections/amazon.aws/pull/2221) ). #### community.general[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id18 "Link to this heading") * MH decorator cause\_changes module utils - deprecate parameters `on_success` and `on_failure` ([https://github.com/ansible-collections/community.general/pull/8791](https://github.com/ansible-collections/community.general/pull/8791) ). * pipx - support for versions of the command line tool `pipx` older than `1.7.0` is deprecated and will be removed in community.general 11.0.0 ([https://github.com/ansible-collections/community.general/pull/8793](https://github.com/ansible-collections/community.general/pull/8793) ). * pipx\_info - support for versions of the command line tool `pipx` older than `1.7.0` is deprecated and will be removed in community.general 11.0.0 ([https://github.com/ansible-collections/community.general/pull/8793](https://github.com/ansible-collections/community.general/pull/8793) ). #### community.mysql[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#community-mysql "Link to this heading") * collection - support of mysqlclient connector is deprecated - use PyMySQL connector instead! We will stop testing against it in collection version 4.0.0 and remove the related code in 5.0.0 ([https://github.com/ansible-collections/community.mysql/issues/654](https://github.com/ansible-collections/community.mysql/issues/654) ). * mysql\_info - The `users_info` filter returned variable `plugin_auth_string` contains the hashed password and it’s misleading, it will be removed from community.mysql 4.0.0. Use the plugin\_hash\_string return value instead ([https://github.com/ansible-collections/community.mysql/pull/629](https://github.com/ansible-collections/community.mysql/pull/629) ). * mysql\_user - the `user` alias of the `name` argument has been deprecated and will be removed in collection version 5.0.0. Use the `name` argument instead. #### community.vmware[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id19 "Link to this heading") * vmware\_cluster - the module has been deprecated and will be removed in community.vmware 6.0.0 ([https://github.com/ansible-collections/community.vmware/pull/2143](https://github.com/ansible-collections/community.vmware/pull/2143) ). * vmware\_cluster\_drs - the module has been deprecated and will be removed in community.vmware 6.0.0 ([https://github.com/ansible-collections/community.vmware/pull/2136](https://github.com/ansible-collections/community.vmware/pull/2136) ). * vmware\_cluster\_vcls - the module has been deprecated and will be removed in community.vmware 6.0.0 ([https://github.com/ansible-collections/community.vmware/pull/2156](https://github.com/ansible-collections/community.vmware/pull/2156) ). [Porting Guide for v10.3.0](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id89) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#porting-guide-for-v10-3-0 "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Known Issues[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id20 "Link to this heading") #### community.docker[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#community-docker "Link to this heading") * docker\_container - when specifying a MAC address for a container’s network, and the network is attached after container creation (for example, due to idempotency checks), the MAC address is at least in some cases ignored by the Docker Daemon ([https://github.com/ansible-collections/community.docker/pull/933](https://github.com/ansible-collections/community.docker/pull/933) ). #### dellemc.openmanage[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id21 "Link to this heading") * idrac\_diagnostics - Issue(285322) - This module doesn’t support export of diagnostics file to HTTP and HTTPS share via SOCKS proxy. * idrac\_firmware - Issue(279282) - This module does not support firmware update using HTTP, HTTPS, and FTP shares with authentication on iDRAC8. * idrac\_storage\_volume - Issue(290766) - The module will report success instead of showing failure for new virtual creation on the BOSS-N1 controller if a virtual disk is already present on the same controller. * ome\_diagnostics - Issue(279193) - Export of SupportAssist collection logs to the share location fails on OME version 4.0.0. * ome\_smart\_fabric\_uplink - Issue(186024) - The module supported by OpenManage Enterprise Modular, however it does not allow the creation of multiple uplinks of the same name. If an uplink is created using the same name as an existing uplink, then the existing uplink is modified. ### Deprecated Features[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id22 "Link to this heading") #### community.docker[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id23 "Link to this heading") * The collection deprecates support for all ansible-core versions that are currently End of Life, [according to the ansible-core support matrix](https://docs.ansible.com/ansible-core/devel/reference_appendices/release_and_maintenance.html#ansible-core-support-matrix) . This means that the next major release of the collection will no longer support ansible-core 2.11, ansible-core 2.12, ansible-core 2.13, and ansible-core 2.14. #### community.routeros[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#community-routeros "Link to this heading") * The collection deprecates support for all Ansible/ansible-base/ansible-core versions that are currently End of Life, [according to the ansible-core support matrix](https://docs.ansible.com/ansible-core/devel/reference_appendices/release_and_maintenance.html#ansible-core-support-matrix) . This means that the next major release of the collection will no longer support Ansible 2.9, ansible-base 2.10, ansible-core 2.11, ansible-core 2.12, ansible-core 2.13, and ansible-core 2.14. #### community.sops[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#community-sops "Link to this heading") * The collection deprecates support for all Ansible/ansible-base/ansible-core versions that are currently End of Life, [according to the ansible-core support matrix](https://docs.ansible.com/ansible-core/devel/reference_appendices/release_and_maintenance.html#ansible-core-support-matrix) . This means that the next major release of the collection will no longer support Ansible 2.9, ansible-base 2.10, ansible-core 2.11, ansible-core 2.12, ansible-core 2.13, and ansible-core 2.14. [Porting Guide for v10.2.0](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id90) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#porting-guide-for-v10-2-0 "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Added Collections[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#added-collections "Link to this heading") * kubevirt.core (version 1.5.0) * vmware.vmware (version 1.3.0) ### Known Issues[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id24 "Link to this heading") #### dellemc.openmanage[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id25 "Link to this heading") * idrac\_diagnostics - Issue(285322) - This module doesn’t support export of diagnostics file to HTTP and HTTPS share via SOCKS proxy. * idrac\_firmware - Issue(279282) - This module does not support firmware update using HTTP, HTTPS, and FTP shares with authentication on iDRAC8. * idrac\_storage\_volume - Issue(290766) - The module will report success instead of showing failure for new virtual creation on the BOSS-N1 controller if a virtual disk is already present on the same controller. * ome\_diagnostics - Issue(279193) - Export of SupportAssist collection logs to the share location fails on OME version 4.0.0. * ome\_smart\_fabric\_uplink - Issue(186024) - The module supported by OpenManage Enterprise Modular, however it does not allow the creation of multiple uplinks of the same name. If an uplink is created using the same name as an existing uplink, then the existing uplink is modified. ### Major Changes[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id26 "Link to this heading") #### dellemc.openmanage[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id27 "Link to this heading") * idrac\_server\_config\_profile - This module is enhanced to allow you to export and import custom defaults on iDRAC. * ome\_configuration\_compliance\_baseline - This module is enhanced to schedule the remediation job and stage the reboot. #### fortinet.fortios[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id28 "Link to this heading") * Add a sanity\_test.yaml file to trigger CI tests in GitHub. * Support Ansible-core 2.17. * Support new FOS versions 7.4.4. #### grafana.grafana[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id29 "Link to this heading") * Add a config check before restarting mimir by @panfantastic in [https://github.com/grafana/grafana-ansible-collection/pull/198](https://github.com/grafana/grafana-ansible-collection/pull/198) * Add support for configuring feature\_toggles in grafana role by @LexVar in [https://github.com/grafana/grafana-ansible-collection/pull/173](https://github.com/grafana/grafana-ansible-collection/pull/173) * Backport post-setup healthcheck from agent to alloy by @v-zhuravlev in [https://github.com/grafana/grafana-ansible-collection/pull/213](https://github.com/grafana/grafana-ansible-collection/pull/213) * Bump ansible-lint from 24.2.3 to 24.5.0 by @dependabot in [https://github.com/grafana/grafana-ansible-collection/pull/207](https://github.com/grafana/grafana-ansible-collection/pull/207) * Bump ansible-lint from 24.5.0 to 24.6.0 by @dependabot in [https://github.com/grafana/grafana-ansible-collection/pull/216](https://github.com/grafana/grafana-ansible-collection/pull/216) * Bump braces from 3.0.2 to 3.0.3 in the npm\_and\_yarn group across 1 directory by @dependabot in [https://github.com/grafana/grafana-ansible-collection/pull/218](https://github.com/grafana/grafana-ansible-collection/pull/218) * Bump pylint from 3.1.0 to 3.1.1 by @dependabot in [https://github.com/grafana/grafana-ansible-collection/pull/200](https://github.com/grafana/grafana-ansible-collection/pull/200) * Bump pylint from 3.1.1 to 3.2.2 by @dependabot in [https://github.com/grafana/grafana-ansible-collection/pull/208](https://github.com/grafana/grafana-ansible-collection/pull/208) * Bump pylint from 3.2.2 to 3.2.3 by @dependabot in [https://github.com/grafana/grafana-ansible-collection/pull/217](https://github.com/grafana/grafana-ansible-collection/pull/217) * Bump pylint from 3.2.3 to 3.2.5 by @dependabot in [https://github.com/grafana/grafana-ansible-collection/pull/234](https://github.com/grafana/grafana-ansible-collection/pull/234) * Change from config.river to config.alloy by @cardasac in [https://github.com/grafana/grafana-ansible-collection/pull/225](https://github.com/grafana/grafana-ansible-collection/pull/225) * Fix Grafana Configuration for Unified and Legacy Alerting Based on Version by @voidquark in [https://github.com/grafana/grafana-ansible-collection/pull/215](https://github.com/grafana/grafana-ansible-collection/pull/215) * Support adding alloy user to extra groups by @v-zhuravlev in [https://github.com/grafana/grafana-ansible-collection/pull/212](https://github.com/grafana/grafana-ansible-collection/pull/212) * Updated result.json\[‘message’\] to result.json()\[‘message’\] by @CPreun in [https://github.com/grafana/grafana-ansible-collection/pull/223](https://github.com/grafana/grafana-ansible-collection/pull/223) ### Deprecated Features[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id30 "Link to this heading") * The `frr.frr` collection has been deprecated. It will be removed from Ansible 11 if no one starts maintaining it again before Ansible 11. See [Collections Removal Process for unmaintained collections](https://docs.ansible.com/ansible/devel/community/collection_contributors/collection_package_removal.html#unmaintained-collections) for more details ([https://forum.ansible.com/t/6243](https://forum.ansible.com/t/6243) ). * The `openvswitch.openvswitch` collection has been deprecated. It will be removed from Ansible 11 if no one starts maintaining it again before Ansible 11. See [Collections Removal Process for unmaintained collections](https://docs.ansible.com/ansible/devel/community/collection_contributors/collection_package_removal.html#unmaintained-collections) for more details ([https://forum.ansible.com/t/6245](https://forum.ansible.com/t/6245) ). [Porting Guide for v10.1.0](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id91) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#porting-guide-for-v10-1-0 "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Added Collections[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id31 "Link to this heading") * ieisystem.inmanage (version 2.0.0) ### Known Issues[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id32 "Link to this heading") #### community.general[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id33 "Link to this heading") * homectl - the module does not work under Python 3.13 or newer, since it relies on the removed `crypt` standard library module ([https://github.com/ansible-collections/community.general/issues/4691](https://github.com/ansible-collections/community.general/issues/4691) , [https://github.com/ansible-collections/community.general/pull/8497](https://github.com/ansible-collections/community.general/pull/8497) ). * udm\_user - the module does not work under Python 3.13 or newer, since it relies on the removed `crypt` standard library module ([https://github.com/ansible-collections/community.general/issues/4690](https://github.com/ansible-collections/community.general/issues/4690) , [https://github.com/ansible-collections/community.general/pull/8497](https://github.com/ansible-collections/community.general/pull/8497) ). #### dellemc.openmanage[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id34 "Link to this heading") * idrac\_diagnostics - Issue(285322) - This module doesn’t support export of diagnostics file to HTTP and HTTPS share via SOCKS proxy. * idrac\_firmware - Issue(279282) - This module does not support firmware update using HTTP, HTTPS, and FTP shares with authentication on iDRAC8. * idrac\_storage\_volume - Issue(290766) - The module will report success instead of showing failure for new virtual creation on the BOSS-N1 controller if a virtual disk is already present on the same controller. * ome\_diagnostics - Issue(279193) - Export of SupportAssist collection logs to the share location fails on OME version 4.0.0. * ome\_smart\_fabric\_uplink - Issue(186024) - The module supported by OpenManage Enterprise Modular, however it does not allow the creation of multiple uplinks of the same name. If an uplink is created using the same name as an existing uplink, then the existing uplink is modified. ### Major Changes[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id35 "Link to this heading") #### containers.podman[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#containers-podman "Link to this heading") * Add mount and unmount for volumes * Add multiple subnets for networks * Add new options for podman\_container * Add new options to pod module * Add podman search * Improve idempotency for networking in podman\_container * Redesign idempotency for Podman Pod module #### dellemc.openmanage[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id36 "Link to this heading") * Added support to use session ID for authentication of iDRAC, OpenManage Enterprise and OpenManage Enterprise Modular. * ome\_session - This module allows you to create and delete the sessions on OpenManage Enterprise and OpenManage Enterprise Modular. ### Deprecated Features[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id37 "Link to this heading") #### community.general[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id38 "Link to this heading") * CmdRunner module util - setting the value of the `ignore_none` parameter within a `CmdRunner` context is deprecated and that feature should be removed in community.general 12.0.0 ([https://github.com/ansible-collections/community.general/pull/8479](https://github.com/ansible-collections/community.general/pull/8479) ). * git\_config - the `list_all` option has been deprecated and will be removed in community.general 11.0.0. Use the `community.general.git_config_info` module instead ([https://github.com/ansible-collections/community.general/pull/8453](https://github.com/ansible-collections/community.general/pull/8453) ). * git\_config - using `state=present` without providing `value` is deprecated and will be disallowed in community.general 11.0.0. Use the `community.general.git_config_info` module instead to read a value ([https://github.com/ansible-collections/community.general/pull/8453](https://github.com/ansible-collections/community.general/pull/8453) ). [Porting Guide for v10.0.0](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id92) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#porting-guide-for-v10-0-0 "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Added Collections[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id39 "Link to this heading") * community.library\_inventory\_filtering\_v1 (version 1.0.1) * kaytus.ksmanage (version 1.2.1) ### Known Issues[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id40 "Link to this heading") #### community.docker[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id41 "Link to this heading") * Please note that the fix for requests 2.32.0 included in community.docker 3.10.1 only fixes problems with the _vendored_ Docker SDK for Python code. Modules and plugins that use Docker SDK for Python can still fail due to the SDK currently being incompatible with requests 2.32.0. If you still experience problems with requests 2.32.0, such as error messages like `Not supported URL scheme http+docker`, please restrict requests to `<2.32.0`. #### dellemc.openmanage[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id42 "Link to this heading") * idrac\_diagnostics - Issue(285322) - This module doesn’t support export of diagnostics file to HTTP and HTTPS share via SOCKS proxy. * idrac\_firmware - Issue(279282) - This module does not support firmware update using HTTP, HTTPS, and FTP shares with authentication on iDRAC8. * idrac\_network\_attributes - Issue(279049) - If unsupported values are provided for the parameter `ome_network_attributes`, then this module does not provide a correct error message. * idrac\_storage\_volume - Issue(290766) - The module will report success instead of showing failure for new virtual creation on the BOSS-N1 controller if a virtual disk is already present on the same controller. * ome\_device\_network\_services - Issue(212681) - The module does not provide a proper error message if unsupported values are provided for the following parameters- port\_number, community\_name, max\_sessions, max\_auth\_retries, and idle\_timeout. * ome\_device\_power\_settings - Issue(212679) - The module displays the following message if the value provided for the parameter `power_cap` is not within the supported range of 0 to 32767, `Unable to complete the request because PowerCap does not exist or is not applicable for the resource URI.` * ome\_device\_quick\_deploy - Issue(275231) - This module does not deploy a new configuration to a slot that has disabled IPv6. * ome\_diagnostics - Issue(279193) - Export of SupportAssist collection logs to the share location fails on OME version 4.0.0. * ome\_smart\_fabric\_uplink - Issue(186024) - The module supported by OpenManage Enterprise Modular, however it does not allow the creation of multiple uplinks of the same name. If an uplink is created using the same name as an existing uplink, then the existing uplink is modified. ### Breaking Changes[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#breaking-changes "Link to this heading") #### Ansible-core[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#ansible-core "Link to this heading") * assert - Nested templating may result in an inability for the conditional to be evaluated. See the porting guide for more information. #### amazon.aws[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id43 "Link to this heading") * amazon.aws collection - Support for ansible-core < 2.15 has been dropped ([https://github.com/ansible-collections/amazon.aws/pull/2093](https://github.com/ansible-collections/amazon.aws/pull/2093) ). * iam\_role - `iam_role.assume_role_policy_document` is no longer converted from CamelCase to snake\_case ([https://github.com/ansible-collections/amazon.aws/pull/2040](https://github.com/ansible-collections/amazon.aws/pull/2040) ). * iam\_role\_info - `iam_role.assume_role_policy_document` is no longer converted from CamelCase to snake\_case ([https://github.com/ansible-collections/amazon.aws/pull/2040](https://github.com/ansible-collections/amazon.aws/pull/2040) ). * kms\_key - the `policies` return value has been renamed to `key_policies` the contents has not been changed ([https://github.com/ansible-collections/amazon.aws/pull/2040](https://github.com/ansible-collections/amazon.aws/pull/2040) ). * kms\_key\_info - the `policies` return value has been renamed to `key_policies` the contents has not been changed ([https://github.com/ansible-collections/amazon.aws/pull/2040](https://github.com/ansible-collections/amazon.aws/pull/2040) ). * lambda\_event - | `batch_size` no longer defaults to 100. According to the boto3 API ([https://boto3.amazonaws.com/v1/documentation/api/1.26.78/reference/services/lambda.html#Lambda.Client.create\_event\_source\_mapping](https://boto3.amazonaws.com/v1/documentation/api/1.26.78/reference/services/lambda.html#Lambda.Client.create_event_source_mapping) ), `batch_size` defaults to 10 for sqs sources and to 100 for stream sources ([https://github.com/ansible-collections/amazon.aws/pull/2025](https://github.com/ansible-collections/amazon.aws/pull/2025) ). #### cloud.common[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#cloud-common "Link to this heading") * Bump minimum Python supported version to 3.9. * Remove support for ansible-core < 2.14. #### community.aws[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#community-aws "Link to this heading") * The community.aws collection has dropped support for `botocore<1.29.0` and `boto3<1.26.0`. Most modules will continue to work with older versions of the AWS SDK, however compatability with older versions of the SDK is not guaranteed and will not be tested. When using older versions of the SDK a warning will be emitted by Ansible ([https://github.com/ansible-collections/amazon.aws/pull/1763](https://github.com/ansible-collections/amazon.aws/pull/1763) ). * aws\_region\_info - The module has been migrated from the `community.aws` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use `amazon.aws.aws_region_info`. * aws\_s3\_bucket\_info - The module has been migrated from the `community.aws` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use `amazon.aws.aws_s3_bucket_info`. * community.aws collection - Support for ansible-core < 2.15 has been dropped ([https://github.com/ansible-collections/community.aws/pull/2074](https://github.com/ansible-collections/community.aws/pull/2074) ). * community.aws collection - due to the AWS SDKs announcing the end of support for Python less than 3.7 ([https://aws.amazon.com/blogs/developer/python-support-policy-updates-for-aws-sdks-and-tools/](https://aws.amazon.com/blogs/developer/python-support-policy-updates-for-aws-sdks-and-tools/) ) support for Python less than 3.7 by this collection wss been deprecated in release 6.0.0 and removed in release 7.0.0. ([https://github.com/ansible-collections/amazon.aws/pull/1763](https://github.com/ansible-collections/amazon.aws/pull/1763) ). * iam\_access\_key - The module has been migrated from the `community.aws` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use `amazon.aws.iam_access_key`. * iam\_access\_key\_info - The module has been migrated from the `community.aws` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use `amazon.aws.iam_access_key_info`. * iam\_group - The module has been migrated from the `community.aws` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use `amazon.aws.iam_group` ([https://github.com/ansible-collections/community.aws/pull/1945](https://github.com/ansible-collections/community.aws/pull/1945) ). * iam\_managed\_policy - The module has been migrated from the `community.aws` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use `amazon.aws.iam_managed_policy` ([https://github.com/ansible-collections/community.aws/pull/1954](https://github.com/ansible-collections/community.aws/pull/1954) ). * iam\_mfa\_device\_info - The module has been migrated from the `community.aws` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use `amazon.aws.iam_mfa_device_info` ([https://github.com/ansible-collections/community.aws/pull/1953](https://github.com/ansible-collections/community.aws/pull/1953) ). * iam\_password\_policy - The module has been migrated from the `community.aws` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use `amazon.aws.iam_password_policy`. * iam\_role - The module has been migrated from the `community.aws` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use `amazon.aws.iam_role` ([https://github.com/ansible-collections/community.aws/pull/1948](https://github.com/ansible-collections/community.aws/pull/1948) ). * iam\_role\_info - The module has been migrated from the `community.aws` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use `amazon.aws.iam_role_info` ([https://github.com/ansible-collections/community.aws/pull/1948](https://github.com/ansible-collections/community.aws/pull/1948) ). * s3\_bucket\_info - The module has been migrated from the `community.aws` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use `amazon.aws.s3_bucket_info`. * sts\_assume\_role - The module has been migrated from the `community.aws` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use `amazon.aws.sts_assume_role`. #### community.ciscosmb[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#community-ciscosmb "Link to this heading") * in facts of interface ‘bandwith’ changed to ‘bandwidth’ #### community.dns[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#community-dns "Link to this heading") * The default for the `txt_character_encoding` options in various modules and plugins changed from `octal` to `decimal` ([https://github.com/ansible-collections/community.dns/pull/196](https://github.com/ansible-collections/community.dns/pull/196) ). * inventory plugins - `filters` is now no longer an alias of `simple_filters`, but a new, different option ([https://github.com/ansible-collections/community.dns/pull/196](https://github.com/ansible-collections/community.dns/pull/196) ). * inventory plugins - the `plugin` option is now required ([https://github.com/ansible-collections/community.dns/pull/196](https://github.com/ansible-collections/community.dns/pull/196) ). * lookup, lookup\_as\_dict - the default for `search` changed from `false` (implicit default for community.dns 2.x.y) to `true` ([https://github.com/ansible-collections/community.dns/issues/200](https://github.com/ansible-collections/community.dns/issues/200) , [https://github.com/ansible-collections/community.dns/pull/201](https://github.com/ansible-collections/community.dns/pull/201) ). #### community.general[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id44 "Link to this heading") * cpanm - the default of the `mode` option changed from `compatibility` to `new` ([https://github.com/ansible-collections/community.general/pull/8198](https://github.com/ansible-collections/community.general/pull/8198) ). * django\_manage - the module now requires Django >= 4.1 ([https://github.com/ansible-collections/community.general/pull/8198](https://github.com/ansible-collections/community.general/pull/8198) ). * django\_manage - the module will now fail if `virtualenv` is specified but no virtual environment exists at that location ([https://github.com/ansible-collections/community.general/pull/8198](https://github.com/ansible-collections/community.general/pull/8198) ). * redfish\_command, redfish\_config, redfish\_info - change the default for `timeout` from 10 to 60 ([https://github.com/ansible-collections/community.general/pull/8198](https://github.com/ansible-collections/community.general/pull/8198) ). #### community.hrobot[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#community-hrobot "Link to this heading") * robot inventory plugin - `filters` is now no longer an alias of `simple_filters`, but a new, different option ([https://github.com/ansible-collections/community.hrobot/pull/101](https://github.com/ansible-collections/community.hrobot/pull/101) ). #### community.okd[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#community-okd "Link to this heading") * Bump minimum Python suupported version to 3.9 ([https://github.com/openshift/community.okd/pull/202](https://github.com/openshift/community.okd/pull/202) ). * Remove support for ansible-core < 2.14 ([https://github.com/openshift/community.okd/pull/202](https://github.com/openshift/community.okd/pull/202) ). #### hetzner.hcloud[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#hetzner-hcloud "Link to this heading") * Drop support for ansible-core 2.13. * certificate - The not\_valid\_before and not\_valid\_after values are now returned as ISO-8601 formatted strings. * certificate\_info - The not\_valid\_before and not\_valid\_after values are now returned as ISO-8601 formatted strings. * inventory - Remove the deprecated api\_token\_env option, you may use the ansible.builtin.env lookup as alternative. * iso\_info - The deprecated value is now returned as ISO-8601 formatted strings. #### kubernetes.core[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#kubernetes-core "Link to this heading") * Remove support for ansible-core < 2.14 * Update python kubernetes library to 24.2.0, helm/kind-action to 1.8.0, kubernetes >= 1.24. #### theforeman.foreman[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#theforeman-foreman "Link to this heading") * content\_view\_filter - stop managing rules from this module, `content_view_filter_rule` should be used for that * inventory plugin - do not default to `http://localhost:3000` as the Foreman URL, providing a URL is now mandatory #### vmware.vmware\_rest[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#vmware-vmware-rest "Link to this heading") * Remove support for ansible-core < 2.14 ### Major Changes[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id45 "Link to this heading") #### Ansible-core[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id46 "Link to this heading") * urls.py - Removed support for Python 2 #### ansible.netcommon[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#ansible-netcommon "Link to this heading") * Bumping requires\_ansible to \>=2.14.0, since previous ansible-core versions are EoL now. #### ansible.utils[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#ansible-utils "Link to this heading") * Bumping netaddr to \>=0.10.1, means that starting from this release, the minimum netaddr version this collection requires is \>=0.10.1. * Bumping requires\_ansible to \>=2.14.0, since previous ansible-core versions are EoL now. * This release mainly addresses the breaking changes in the netaddr library. * With the new release of netaddr 1.0.0, the IPAddress.is\_private() method has been removed and instead, the IPAddress.is\_global() method has been extended to support the same functionality. This change has been reflected in the ipaddr filter plugin. #### arista.eos[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#arista-eos "Link to this heading") * Bumping requires\_ansible to \>=2.14.0, since previous ansible-core versions are EoL now. * This release removes previously deprecated modules and attributes from this collection. Please refer to the **Removed Features** section for details. * Update the netcommon base version 6.1.0 to support cli\_restore plugin. #### cisco.asa[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#cisco-asa "Link to this heading") * Bumping requires\_ansible to \>=2.14.0, since previous ansible-core versions are EoL now. #### cisco.ios[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#cisco-ios "Link to this heading") * Bumping requires\_ansible to \>=2.14.0, since previous ansible-core versions are EoL now. * Update the netcommon base version 6.1.0 to support cli\_restore plugin. * ios\_ntp - Remove deprecated ntp legacy module #### cisco.iosxr[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#cisco-iosxr "Link to this heading") * Bumping requires\_ansible to \>=2.14.0, since previous ansible-core versions are EoL now. * This release removes previously deprecated module and attributes from this collection. Please refer to the **Removed Features** section for details. * Update the netcommon base version to support cli\_restore plugin. #### cisco.nxos[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#cisco-nxos "Link to this heading") * Bumping requires\_ansible to \>=2.14.0, since previous ansible-core versions are EoL now. * This release removes four previously deprecated modules from this collection. Please refer to the **Removed Features** section for details. * Updated the minimum required ansible.netcommon version to 6.1.0 to support the cli\_restore module. #### community.dns[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id47 "Link to this heading") * The `community.dns` collection now depends on the `community.library_inventory_filtering_v1` collection. This utility collection provides host filtering functionality for inventory plugins. If you use the Ansible community package, both collections are included and you do not have to do anything special. If you install the collection with `ansible-galaxy collection install`, it will be installed automatically. If you install the collection by copying the files of the collection to a place where ansible-core can find it, for example by cloning the git repository, you need to make sure that you also have to install the dependency if you are using the inventory plugins ([https://github.com/ansible-collections/community.dns/pull/196](https://github.com/ansible-collections/community.dns/pull/196) ). #### community.docker[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id48 "Link to this heading") * The `community.docker` collection now depends on the `community.library_inventory_filtering_v1` collection. This utility collection provides host filtering functionality for inventory plugins. If you use the Ansible community package, both collections are included and you do not have to do anything special. If you install the collection with `ansible-galaxy collection install`, it will be installed automatically. If you install the collection by copying the files of the collection to a place where ansible-core can find it, for example by cloning the git repository, you need to make sure that you also have to install the dependency if you are using the inventory plugins ([https://github.com/ansible-collections/community.docker/pull/698](https://github.com/ansible-collections/community.docker/pull/698) ). #### community.hashi\_vault[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#community-hashi-vault "Link to this heading") * requirements - the `requests` package which is required by `hvac` now has a more restrictive range for this collection in certain use cases due to breaking security changes in `ansible-core` that were backported ([https://github.com/ansible-collections/community.hashi\_vault/pull/416](https://github.com/ansible-collections/community.hashi_vault/pull/416) ). #### community.hrobot[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id49 "Link to this heading") * The `community.hrobot` collection now depends on the `community.library_inventory_filtering_v1` collection. This utility collection provides host filtering functionality for inventory plugins. If you use the Ansible community package, both collections are included and you do not have to do anything special. If you install the collection with `ansible-galaxy collection install`, it will be installed automatically. If you install the collection by copying the files of the collection to a place where ansible-core can find it, for example by cloning the git repository, you need to make sure that you also have to install the dependency if you are using the inventory plugin ([https://github.com/ansible-collections/community.hrobot/pull/101](https://github.com/ansible-collections/community.hrobot/pull/101) ). #### community.mysql[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id50 "Link to this heading") * Collection version 2.\*.\* is EOL, no more bugfixes will be backported. Please consider upgrading to the latest version. #### containers.podman[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id51 "Link to this heading") * Add quadlet support for Podman modules #### dellemc.openmanage[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id52 "Link to this heading") * All OME modules are enhanced to support the environment variables OME\_USERNAME and OME\_PASSWORD as fallback for credentials. * All iDRAC and Redfish modules are enhanced to support the environment variables IDRAC\_USERNAME and IDRAC\_PASSWORD as fallback for credentials. * idrac\_certificates - The module is enhanced to support the import and export of CUSTOMCERTIFICATE. * idrac\_diagnostics - The module is introduced to run and export diagnostics on iDRAC. * idrac\_gather\_facts - This role is enhanced to support secure boot. * idrac\_license - The module is introduced to configure iDRAC licenses. * idrac\_session - This module allows you to create and delete the sessions on iDRAC. * idrac\_user - This role is introduced to manage local users of iDRAC. #### dellemc.unity[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#dellemc-unity "Link to this heading") * Adding support for Unity Puffin v5.4. #### fortinet.fortios[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id53 "Link to this heading") * Add notes for backup modules in the documentation in both monitor and monitor\_fact modules. * Supported new FOS versions 7.4.2 and 7.4.3, and support data type mac\_address in the collection. * Update all the boolean values to true/false in the documents and examples. * Update the document of log\_fact. * Update the documentation for the supported versions from latest to a fix version number. * Update the mismatched version message with version ranges. * Update the required ansible version to 2.14. * Update the required ansible version to 2.15. * Update the supported version ranges instead of concrete version numbers to reduce the collection size. #### grafana.grafana[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id54 "Link to this heading") * Add Grafana Loki role by @voidquark in [https://github.com/grafana/grafana-ansible-collection/pull/188](https://github.com/grafana/grafana-ansible-collection/pull/188) * Add Grafana Mimir role by @GVengelen in [https://github.com/grafana/grafana-ansible-collection/pull/183](https://github.com/grafana/grafana-ansible-collection/pull/183) * Add a new config part to configure KeyCloak based auth by @he0s in [https://github.com/grafana/grafana-ansible-collection/pull/191](https://github.com/grafana/grafana-ansible-collection/pull/191) * Add an Ansible role for Grafana Alloy by @ishanjainn in [https://github.com/grafana/grafana-ansible-collection/pull/169](https://github.com/grafana/grafana-ansible-collection/pull/169) * Add an Ansible role for OpenTelemetry Collector by @ishanjainn in [https://github.com/grafana/grafana-ansible-collection/pull/138](https://github.com/grafana/grafana-ansible-collection/pull/138) * Add promtail role by @voidquark in [https://github.com/grafana/grafana-ansible-collection/pull/197](https://github.com/grafana/grafana-ansible-collection/pull/197) * Bump ansible-lint from 24.2.2 to 24.2.3 by @dependabot in [https://github.com/grafana/grafana-ansible-collection/pull/195](https://github.com/grafana/grafana-ansible-collection/pull/195) #### ibm.qradar[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#ibm-qradar "Link to this heading") * Bumping requires\_ansible to \>=2.14.0, since previous ansible-core versions are EoL now. #### infoblox.nios\_modules[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#infoblox-nios-modules "Link to this heading") * Upgrade Ansible version support from 2.13 to 2.16. * Upgrade Python version support from 3.8 to 3.10. #### junipernetworks.junos[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#junipernetworks-junos "Link to this heading") * Bumping requires\_ansible to \>=2.14.0, since previous ansible-core versions are EoL now. * This release removes previously deprecated modules from this collection. Please refer to the **Removed Features** section for details. * Update the netcommon base version 6.1.0 to support cli\_restore plugin. #### splunk.es[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#splunk-es "Link to this heading") * Bumping requires\_ansible to \>=2.14.0, since previous ansible-core versions are EoL now. ### Removed Collections[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#removed-collections "Link to this heading") * community.azure (previously included version: 2.0.0) * community.sap (previously included version: 2.0.0) * gluster.gluster (previously included version: 1.0.2) * hpe.nimble (previously included version: 1.1.4) * netapp.aws (previously included version: 21.7.1) * netapp.azure (previously included version: 21.10.1) * netapp.elementsw (previously included version: 21.7.0) * netapp.um\_info (previously included version: 21.8.1) * purestorage.fusion (previously included version: 1.6.0) ### Removed Features[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#removed-features "Link to this heading") * The `community.azure` collection was considered unmaintained and has been removed from Ansible 10 ([https://github.com/ansible-community/community-topics/issues/263](https://github.com/ansible-community/community-topics/issues/263) ). Users can still install this collection with `ansible-galaxy collection install community.azure`. * The `gluster.gluster` collection was considered unmaintained and has been removed from Ansible 10 ([https://github.com/ansible-community/community-topics/issues/225](https://github.com/ansible-community/community-topics/issues/225) ). Users can still install this collection with `ansible-galaxy collection install gluster.gluster`. * The `hpe.nimble` collection was considered unmaintained and has been removed from Ansible 10 ([https://github.com/ansible-community/community-topics/issues/254](https://github.com/ansible-community/community-topics/issues/254) ). Users can still install this collection with `ansible-galaxy collection install hpe.nimble`. * The `netapp.aws` collection was considered unmaintained and has been removed from Ansible 10 ([https://github.com/ansible-community/community-topics/issues/223](https://github.com/ansible-community/community-topics/issues/223) ). Users can still install this collection with `ansible-galaxy collection install netapp.aws`. * The `netapp.azure` collection was considered unmaintained and has been removed from Ansible 10 ([https://github.com/ansible-community/community-topics/issues/234](https://github.com/ansible-community/community-topics/issues/234) ). Users can still install this collection with `ansible-galaxy collection install netapp.azure`. * The `netapp.elementsw` collection was considered unmaintained and has been removed from Ansible 10 ([https://github.com/ansible-community/community-topics/issues/235](https://github.com/ansible-community/community-topics/issues/235) ). Users can still install this collection with `ansible-galaxy collection install netapp.elementsw`. * The `netapp.um_info` collection was considered unmaintained and has been removed from Ansible 10 ([https://github.com/ansible-community/community-topics/issues/244](https://github.com/ansible-community/community-topics/issues/244) ). Users can still install this collection with `ansible-galaxy collection install netapp.um_info`. * The collection `community.sap` has been completely removed from Ansible. It has been renamed to `community.sap_libs`. The collection will be completely removed from Ansible eventually. Please update your FQCNs from `community.sap` to `community.sap_libs`. * The deprecated `purestorage.fusion` collection has been removed ([https://forum.ansible.com/t/3712](https://forum.ansible.com/t/3712) ). #### Ansible-core[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id55 "Link to this heading") * Remove deprecated APIs from ansible-docs ([https://github.com/ansible/ansible/issues/81716](https://github.com/ansible/ansible/issues/81716) ). * Remove deprecated JINJA2\_NATIVE\_WARNING environment variable ([https://github.com/ansible/ansible/issues/81714](https://github.com/ansible/ansible/issues/81714) ) * Remove deprecated `scp_if_ssh` from ssh connection plugin ([https://github.com/ansible/ansible/issues/81715](https://github.com/ansible/ansible/issues/81715) ). * Remove deprecated crypt support from ansible.utils.encrypt ([https://github.com/ansible/ansible/issues/81717](https://github.com/ansible/ansible/issues/81717) ) * Removed Python 2.7 and Python 3.6 as a supported remote version. Python 3.7+ is now required for target execution. * With the removal of Python 2 support, the yum module and yum action plugin are removed and redirected to `dnf`. #### amazon.aws[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id56 "Link to this heading") * iam\_role - the `iam_role.assume_role_policy_document_raw` return value has been deprecated. `iam_role.assume_role_policy_document` now returns the same format as `iam_role.assume_role_policy_document_raw` ([https://github.com/ansible-collections/amazon.aws/pull/2040](https://github.com/ansible-collections/amazon.aws/pull/2040) ). * iam\_role\_info - the `iam_role.assume_role_policy_document_raw` return value has been deprecated. `iam_role.assume_role_policy_document` now returns the same format as `iam_role.assume_role_policy_document_raw` ([https://github.com/ansible-collections/amazon.aws/pull/2040](https://github.com/ansible-collections/amazon.aws/pull/2040) ). * module\_utils.policy - the previously deprecated `sort_json_policy_dict()` function has been removed, consider using `compare_policies()` instead ([https://github.com/ansible-collections/amazon.aws/pull/2052](https://github.com/ansible-collections/amazon.aws/pull/2052) ). #### arista.eos[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id57 "Link to this heading") * Remove depreacted eos\_bgp module which is replaced with eos\_bgp\_global and eos\_bgp\_address\_family. * Remove deprecated eos\_logging module which is replaced with eos\_logging\_global resource module. * Remove deprecated timers.throttle attribute. #### cisco.ios[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id58 "Link to this heading") * Deprecated ios\_ntp module in favor of ios\_ntp\_global. * Removed previously deprecated ios\_bgp module in favor of ios\_bgp\_global and ios\_bgp\_address\_family. #### cisco.iosxr[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id59 "Link to this heading") * Remove deprecated iosxr\_logging module which is replaced with iosxr\_logging\_global resource module. #### cisco.nxos[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id60 "Link to this heading") * The nxos\_logging module has been removed with this release. * The nxos\_ntp module has been removed with this release. * The nxos\_ntp\_auth module has been removed with this release. * The nxos\_ntp\_options module has been removed with this release. #### community.dns[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id61 "Link to this heading") * The collection no longer supports Ansible, ansible-base, and ansible-core releases that are currently End of Life at the time of the 3.0.0 release. This means that Ansible 2.9, ansible-base 2.10, ansible-core 2.11, ansible-core 2.12, and ansible-core 2.13 are no longer supported. The collection might still work with these versions, but it can stop working at any moment without advance notice, and this will not be considered a bug ([https://github.com/ansible-collections/community.dns/pull/196](https://github.com/ansible-collections/community.dns/pull/196) ). * hetzner\_dns\_record\_set, hetzner\_dns\_record - the deprecated alias `name` of the prefix option was removed ([https://github.com/ansible-collections/community.dns/pull/196](https://github.com/ansible-collections/community.dns/pull/196) ). * hosttech\_dns\_records - the redirect to the `hosttech_dns_record_sets` module has been removed ([https://github.com/ansible-collections/community.dns/pull/196](https://github.com/ansible-collections/community.dns/pull/196) ). #### community.general[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id62 "Link to this heading") * The deprecated redirects for internal module names have been removed. These internal redirects were extra-long FQCNs like `community.general.packaging.os.apt_rpm` that redirect to the short FQCN `community.general.apt_rpm`. They were originally needed to implement flatmapping; as various tooling started to recommend users to use the long names flatmapping was removed from the collection and redirects were added for users who already followed these incorrect recommendations ([https://github.com/ansible-collections/community.general/pull/7835](https://github.com/ansible-collections/community.general/pull/7835) ). * ansible\_galaxy\_install - the `ack_ansible29` and `ack_min_ansiblecore211` options have been removed. They no longer had any effect ([https://github.com/ansible-collections/community.general/pull/8198](https://github.com/ansible-collections/community.general/pull/8198) ). * cloudflare\_dns - remove support for SPF records. These are no longer supported by CloudFlare ([https://github.com/ansible-collections/community.general/pull/7782](https://github.com/ansible-collections/community.general/pull/7782) ). * django\_manage - support for the `command` values `cleanup`, `syncdb`, and `validate` were removed. Use `clearsessions`, `migrate`, and `check` instead, respectively ([https://github.com/ansible-collections/community.general/pull/8198](https://github.com/ansible-collections/community.general/pull/8198) ). * flowdock - this module relied on HTTPS APIs that do not exist anymore and was thus removed ([https://github.com/ansible-collections/community.general/pull/8198](https://github.com/ansible-collections/community.general/pull/8198) ). * mh.mixins.deps module utils - the `DependencyMixin` has been removed. Use the `deps` module utils instead ([https://github.com/ansible-collections/community.general/pull/8198](https://github.com/ansible-collections/community.general/pull/8198) ). * proxmox - the `proxmox_default_behavior` option has been removed ([https://github.com/ansible-collections/community.general/pull/8198](https://github.com/ansible-collections/community.general/pull/8198) ). * rax\* modules, rax module utils, rax docs fragment - the Rackspace modules relied on the deprecated package `pyrax` and were thus removed ([https://github.com/ansible-collections/community.general/pull/8198](https://github.com/ansible-collections/community.general/pull/8198) ). * redhat module utils - the classes `Rhsm`, `RhsmPool`, and `RhsmPools` have been removed ([https://github.com/ansible-collections/community.general/pull/8198](https://github.com/ansible-collections/community.general/pull/8198) ). * redhat\_subscription - the alias `autosubscribe` of the `auto_attach` option was removed ([https://github.com/ansible-collections/community.general/pull/8198](https://github.com/ansible-collections/community.general/pull/8198) ). * stackdriver - this module relied on HTTPS APIs that do not exist anymore and was thus removed ([https://github.com/ansible-collections/community.general/pull/8198](https://github.com/ansible-collections/community.general/pull/8198) ). * webfaction\_\* modules - these modules relied on HTTPS APIs that do not exist anymore and were thus removed ([https://github.com/ansible-collections/community.general/pull/8198](https://github.com/ansible-collections/community.general/pull/8198) ). #### community.grafana[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#community-grafana "Link to this heading") * removed deprecated message argument in grafana\_dashboard #### community.hrobot[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id63 "Link to this heading") * The collection no longer supports Ansible, ansible-base, and ansible-core releases that are currently End of Life at the time of the 2.0.0 release. This means that Ansible 2.9, ansible-base 2.10, ansible-core 2.11, ansible-core 2.12, and ansible-core 2.13 are no longer supported. The collection might still work with these versions, but it can stop working at any moment without advance notice, and this will not be considered a bug ([https://github.com/ansible-collections/community.hrobot/pull/101](https://github.com/ansible-collections/community.hrobot/pull/101) ). #### junipernetworks.junos[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id64 "Link to this heading") * Remove deprected junos\_logging module which is replaced by junos\_logging\_global resource module. ### Deprecated Features[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id65 "Link to this heading") * The `inspur.sm` collection is considered unmaintained and will be removed from Ansible 11 if no one starts maintaining it again before Ansible 11. See [Collections Removal Process for unmaintained collections](https://docs.ansible.com/ansible/devel/community/collection_contributors/collection_package_removal.html#unmaintained-collections) for more details, including for how this can be cancelled ([https://forum.ansible.com/t/2854](https://forum.ansible.com/t/2854) ). * The `netapp.storagegrid` collection is considered unmaintained and will be removed from Ansible 11 if no one starts maintaining it again before Ansible 11. See [Collections Removal Process for unmaintained collections](https://docs.ansible.com/ansible/devel/community/collection_contributors/collection_package_removal.html#unmaintained-collections) for more details, including for how this can be cancelled ([https://forum.ansible.com/t/2811](https://forum.ansible.com/t/2811) ). #### Ansible-core[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id66 "Link to this heading") * Old style vars plugins which use the entrypoints get\_host\_vars or get\_group\_vars are deprecated. The plugin should be updated to inherit from BaseVarsPlugin and define a get\_vars method as the entrypoint. * The ‘required’ parameter in ‘ansible.module\_utils.common.process.get\_bin\_path’ API is deprecated ([https://github.com/ansible/ansible/issues/82464](https://github.com/ansible/ansible/issues/82464) ). * `module_utils` - importing the following convenience helpers from `ansible.module_utils.basic` has been deprecated: `get_exception`, `literal_eval`, `_literal_eval`, `datetime`, `signal`, `types`, `chain`, `repeat`, `PY2`, `PY3`, `b`, `binary_type`, `integer_types`, `iteritems`, `string_types`, `test_type`, `map` and `shlex_quote`. * ansible-doc - role entrypoint attributes are deprecated and eventually will no longer be shown in ansible-doc from ansible-core 2.20 on ([https://github.com/ansible/ansible/issues/82639](https://github.com/ansible/ansible/issues/82639) , [https://github.com/ansible/ansible/pull/82678](https://github.com/ansible/ansible/pull/82678) ). * paramiko connection plugin, configuration items in the global scope are being deprecated and will be removed in favor or the existing same options in the plugin itself. Users should not need to change anything (how to configure them are the same) but plugin authors using the global constants should move to using the plugin’s get\_option(). #### amazon.aws[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id67 "Link to this heading") * aws\_ec2 inventory plugin - removal of the previously deprecated `include_extra_api_calls` option has been assigned to release 9.0.0 ([https://github.com/ansible-collections/amazon.aws/pull/2040](https://github.com/ansible-collections/amazon.aws/pull/2040) ). * cloudformation - the `template` parameter has been deprecated and will be removed in a release after 2026-05-01. The `template_body` parameter can be used in conjungtion with the lookup plugin ([https://github.com/ansible-collections/amazon.aws/pull/2048](https://github.com/ansible-collections/amazon.aws/pull/2048) ). * iam\_policy - removal of the previously deprecated `policies` return key has been assigned to release 9.0.0. Use the `policy_names` return key instead ([https://github.com/ansible-collections/amazon.aws/pull/2040](https://github.com/ansible-collections/amazon.aws/pull/2040) ). * iam\_role\_info - in a release after 2026-05-01 paths must begin and end with `/` ([https://github.com/ansible-collections/amazon.aws/pull/1998](https://github.com/ansible-collections/amazon.aws/pull/1998) ). * module\_utils.botocore - the `boto3` parameter for `get_aws_connection_info()` will be removed in a release after 2025-05-01. The `boto3` parameter has been ignored since release 4.0.0 ([https://github.com/ansible-collections/amazon.aws/pull/2047](https://github.com/ansible-collections/amazon.aws/pull/2047) ). * module\_utils.botocore - the `boto3` parameter for `get_aws_region()` will be removed in a release after 2025-05-01. The `boto3` parameter has been ignored since release 4.0.0 ([https://github.com/ansible-collections/amazon.aws/pull/2047](https://github.com/ansible-collections/amazon.aws/pull/2047) ). * module\_utils.ec2 - the `boto3` parameter for `get_ec2_security_group_ids_from_names()` will be removed in a release after 2025-05-01. The `boto3` parameter has been ignored since release 4.0.0 ([https://github.com/ansible-collections/amazon.aws/pull/2047](https://github.com/ansible-collections/amazon.aws/pull/2047) ). * rds\_param\_group - the `rds_param_group` module has been renamed to `rds_instance_param_group`. The usage of the module has not changed. The rds\_param\_group alias will be removed in version 10.0.0 ([https://github.com/ansible-collections/amazon.aws/pull/2058](https://github.com/ansible-collections/amazon.aws/pull/2058) ). #### community.aws[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id68 "Link to this heading") * aws\_glue\_connection - updated the deprecation for removal of the `connection_parameters` return key from `after 2024-06-01` to release version `9.0.0`, it is being replaced by the `raw_connection_parameters` key ([https://github.com/ansible-collections/community.aws/pull/518](https://github.com/ansible-collections/community.aws/pull/518) ). * ecs\_cluster - updated the deprecation for updated default of `purge_capacity_providers`, the current default of `False` will be changed to `True` in release `9.0.0`. To maintain the current behaviour explicitly set `purge_capacity_providers=False` ([https://github.com/ansible-collections/community.aws/pull/1640](https://github.com/ansible-collections/community.aws/pull/1640) ). * ecs\_service - updated the deprecation for updated default of `purge_placement_constraints`, the current default of `False` will be changed to `True` in release `9.0.0`. To maintain the current behaviour explicitly set `purge_placement_constraints=False` ([https://github.com/ansible-collections/community.aws/pull/1716](https://github.com/ansible-collections/community.aws/pull/1716) ). * ecs\_service - updated the deprecation for updated default of `purge_placement_strategy`, the current default of `False` will be changed to `True` in release `9.0.0`. To maintain the current behaviour explicitly set `purge_placement_strategy=False` ([https://github.com/ansible-collections/community.aws/pull/1716](https://github.com/ansible-collections/community.aws/pull/1716) ). #### community.crypto[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#community-crypto "Link to this heading") * acme documentation fragment - the default `community.crypto.acme[.documentation]` docs fragment is deprecated and will be removed from community.crypto 3.0.0. Replace it with both the new `community.crypto.acme.basic` and `community.crypto.acme.account` fragments ([https://github.com/ansible-collections/community.crypto/pull/735](https://github.com/ansible-collections/community.crypto/pull/735) ). * acme.backends module utils - from community.crypto on, all implementations of `CryptoBackend` must override `get_ordered_csr_identifiers()`. The current default implementation, which simply sorts the result of `get_csr_identifiers()`, will then be removed ([https://github.com/ansible-collections/community.crypto/pull/725](https://github.com/ansible-collections/community.crypto/pull/725) ). * acme.backends module utils - the `get_cert_information()` method for a ACME crypto backend must be implemented from community.crypto 3.0.0 on ([https://github.com/ansible-collections/community.crypto/pull/736](https://github.com/ansible-collections/community.crypto/pull/736) ). * crypto.module\_backends.common module utils - the `crypto.module_backends.common` module utils is deprecated and will be removed from community.crypto 3.0.0. Use the improved `argspec` module util instead ([https://github.com/ansible-collections/community.crypto/pull/749](https://github.com/ansible-collections/community.crypto/pull/749) ). * openssl\_csr\_pipe, openssl\_privatekey\_pipe, x509\_certificate\_pipe - the current behavior of check mode is deprecated and will change in community.crypto 3.0.0. The current behavior is similar to the modules without `_pipe`: if the object needs to be (re-)generated, only the `changed` status is set, but the object is not updated. From community.crypto 3.0.0 on, the modules will ignore check mode and always act as if check mode is not active. This behavior can already achieved now by adding `check_mode: false` to the task. If you think this breaks your use-case of this module, please [create an issue in the community.crypto repository](https://github.com/ansible-collections/community.crypto/issues/new/choose) ([https://github.com/ansible-collections/community.crypto/issues/712](https://github.com/ansible-collections/community.crypto/issues/712) , [https://github.com/ansible-collections/community.crypto/pull/714](https://github.com/ansible-collections/community.crypto/pull/714) ). #### community.dns[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id69 "Link to this heading") * hetzner\_dns\_records and hosttech\_dns\_records inventory plugins - the `filters` option has been renamed to `simple_filters`. The old name will stop working in community.hrobot 2.0.0 ([https://github.com/ansible-collections/community.dns/pull/181](https://github.com/ansible-collections/community.dns/pull/181) ). #### community.docker[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id70 "Link to this heading") * docker\_compose - the Docker Compose v1 module is deprecated and will be removed from community.docker 4.0.0. Please migrate to the `community.docker.docker_compose_v2` module, which works with Docker Compose v2 ([https://github.com/ansible-collections/community.docker/issues/823](https://github.com/ansible-collections/community.docker/issues/823) , [https://github.com/ansible-collections/community.docker/pull/833](https://github.com/ansible-collections/community.docker/pull/833) ). * docker\_container - the default `ignore` for the `image_name_mismatch` parameter has been deprecated and will switch to `recreate` in community.docker 4.0.0. A deprecation warning will be printed in situations where the default value is used and where a behavior would change once the default changes ([https://github.com/ansible-collections/community.docker/pull/703](https://github.com/ansible-collections/community.docker/pull/703) ). * various modules and plugins - the `ssl_version` option has been deprecated and will be removed from community.docker 4.0.0. It has already been removed from Docker SDK for Python 7.0.0, and was only necessary in the past to work around SSL/TLS issues ([https://github.com/ansible-collections/community.docker/pull/853](https://github.com/ansible-collections/community.docker/pull/853) ). #### community.general[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id71 "Link to this heading") * MH DependencyCtxMgr module\_utils - deprecate `module_utils.mh.mixin.deps.DependencyCtxMgr` in favour of `module_utils.deps` ([https://github.com/ansible-collections/community.general/pull/8280](https://github.com/ansible-collections/community.general/pull/8280) ). * ModuleHelper module\_utils - deprecate `plugins.module_utils.module_helper.AnsibleModule` ([https://github.com/ansible-collections/community.general/pull/8280](https://github.com/ansible-collections/community.general/pull/8280) ). * ModuleHelper module\_utils - deprecate `plugins.module_utils.module_helper.DependencyCtxMgr` ([https://github.com/ansible-collections/community.general/pull/8280](https://github.com/ansible-collections/community.general/pull/8280) ). * ModuleHelper module\_utils - deprecate `plugins.module_utils.module_helper.StateMixin` ([https://github.com/ansible-collections/community.general/pull/8280](https://github.com/ansible-collections/community.general/pull/8280) ). * ModuleHelper module\_utils - deprecate `plugins.module_utils.module_helper.VarDict,` ([https://github.com/ansible-collections/community.general/pull/8280](https://github.com/ansible-collections/community.general/pull/8280) ). * ModuleHelper module\_utils - deprecate `plugins.module_utils.module_helper.VarMeta` ([https://github.com/ansible-collections/community.general/pull/8280](https://github.com/ansible-collections/community.general/pull/8280) ). * ModuleHelper module\_utils - deprecate `plugins.module_utils.module_helper.VarsMixin` ([https://github.com/ansible-collections/community.general/pull/8280](https://github.com/ansible-collections/community.general/pull/8280) ). * ModuleHelper module\_utils - deprecate use of `VarsMixin` in favor of using the `VardDict` module\_utils ([https://github.com/ansible-collections/community.general/pull/8226](https://github.com/ansible-collections/community.general/pull/8226) ). * ModuleHelper vars module\_utils - bump deprecation of `VarMeta`, `VarDict` and `VarsMixin` to version 11.0.0 ([https://github.com/ansible-collections/community.general/pull/8226](https://github.com/ansible-collections/community.general/pull/8226) ). * apt\_rpm - the behavior of `state=present` and `state=installed` is deprecated and will change in community.general 11.0.0. Right now the module will upgrade a package to the latest version if one of these two states is used. You should explicitly use `state=latest` if you want this behavior, and switch to `state=present_not_latest` if you do not want to upgrade the package if it is already installed. In community.general 11.0.0 the behavior of `state=present` and `state=installed` will change to that of `state=present_not_latest` ([https://github.com/ansible-collections/community.general/issues/8217](https://github.com/ansible-collections/community.general/issues/8217) , [https://github.com/ansible-collections/community.general/pull/8285](https://github.com/ansible-collections/community.general/pull/8285) ). * consul\_acl - the module has been deprecated and will be removed in community.general 10.0.0. `consul_token` and `consul_policy` can be used instead ([https://github.com/ansible-collections/community.general/pull/7901](https://github.com/ansible-collections/community.general/pull/7901) ). * django\_manage - the `ack_venv_creation_deprecation` option has no more effect and will be removed from community.general 11.0.0 ([https://github.com/ansible-collections/community.general/pull/8198](https://github.com/ansible-collections/community.general/pull/8198) ). * gitlab modules - the basic auth method on GitLab API have been deprecated and will be removed in community.general 10.0.0 ([https://github.com/ansible-collections/community.general/pull/8383](https://github.com/ansible-collections/community.general/pull/8383) ). * hipchat callback plugin - the hipchat service has been discontinued and the self-hosted variant has been End of Life since 2020. The callback plugin is therefore deprecated and will be removed from community.general 10.0.0 if nobody provides compelling reasons to still keep it ([https://github.com/ansible-collections/community.general/issues/8184](https://github.com/ansible-collections/community.general/issues/8184) , [https://github.com/ansible-collections/community.general/pull/8189](https://github.com/ansible-collections/community.general/pull/8189) ). * irc - the defaults `false` for `use_tls` and `validate_certs` have been deprecated and will change to `true` in community.general 10.0.0 to improve security. You can already improve security now by explicitly setting them to `true`. Specifying values now disables the deprecation warning ([https://github.com/ansible-collections/community.general/pull/7578](https://github.com/ansible-collections/community.general/pull/7578) ). #### community.hrobot[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id72 "Link to this heading") * robot inventory plugin - the `filters` option has been renamed to `simple_filters`. The old name will stop working in community.hrobot 2.0.0 ([https://github.com/ansible-collections/community.hrobot/pull/94](https://github.com/ansible-collections/community.hrobot/pull/94) ). #### community.okd[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id73 "Link to this heading") * openshift - the `openshift` inventory plugin has been deprecated and will be removed in release 4.0.0 ([https://github.com/ansible-collections/kubernetes.core/issues/31](https://github.com/ansible-collections/kubernetes.core/issues/31) ). #### community.vmware[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id74 "Link to this heading") * vmware\_guest\_tools\_info - vm\_tools\_install\_status will be removed from next major version (5.0.0) of the collection since the API call that provides this information has been deprecated by VMware. Use vm\_tools\_running\_status / vm\_tools\_version\_status instead ([https://github.com/ansible-collections/community.vmware/issues/2033](https://github.com/ansible-collections/community.vmware/issues/2033) ). #### dellemc.openmanage[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id75 "Link to this heading") * The `dellemc_idrac_storage_volume` module is deprecated and replaced with `idrac_storage_volume`. #### kubernetes.core[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_10.html#id76 "Link to this heading") * k8s - the `k8s` inventory plugin has been deprecated and will be removed in release 4.0.0 ([https://github.com/ansible-collections/kubernetes.core/issues/31](https://github.com/ansible-collections/kubernetes.core/issues/31) ). --- # Using variables — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * [Using Ansible playbooks](https://docs.ansible.com/projects/ansible/latest/playbook_guide/index.html) * [Working with playbooks](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks.html) * Using variables * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/playbook_guide/playbooks_variables.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Using variables[](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#using-variables "Link to this heading") ==================================================================================================================================================== Ansible uses variables to manage differences between systems. With Ansible, you can execute tasks and playbooks on multiple systems with a single command. To represent the variations among those different systems, you can create variables with standard YAML syntax, including lists and dictionaries. You can define these variables in your playbooks, in your [inventory](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#intro-inventory) , in reusable [files](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse.html#playbooks-reuse) or [roles](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#playbooks-reuse-roles) , or at the command line. You can also create variables during a playbook run by registering the return value of a task as a new variable. After you create a variable, you can use it in module arguments, in [conditional “when” statements](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_conditionals.html#playbooks-conditionals) , in [templates](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_templating.html#playbooks-templating) , and in [loops](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_loops.html#playbooks-loops) . After you understand the concepts and examples on this page, read about [Ansible facts](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_vars_facts.html#vars-and-facts) , which are variables you retrieve from remote systems. [Creating valid variable names](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#id17) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#creating-valid-variable-names "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Not all strings are valid Ansible variable names. A variable name can only include letters, numbers, and underscores. [Python keywords](https://docs.python.org/3/reference/lexical_analysis.html#keywords) or [playbook keywords](https://docs.ansible.com/projects/ansible/latest/reference_appendices/playbooks_keywords.html#playbook-keywords) are not valid variable names. A variable name cannot begin with a number. Variable names can begin with an underscore. In many programming languages, variables that begin with an underscore are private. This is not true in Ansible. Ansible treats variables that begin with an underscore the same as any other variable. Do not rely on this convention for privacy or security. This table gives examples of valid and invalid variable names: | Valid variable names | Not valid | | --- | --- | | `foo` | `*foo`, [Python keywords](https://docs.python.org/3/reference/lexical_analysis.html#keywords)
such as `async` and `lambda` | | `foo_env` | [playbook keywords](https://docs.ansible.com/projects/ansible/latest/reference_appendices/playbooks_keywords.html#playbook-keywords)
such as `environment` | | `foo_port` | `foo-port`, `foo port`, `foo.port` | | `foo5`, `_foo` | `5foo`, `12` | Ansible defines certain [variables](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#special-variables) internally. You cannot define these variables. Avoid variable names that overwrite Jinja2 global functions listed in [Working with playbooks](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks.html#working-with-playbooks) , such as [lookup](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_lookups.html#lookups-and-variables) , [query](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_lookups.html#lookups-and-variables-query) , [q](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_lookups.html#lookups-and-variables-query) , [now](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_templating_now.html#templating-now) , and [undef](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_templating_undef.html#templating-undef) . [Simple variables](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#id18) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#simple-variables "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Simple variables combine a variable name with a single value. You can use this syntax, and the syntax for lists and dictionaries shown below, in a variety of places. For details about setting variables in inventory, in playbooks, in reusable files, in roles, or at the command line, see [Where to set variables](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#setting-variables) . ### [Defining simple variables](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#id19) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#defining-simple-variables "Link to this heading") You can define a simple variable using standard YAML syntax. For example: remote\_install\_path: /opt/my\_app\_config ### [Referencing simple variables](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#id20) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#referencing-simple-variables "Link to this heading") After you define a variable, use Jinja2 syntax to reference it. Jinja2 variables use double curly braces. For example, the expression `My amp goes to {{ max_amp_value }}` demonstrates the most basic form of variable substitution. You can use Jinja2 syntax in playbooks. The following example shows a variable that defines the location of a file, which can vary from one system to another: ansible.builtin.template: src: foo.cfg.j2 dest: '{{ remote\_install\_path }}/foo.cfg' Ansible allows Jinja2 loops and conditionals in [templates](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_templating.html#playbooks-templating) but not in playbooks. You cannot create a loop of tasks. Ansible playbooks are pure machine-parseable YAML. [When to quote variables (a YAML gotcha)](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#id21) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#when-to-quote-variables-a-yaml-gotcha "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- If you start a value with `{{ foo }}`, you must quote the whole expression to create valid YAML syntax. If you do not quote the whole expression, the YAML parser cannot interpret the syntax. The parser cannot determine if it is a variable or the start of a YAML dictionary. For guidance on writing YAML, see the [YAML Syntax](https://docs.ansible.com/projects/ansible/latest/reference_appendices/YAMLSyntax.html#yaml-syntax) documentation. If you use a variable without quotes, like this: \- hosts: app\_servers vars: app\_path: {{ base\_path }}/22 You will see: `ERROR! Syntax Error while loading YAML.` If you add quotes, Ansible works correctly: \- hosts: app\_servers vars: app\_path: "{{ base\_path }}/22" [List variables](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#id22) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#list-variables "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- A list variable combines a variable name with multiple values. You can store the multiple values as an itemized list or in square brackets `[]`, separated with commas. ### [Defining variables as lists](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#id23) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#defining-variables-as-lists "Link to this heading") You can define variables with multiple values using YAML lists. For example: region: \- northeast \- southeast \- midwest ### [Referencing list variables](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#id24) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#referencing-list-variables "Link to this heading") If you use a variable defined as a list (also called an array), you can use individual, specific items from that list. The first item in a list is item 0, the second item is item 1, and so on. For example: region: "{{ region\[0\] }}" The value of this expression would be “northeast”. [Dictionary variables](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#id25) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#dictionary-variables "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- A dictionary stores data in key-value pairs. Usually, you use dictionaries to store related data, such as the information contained in an ID or a user profile. ### [Defining variables as key-value dictionaries](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#id26) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#defining-variables-as-key-value-dictionaries "Link to this heading") You can define more complex variables using YAML dictionaries. A YAML dictionary maps keys to values. For example: foo: field1: one field2: two ### [Referencing key-value dictionary variables](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#id27) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#referencing-key-value-dictionary-variables "Link to this heading") If you use a variable defined as a key-value dictionary (also called a hash), you can use individual, specific items from that dictionary using either bracket notation or dot notation: foo\['field1'\] foo.field1 Both of these examples reference the same value (“one”). Bracket notation always works. Dot notation can cause problems because some keys collide with attributes and methods of python dictionaries. Use bracket notation if you use keys that start and end with two underscores, which are reserved for special meanings in python, or are any of the known public attributes: `add`, `append`, `as_integer_ratio`, `bit_length`, `capitalize`, `center`, `clear`, `conjugate`, `copy`, `count`, `decode`, `denominator`, `difference`, `difference_update`, `discard`, `encode`, `endswith`, `expandtabs`, `extend`, `find`, `format`, `fromhex`, `fromkeys`, `get`, `has_key`, `hex`, `imag`, `index`, `insert`, `intersection`, `intersection_update`, `isalnum`, `isalpha`, `isdecimal`, `isdigit`, `isdisjoint`, `is_integer`, `islower`, `isnumeric`, `isspace`, `issubset`, `issuperset`, `istitle`, `isupper`, `items`, `iteritems`, `iterkeys`, `itervalues`, `join`, `keys`, `ljust`, `lower`, `lstrip`, `numerator`, `partition`, `pop`, `popitem`, `real`, `remove`, `replace`, `reverse`, `rfind`, `rindex`, `rjust`, `rpartition`, `rsplit`, `rstrip`, `setdefault`, `sort`, `split`, `splitlines`, `startswith`, `strip`, `swapcase`, `symmetric_difference`, `symmetric_difference_update`, `title`, `translate`, `union`, `update`, `upper`, `values`, `viewitems`, `viewkeys`, `viewvalues`, `zfill`. [Combining variables](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#id28) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#combining-variables "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- To merge variables that contain lists or dictionaries, you can use the following approaches. ### [Combining list variables](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#id29) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#combining-list-variables "Link to this heading") You can use the set\_fact module to combine lists into a new merged\_list variable as follows: vars: list1: \- apple \- banana \- fig list2: \- peach \- plum \- pear tasks: \- name: Combine list1 and list2 into a merged\_list var ansible.builtin.set\_fact: merged\_list: "{{ list1 + list2 }}" ### [Combining dictionary variables](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#id30) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#combining-dictionary-variables "Link to this heading") To merge dictionaries, use the `combine` filter. For example: vars: dict1: name: Leeroy Jenkins age: 25 occupation: Astronaut dict2: location: Galway country: Ireland postcode: H71 1234 tasks: \- name: Combine dict1 and dict2 into a merged\_dict var ansible.builtin.set\_fact: merged\_dict: "{{ dict1 | ansible.builtin.combine(dict2) }}" For more details, see [ansible.builtin.combine](https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/combine_filter.html#ansible-collections-ansible-builtin-combine-filter) . ### [Using the merge\_variables lookup](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#id31) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#using-the-merge-variables-lookup "Link to this heading") To merge variables that match the given prefixes, suffixes, or regular expressions, you can use the `community.general.merge_variables` lookup. For example: merged\_variable: "{{ lookup('community.general.merge\_variables', '\_\_my\_pattern', pattern\_type='suffix') }}" For more details and example usage, refer to the [community.general.merge\_variables lookup documentation](https://docs.ansible.com/projects/ansible/latest/collections/community/general/merge_variables_lookup.html) . [Registering variables](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#id32) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#registering-variables "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ You can create a variable from the output of an Ansible task with the task keyword `register`. You can use the registered variable in any later task in your play. For example: \- hosts: web\_servers tasks: \- name: Run a shell command and register its output as a variable ansible.builtin.shell: /usr/bin/foo register: foo\_result ignore\_errors: true \- name: Run a shell command using output of the previous task ansible.builtin.shell: /usr/bin/bar when: foo\_result.rc == 5 For more examples of using registered variables in conditions on later tasks, see [Conditionals](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_conditionals.html#playbooks-conditionals) . Registered variables may be simple variables, list variables, dictionary variables, or complex nested data structures. The documentation for each module includes a `RETURN` section that describes the return values for that module. To see the values for a particular task, run your playbook with `-v`. Registered variables are stored in memory. You cannot cache registered variables for use in future playbook runs. A registered variable is valid only on the host for the rest of the current playbook run, including subsequent plays within the same playbook run. Registered variables are host-level variables. When you register a variable in a task with a loop, the registered variable contains a value for each item in the loop. The data structure placed in the variable during the loop contains a `results` attribute, which is a list of all responses from the module. For a more in-depth example of how this works, see the [Loops](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_loops.html#playbooks-loops) section on using register with a loop. If a task fails or is skipped, Ansible still registers a variable with a failure or skipped status, unless the task is skipped based on tags. See [Tags](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_tags.html#tags) for information on adding and using tags. [Referencing nested variables](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#id33) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#referencing-nested-variables "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Many registered variables and [facts](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_vars_facts.html#vars-and-facts) are nested YAML or JSON data structures. You cannot access values from these nested data structures with the simple `{{ foo }}` syntax. You must use either bracket notation or dot notation. For example, to reference an IP address from your facts using bracket notation: '{{ ansible\_facts\["eth0"\]\["ipv4"\]\["address"\] }}' To reference an IP address from your facts using dot notation: {{ ansible\_facts.eth0.ipv4.address }} [Transforming variables with Jinja2 filters](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#id34) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#transforming-variables-with-jinja2-filters "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ Jinja2 filters let you transform the value of a variable within a template expression. For example, the `capitalize` filter capitalizes any value passed to it; the `to_yaml` and `to_json` filters change the format of your variable values. Jinja2 includes many [built-in filters](https://jinja.palletsprojects.com/templates/#builtin-filters) , and Ansible supplies many more filters. To find more examples of filters, see [Using filters to manipulate data](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_filters.html#playbooks-filters) . [Where to set variables](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#id35) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#where-to-set-variables "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can define variables in a variety of places, such as in inventory, in playbooks, in reusable files, in roles, and at the command line. Ansible loads every possible variable it finds, then chooses the variable to apply based on [variable precedence rules](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#ansible-variable-precedence) . ### [Defining variables in inventory](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#id36) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#defining-variables-in-inventory "Link to this heading") You can define different variables for each host individually, or set shared variables for a group of hosts in your inventory. For example, if all machines in the `[boston]` group use ‘boston.ntp.example.com’ as an NTP server, you can set a group variable. The [How to build your inventory](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#intro-inventory) page has details on setting [host variables](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#host-variables) and [group variables](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#group-variables) in inventory. ### [Defining variables in a play](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#id37) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#defining-variables-in-a-play "Link to this heading") You can define variables directly in a playbook play: \- hosts: webservers vars: http\_port: 80 When you define variables in a play, they are visible only to tasks executed in that play. ### [Defining variables in included files and roles](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#id38) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#defining-variables-in-included-files-and-roles "Link to this heading") You can define variables in reusable variables files or in reusable roles. If you define variables in reusable variable files, the sensitive variables are separated from playbooks. This separation enables you to store your playbooks in a source control software and even share the playbooks, without the risk of exposing passwords or other sensitive and personal data. For information about creating reusable files and roles, see [Reusing Ansible artifacts](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse.html#playbooks-reuse) . This example shows how you can include variables defined in an external file: \--- \- hosts: all remote\_user: root vars: favcolor: blue vars\_files: \- /vars/external\_vars.yml tasks: \- name: This is just a placeholder ansible.builtin.command: /bin/echo foo The contents of each variables file is a simple YAML dictionary. For example: \--- \# in the above example, this would be vars/external\_vars.yml somevar: somevalue password: magic You can keep per-host and per-group variables in similar files. To learn about organizing your variables, see [Organizing host and group variables](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#splitting-out-vars) . ### [Defining variables at runtime](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#id39) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#defining-variables-at-runtime "Link to this heading") You can define variables when you run your playbook by passing variables at the command line using the `--extra-vars` (or `-e`) argument. You can also request user input with a `vars_prompt` (see [Interactive input: prompts](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_prompts.html#playbooks-prompts) ). If you pass variables at the command line, use a single quoted string that contains one or more variables in one of the formats below. #### [Key-value format](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#id40) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#key-value-format "Link to this heading") Values passed in using the `key=value` syntax are interpreted as strings. Use the JSON format if you need to pass non-string values such as Booleans, integers, floats, and lists. ansible-playbook release.yml --extra-vars "version=1.23.45 other\_variable=foo" #### [JSON string format](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#id41) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#json-string-format "Link to this heading") ansible-playbook release.yml \--extra-vars '{"version":"1.23.45","other\_variable":"foo"}' ansible-playbook arcade.yml \--extra-vars '{"pacman":"mrs","ghosts":\["inky","pinky","clyde","sue"\]}' When passing variables with `--extra-vars`, you must escape quotes and other special characters appropriately for both your markup (for example, JSON) and for your shell: ansible-playbook arcade.yml \--extra-vars "{\\"name\\":\\"Conan O\\'Brien\\"}" ansible-playbook arcade.yml \--extra-vars '{"name":"Conan O'\\\\\\''Brien"}' ansible-playbook script.yml \--extra-vars "{\\"dialog\\":\\"He said \\\\\\"I just can\\'t get enough of those single and double-quotes"\\!"\\\\\\"\\"}" #### [Vars from a JSON or YAML file](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#id42) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#vars-from-a-json-or-yaml-file "Link to this heading") If you have a lot of special characters, use a JSON or YAML file containing the variable definitions. Prepend both JSON and YAML file names with @. ansible-playbook release.yml --extra-vars "@some\_file.json" ansible-playbook release.yml --extra-vars "@some\_file.yaml" [Variable precedence: where should I put a variable?](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#id43) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#variable-precedence-where-should-i-put-a-variable "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can set multiple variables with the same name in many different places. If you do this, Ansible loads every possible variable it finds, and then chooses the variable to apply based on variable precedence. In other words, the different variables will override each other in a certain order. Teams and projects that agree on guidelines for defining variables (where to define certain types of variables) usually avoid variable precedence concerns. You should define each variable in one place. Determine where to define a variable, and keep it simple. For examples, see [Tips on where to set variables](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#variable-examples) . Some behavioral parameters that you can set in variables you can also set in Ansible configuration, as command-line options, and using playbook keywords. For example, you can define the user that Ansible uses to connect to remote devices as a variable with `ansible_user`, in a configuration file with `DEFAULT_REMOTE_USER`, as a command-line option with `-u`, and with the playbook keyword `remote_user`. If you define the same parameter in a variable and by another method, the variable overrides the other setting. This approach allows host-specific settings to override more general settings. For examples and more details on the precedence of these various settings, see [Controlling how Ansible behaves: precedence rules](https://docs.ansible.com/projects/ansible/latest/reference_appendices/general_precedence.html#general-precedence-rules) . ### [Understanding variable precedence](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#id44) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#understanding-variable-precedence "Link to this heading") Ansible does apply variable precedence, and you might have a use for it. Here is the order of precedence from least to greatest (the last listed variables override all other variables): > 1. Command-line values (for example, `-u my_user`, these are not variables) > > 2. Role defaults (as defined in [Role directory structure](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#role-directory-structure) > ) [\[1\]](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#id13) > > 3. Inventory file or script group vars [\[2\]](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#id14) > > 4. Inventory group\_vars/all [\[3\]](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#id15) > > 5. Playbook group\_vars/all [\[3\]](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#id15) > > 6. Inventory group\_vars/\* [\[3\]](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#id15) > > 7. Playbook group\_vars/\* [\[3\]](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#id15) > > 8. Inventory file or script host vars [\[2\]](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#id14) > > 9. Inventory host\_vars/\* [\[3\]](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#id15) > > 10. Playbook host\_vars/\* [\[3\]](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#id15) > > 11. Host facts and cached set\_facts [\[4\]](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#id16) > > 12. Play vars > > 13. Play vars\_prompt > > 14. Play vars\_files > > 15. Role vars (as defined in [Role directory structure](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#role-directory-structure) > ) > > 16. Block vars (for tasks in block only) > > 17. Task vars (for the task only) > > 18. include\_vars > > 19. Registered vars and set\_facts > > 20. Role (and include\_role) params > > 21. include params > > 22. Extra vars (for example, `-e "user=my_user"`)(always win precedence) > In general, Ansible gives precedence to variables that were defined more recently, more actively, and with more explicit scope. Variables in the defaults folder inside a role are easily overridden. Anything in the vars directory of the role overrides previous versions of that variable in the namespace. Host or inventory variables override role defaults, but explicit includes such as the vars directory or an `include_vars` task override inventory variables. Ansible merges different variables set in inventory so that more specific settings override more generic settings. For example, `ansible_ssh_user` specified as a group\_var is overridden by `ansible_user` specified as a host\_var. For details about the precedence of variables set in inventory, see [How variables are merged](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#how-we-merge) . Footnotes Note Within any section, redefining a var overrides the previous instance. If multiple groups have the same variable, the last one loaded wins. If you define a variable twice in a play’s `vars:` section, the second one wins. The previous text describes the default config `hash_behavior=replace`. Switch to `merge` to overwrite only partially. ### [Scoping variables](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#id45) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#scoping-variables "Link to this heading") You can decide where to set a variable based on the scope you want that value to have. Ansible has three main scopes: > * Global: this is set by config, environment variables and the command line > > * Play: each play and contained structures, vars entries (vars; vars\_files; vars\_prompt), role defaults and vars. > > * Host: variables directly associated to a host, like inventory, include\_vars, facts or registered task outputs > Inside a template, you automatically have access to all variables that are in scope for a host, plus any registered variables, facts, and magic variables. ### [Tips on where to set variables](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#id46) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#tips-on-where-to-set-variables "Link to this heading") You should choose where to define a variable based on the kind of control you might want over values. Set variables in inventory that deal with geography or behavior. Since groups are frequently the entity that maps roles to hosts, you can often set variables on the group instead of defining them on a role. Remember that child groups override parent groups, and host variables override group variables. See [Defining variables in inventory](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#define-variables-in-inventory) for details on setting host and group variables. Set common defaults in a `group_vars/all` file. See [Organizing host and group variables](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#splitting-out-vars) for details on how to organize host and group variables in your inventory. You generally place group variables alongside your inventory file, but they can also be returned by dynamic inventory (see [Working with dynamic inventory](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_dynamic_inventory.html#intro-dynamic-inventory) ) or defined in AWX or on the [Red Hat Ansible Automation Platform](https://docs.ansible.com/projects/ansible/latest/reference_appendices/tower.html#ansible-platform) from the UI or API: \--- \# file: /etc/ansible/group\_vars/all \# this is the site wide default ntp\_server: default-time.example.com Set location-specific variables in `group_vars/my_location` files. All groups are children of the `all` group, so variables set here override those set in `group_vars/all`: \--- \# file: /etc/ansible/group\_vars/boston ntp\_server: boston-time.example.com If one host used a different NTP server, you could set that in a host\_vars file, which would override the group variable: \--- \# file: /etc/ansible/host\_vars/xyz.boston.example.com ntp\_server: override.example.com Set defaults in roles to avoid undefined-variable errors. If you share your roles, other users can rely on the reasonable defaults you added in the `roles/x/defaults/main.yml` file, or they can easily override those values in inventory or at the command line. See [Roles](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#playbooks-reuse-roles) for more info. For example: \--- \# file: roles/x/defaults/main.yml \# if no other value is supplied in inventory or as a parameter, this value will be used http\_port: 80 Set variables in roles to ensure a value is used in that role and is not overridden by inventory variables. If you are not sharing your role with others, you can define app-specific behaviors like ports this way, in `roles/x/vars/main.yml`. If you are sharing roles with others, putting variables here makes them harder to override, although they can still be overridden by passing a parameter to the role or setting a variable with `-e`: \--- \# file: roles/x/vars/main.yml \# this will absolutely be used in this role http\_port: 80 Pass variables as parameters when you call roles for maximum clarity, flexibility, and visibility. This approach overrides any defaults that exist for a role. For example: roles: \- role: apache vars: http\_port: 8080 When you read this playbook, it is clear that you have chosen to set a variable or override a default. You can also pass multiple values, which allows you to run the same role multiple times. See [Running a role multiple times in one play](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#run-role-twice) for more details. For example: roles: \- role: app\_user vars: myname: Ian \- role: app\_user vars: myname: Terry \- role: app\_user vars: myname: Graham \- role: app\_user vars: myname: John Variables set in one role are available to later roles. You can set variables in the role’s `vars` directory (as defined in [Role directory structure](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#role-directory-structure) ) and use them in other roles and elsewhere in your playbook: roles: \- role: common\_settings \- role: something vars: foo: 12 \- role: something\_else There are some protections in place to avoid the need to namespace variables. In this example, variables defined in ‘common\_settings’ are available to ‘something’ and ‘something\_else’ tasks, but tasks in ‘something’ have foo set at 12, even if ‘common\_settings’ sets foo to 20. Instead of worrying about variable precedence, we encourage you to think about how easily or how often you want to override a variable when deciding where to set it. If you are not sure what other variables are defined and you need a particular value, use `--extra-vars` (`-e`) to override all other variables. [Using advanced variable syntax](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#id47) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#using-advanced-variable-syntax "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ For information about advanced YAML syntax used to declare variables and have more control over the data placed in YAML files used by Ansible, see [Advanced playbook syntax](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_advanced_syntax.html#playbooks-advanced-syntax) . See also [Ansible playbooks](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_intro.html#about-playbooks) An introduction to playbooks [Conditionals](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_conditionals.html#playbooks-conditionals) Conditional statements in playbooks [Using filters to manipulate data](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_filters.html#playbooks-filters) Jinja2 filters and their uses [Loops](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_loops.html#playbooks-loops) Looping in playbooks [Roles](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#playbooks-reuse-roles) Playbook organization by roles [General tips](https://docs.ansible.com/projects/ansible/latest/tips_tricks/ansible_tips_tricks.html#tips-and-tricks) Tips and tricks for playbooks [Special Variables](https://docs.ansible.com/projects/ansible/latest/reference_appendices/special_variables.html#special-variables) List of special variables [Communication](https://docs.ansible.com/projects/ansible/latest/community/communication.html#communication) Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide --- # Ansible 6 Porting Guide — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * [Ansible Porting Guides](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guides.html) * Ansible 6 Porting Guide * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/porting_guides/porting_guide_6.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Ansible 6 Porting Guide[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#ansible-6-porting-guide "Link to this heading") ================================================================================================================================================================ Ansible 6 is based on Ansible-core 2.13. We suggest you read this page along with the [Ansible 6 Changelog](https://github.com/ansible-community/ansible-build-data/blob/main/6/CHANGELOG-v6.rst) to understand what updates you may need to make. [Playbook](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id78) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#playbook "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * Templating - You can no longer perform arithmetic and concatenation operations outside of the jinja template. The following statement will need to be rewritten to produce `[1, 2]`: > \- name: Prior to 2.13 > debug: > msg: '\[1\] + {{ \[2\] }}' > > \- name: 2.13 and forward > debug: > msg: '{{ \[1\] + \[2\] }}' * The return value of the `__repr__` method of an undefined variable represented by the `AnsibleUndefined` object changed. `{{ '%r'|format(undefined_variable) }}` returns `AnsibleUndefined(hint=None, obj=missing, name='undefined_variable')` in 2.13 as opposed to just `AnsibleUndefined` in versions 2.12 and prior. * The `finalize` method is no longer exposed in the globals for use in templating. To convert `None` to an empty string the following expression can be used: `{{ value if value is not none }}`. [Command Line](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id79) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#command-line "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- No notable changes [Deprecated](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id80) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#deprecated "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ No notable changes [Modules](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id81) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#modules "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ * To use ansible-core 2.13 for module execution, you must use Python 2 version 2.7 or Python 3 version 3.5 or newer. Any code utilizing `ansible.module_utils.basic` will not function with lower Python versions. ### [Modules removed](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id82) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#modules-removed "Link to this heading") The following modules no longer exist: * No notable changes ### [Deprecation notices](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id83) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#deprecation-notices "Link to this heading") No notable changes ### [Noteworthy module changes](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id84) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#noteworthy-module-changes "Link to this heading") No notable changes ### [Breaking Changes](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id85) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#breaking-changes "Link to this heading") * `ansible.module_utils.urls.fetch_url` will now return the captured `HTTPError` exception as `r`. `HTTPError` is a response like object that can offer more information to module authors. Modules should rely on `info['status'] >= 400` to determine if there was a failure, instead of using `r is None` or catching `AttributeError` when attempting `r.read()`. [Plugins](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id86) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#plugins "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ No notable changes [Porting custom scripts](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id87) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#porting-custom-scripts "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ No notable changes [Networking](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id88) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#networking "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ No notable changes [Porting Guide for v6.7.0](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id89) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#porting-guide-for-v6-7-0 "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [Known Issues](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id90) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#known-issues "Link to this heading") #### community.routeros[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#community-routeros "Link to this heading") * api\_modify - when limits for entries in `queue tree` are defined as human readable - for example `25M` -, the configuration will be correctly set in ROS, but the module will indicate the item is changed on every run even when there was no change done. This is caused by the ROS API which returns the number in bytes - for example `25000000` (which is inconsistent with the CLI behavior). In order to mitigate that, the limits have to be defined in bytes (those will still appear as human readable in the ROS CLI) ([https://github.com/ansible-collections/community.routeros/pull/131](https://github.com/ansible-collections/community.routeros/pull/131) ). * api\_modify, api\_info - `routing ospf area`, `routing ospf area range`, `routing ospf instance`, `routing ospf interface-template` paths are not fully implemented for ROS6 due to the significant changes between ROS6 and ROS7 ([https://github.com/ansible-collections/community.routeros/pull/131](https://github.com/ansible-collections/community.routeros/pull/131) ). ### [Major Changes](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id91) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#major-changes "Link to this heading") #### cisco.meraki[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#cisco-meraki "Link to this heading") * meraki\_mr\_l7\_firewall - New module * meraki\_webhook\_payload\_template - New module #### community.zabbix[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#community-zabbix "Link to this heading") * all modules are opting away from zabbix-api and using httpapi ansible.netcommon plugin. We will support zabbix-api for backwards compatibility until next major release. See our README.md for more information about how to migrate * zabbix\_agent and zabbix\_proxy roles are opting away from zabbix-api and use httpapi ansible.netcommon plugin. We will support zabbix-api for backwards compatibility until next major release. See our README.md for more information about how to migrate #### containers.podman[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#containers-podman "Link to this heading") * New become plugin - podman\_unshare * Podman generate systemd module #### fortinet.fortimanager[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#fortinet-fortimanager "Link to this heading") * Fix compatibility issue for ansible 2.9.x and ansible-base 2.10.x. * support Ansible changelogs. #### fortinet.fortios[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#fortinet-fortios "Link to this heading") * Support FortiOS v7.0.6, v7.0.7, v7.0.8, v7.2.1, v7.2.2. ### [Deprecated Features](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id92) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#deprecated-features "Link to this heading") #### community.general[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#community-general "Link to this heading") * Please note that some tools, like the VScode plugin ([https://github.com/ansible/vscode-ansible/issues/573](https://github.com/ansible/vscode-ansible/issues/573) ), or `ansible-doc --list --type module`, suggest to replace the correct FQCNs for modules and actions in community.general with internal names that have more than three components. For example, `community.general.ufw` is suggested to be replaced by `community.general.system.ufw`. While these longer names do work, they are considered **internal names** by the collection and are subject to change and be removed at all time. They **will** be removed in community.general 6.0.0 and result in deprecation messages. Avoid using these internal names, and use general three-component FQCNs (`community.general.`) instead ([https://github.com/ansible-collections/community.general/pull/5373](https://github.com/ansible-collections/community.general/pull/5373) ). [Porting Guide for v6.6.0](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id93) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#porting-guide-for-v6-6-0 "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [Added Collections](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id94) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#added-collections "Link to this heading") * lowlydba.sqlserver (version 1.0.4) ### [Known Issues](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id95) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id1 "Link to this heading") #### community.routeros[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id2 "Link to this heading") * The `community.routeros.command` module claims to support check mode. Since it cannot judge whether the commands executed modify state or not, this behavior is incorrect. Since this potentially breaks existing playbooks, we will not change this behavior until community.routeros 3.0.0. ### [Breaking Changes](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id96) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id3 "Link to this heading") #### community.general[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id4 "Link to this heading") * newrelic\_deployment - `revision` is required for v2 API ([https://github.com/ansible-collections/community.general/pull/5341](https://github.com/ansible-collections/community.general/pull/5341) ). ### [Major Changes](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id97) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id5 "Link to this heading") #### community.general[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id6 "Link to this heading") * newrelic\_deployment - removed New Relic v1 API, added support for v2 API ([https://github.com/ansible-collections/community.general/pull/5341](https://github.com/ansible-collections/community.general/pull/5341) ). #### fortinet.fortimanager[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id7 "Link to this heading") * Many fixes for Ansible sanity test warnings & errors. * Support FortiManager Schema 7.2.0 , 98 new modules ### [Deprecated Features](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id98) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id8 "Link to this heading") * The mellanox.onyx collection is considered unmaintained and will be removed from Ansible 8 if no one starts maintaining it again before Ansible 8. See [the removal process for details on how this works](https://github.com/ansible-collections/overview/blob/main/removal_from_ansible.rst#cancelling-removal-of-an-unmaintained-collection) ([https://github.com/ansible-community/community-topics/issues/136](https://github.com/ansible-community/community-topics/issues/136) ). #### cisco.mso[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#cisco-mso "Link to this heading") * The mso\_schema\_template\_contract\_filter contract\_filter\_type attribute is deprecated. The value is now deduced from filter\_type. #### community.general[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id9 "Link to this heading") * ArgFormat module utils - deprecated along `CmdMixin`, in favor of the `cmd_runner_fmt` module util ([https://github.com/ansible-collections/community.general/pull/5370](https://github.com/ansible-collections/community.general/pull/5370) ). * CmdMixin module utils - deprecated in favor of the `CmdRunner` module util ([https://github.com/ansible-collections/community.general/pull/5370](https://github.com/ansible-collections/community.general/pull/5370) ). * CmdModuleHelper module utils - deprecated in favor of the `CmdRunner` module util ([https://github.com/ansible-collections/community.general/pull/5370](https://github.com/ansible-collections/community.general/pull/5370) ). * CmdStateModuleHelper module utils - deprecated in favor of the `CmdRunner` module util ([https://github.com/ansible-collections/community.general/pull/5370](https://github.com/ansible-collections/community.general/pull/5370) ). * django\_manage - support for Django releases older than 4.1 has been deprecated and will be removed in community.general 9.0.0 ([https://github.com/ansible-collections/community.general/pull/5400](https://github.com/ansible-collections/community.general/pull/5400) ). * django\_manage - support for the commands `cleanup`, `syncdb` and `validate` that have been deprecated in Django long time ago will be removed in community.general 9.0.0 ([https://github.com/ansible-collections/community.general/pull/5400](https://github.com/ansible-collections/community.general/pull/5400) ). * django\_manage - the behavior of “creating the virtual environment when missing” is being deprecated and will be removed in community.general version 9.0.0 ([https://github.com/ansible-collections/community.general/pull/5405](https://github.com/ansible-collections/community.general/pull/5405) ). * newrelic\_deployment - `appname` and `environment` are no longer valid options in the v2 API. They will be removed in community.general 7.0.0 ([https://github.com/ansible-collections/community.general/pull/5341](https://github.com/ansible-collections/community.general/pull/5341) ). [Porting Guide for v6.5.0](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id99) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#porting-guide-for-v6-5-0 "Link to this heading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [Major Changes](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id100) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id10 "Link to this heading") #### infoblox.nios\_modules[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#infoblox-nios-modules "Link to this heading") * Feature for extra layer security , with cert and key parameters in playbooks for authenticating using certificate and key `*.pem` file absolute path [#154](https://github.com/infobloxopen/infoblox-ansible/pull/154) * Fix to remove issue causing due to template attr in deleting network using Ansible module nios network [#147](https://github.com/infobloxopen/infoblox-ansible/pull/147) ### [Deprecated Features](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id101) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id13 "Link to this heading") * The dellemc.os10 collection is considered unmaintained and will be removed from Ansible 8 if no one starts maintaining it again before Ansible 8. See [the removal process for details on how this works](https://github.com/ansible-collections/overview/blob/main/removal_from_ansible.rst#cancelling-removal-of-an-unmaintained-collection) ([https://github.com/ansible-community/community-topics/issues/134](https://github.com/ansible-community/community-topics/issues/134) ). * The dellemc.os6 collection is considered unmaintained and will be removed from Ansible 8 if no one starts maintaining it again before Ansible 8. See [the removal process for details on how this works](https://github.com/ansible-collections/overview/blob/main/removal_from_ansible.rst#cancelling-removal-of-an-unmaintained-collection) ([https://github.com/ansible-community/community-topics/issues/132](https://github.com/ansible-community/community-topics/issues/132) ). * The dellemc.os9 collection is considered unmaintained and will be removed from Ansible 8 if no one starts maintaining it again before Ansible 8. See [the removal process for details on how this works](https://github.com/ansible-collections/overview/blob/main/removal_from_ansible.rst#cancelling-removal-of-an-unmaintained-collection) ([https://github.com/ansible-community/community-topics/issues/133](https://github.com/ansible-community/community-topics/issues/133) ). #### community.general[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id14 "Link to this heading") * lxc\_container - the module will no longer make any effort to support Python 2 ([https://github.com/ansible-collections/community.general/pull/5304](https://github.com/ansible-collections/community.general/pull/5304) ). [Porting Guide for v6.4.0](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id102) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#porting-guide-for-v6-4-0 "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [Added Collections](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id103) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id15 "Link to this heading") * inspur.ispim (version 1.0.1) * vultr.cloud (version 1.1.0) ### [Deprecated Features](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id104) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id16 "Link to this heading") #### community.general[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id17 "Link to this heading") * proxmox - deprecated the current `unprivileged` default value, will be changed to `true` in community.general 7.0.0 ([https://github.com/pull/5224](https://github.com/pull/5224) ). [Porting Guide for v6.3.0](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id105) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#porting-guide-for-v6-3-0 "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [Major Changes](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id106) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id18 "Link to this heading") #### community.mysql[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#community-mysql "Link to this heading") * mysql\_db - the `pipefail` argument’s default value will be changed to `true` in community.mysql 4.0.0. If your target machines do not use `bash` as a default interpreter, set `pipefail` to `false` explicitly. However, we strongly recommend setting up `bash` as a default and `pipefail=true` as it will protect you from getting broken dumps you don’t know about ([https://github.com/ansible-collections/community.mysql/issues/407](https://github.com/ansible-collections/community.mysql/issues/407) ). #### fortinet.fortios[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id19 "Link to this heading") * Support Diff feature in check\_mode. * Support Fortios 7.2.0. ### [Deprecated Features](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id107) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id20 "Link to this heading") * The google.cloud collection is considered unmaintained and will be removed from Ansible 8 if no one starts maintaining it again before Ansible 8. See [the removal process for details on how this works](https://github.com/ansible-collections/overview/blob/main/removal_from_ansible.rst#cancelling-removal-of-an-unmaintained-collection) ([https://github.com/ansible-community/community-topics/issues/105](https://github.com/ansible-community/community-topics/issues/105) ). * The servicenow.servicenow collection has been deprecated by its maintainers ([https://github.com/ServiceNowITOM/servicenow-ansible/pull/69](https://github.com/ServiceNowITOM/servicenow-ansible/pull/69) ) and will be removed from Ansible 7. It can still be installed manually, but it is suggested to switch to [servicenow.itsm](https://galaxy.ansible.com/servicenow/itsm) instead ([https://github.com/ansible-community/community-topics/issues/124](https://github.com/ansible-community/community-topics/issues/124) ). [Porting Guide for v6.2.0](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id108) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#porting-guide-for-v6-2-0 "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [Added Collections](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id109) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id21 "Link to this heading") * ibm.spectrum\_virtualize (version 1.9.0) ### [Known Issues](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id110) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id22 "Link to this heading") #### netapp.ontap[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#netapp-ontap "Link to this heading") * na\_ontap\_snapshot - added documentation to use UTC format for `expiry_time`. ### [Major Changes](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id111) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id23 "Link to this heading") #### community.postgresql[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#community-postgresql "Link to this heading") * postgresql\_user - the `groups` argument has been deprecated and will be removed in `community.postgresql 3.0.0`. Please use the `postgresql_membership` module to specify group/role memberships instead ([https://github.com/ansible-collections/community.postgresql/issues/277](https://github.com/ansible-collections/community.postgresql/issues/277) ). ### [Deprecated Features](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id112) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id24 "Link to this heading") #### community.hashi\_vault[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#community-hashi-vault "Link to this heading") * vault\_kv2\_get lookup - the `engine_mount_point option` in the `vault_kv2_get` lookup only will change its default from `kv` to `secret` in community.hashi\_vault version 4.0.0 ([https://github.com/ansible-collections/community.hashi\_vault/issues/279](https://github.com/ansible-collections/community.hashi_vault/issues/279) ). [Porting Guide for v6.1.0](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id113) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#porting-guide-for-v6-1-0 "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [Added Collections](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id114) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id25 "Link to this heading") * purestorage.fusion (version 1.0.2) ### [Known Issues](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id115) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id26 "Link to this heading") #### dellemc.openmanage[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#dellemc-openmanage "Link to this heading") * idrac\_user - Issue(192043) The module may error out with the message `unable to perform the import or export operation because there are pending attribute changes or a configuration job is in progress`. Wait for the job to complete and run the task again. * ome\_application\_alerts\_smtp - Issue(212310) - The module does not provide a proper error message if the destination\_address is more than 255 characters. * ome\_application\_alerts\_syslog - Issue(215374) - The module does not provide a proper error message if the destination\_address is more than 255 characters. * ome\_device\_local\_access\_configuration - Issue(215035) - The module reports `Successfully updated the local access setting` if an unsupported value is provided for the parameter timeout\_limit. However, this value is not actually applied on OpenManage Enterprise Modular. * ome\_device\_local\_access\_configuration - Issue(217865) - The module does not display a proper error message if an unsupported value is provided for the user\_defined and lcd\_language parameters. * ome\_device\_network\_services - Issue(212681) - The module does not provide a proper error message if unsupported values are provided for the parameters- port\_number, community\_name, max\_sessions, max\_auth\_retries, and idle\_timeout. * ome\_device\_power\_settings - Issue(212679) - The module displays the following message if the value provided for the parameter `power_cap` is not within the supported range of 0 to 32767, `Unable to complete the request because PowerCap does not exist or is not applicable for the resource URI.` * ome\_device\_quick\_deploy - Issue(216352) - The module does not display a proper error message if an unsupported value is provided for the ipv6\_prefix\_length and vlan\_id parameters. * ome\_smart\_fabric\_uplink - Issue(186024) - The module does not allow the creation of multiple uplinks of the same name even though it is supported by OpenManage Enterprise Modular. If an uplink is created using the same name as an existing uplink, the existing uplink is modified. ### [Major Changes](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id116) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id27 "Link to this heading") #### chocolatey.chocolatey[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#chocolatey-chocolatey "Link to this heading") * win\_chocolatey - Added bootstrap\_script option to allow users to target a script URL for installing Chocolatey on clients. * win\_chocolatey\_facts - Added outdated packages list to data returned. #### infoblox.nios\_modules[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id28 "Link to this heading") * Update text field of TXT Record [#128](https://github.com/infobloxopen/infoblox-ansible/pull/128) * Update operation using old\_name and new\_name for the object with dummy name in old\_name (which does not exist in system) will not create a new object in the system. An error will be thrown stating the object does not exist in the system [#129](https://github.com/infobloxopen/infoblox-ansible/pull/129) ### [Deprecated Features](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id117) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id31 "Link to this heading") #### cisco.ios[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#cisco-ios "Link to this heading") * Deprecated ios\_linkagg\_module in favor of ios\_lag\_interfaces. #### community.aws[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#community-aws "Link to this heading") * aws\_codebuild - The `tags` parameter currently uses a non-standard format and has been deprecated. In release 6.0.0 this parameter will accept a simple key/value pair dictionary instead of the current list of dictionaries. It is recommended to migrate to using the resource\_tags parameter which already accepts the simple dictionary format ([https://github.com/ansible-collections/community.aws/pull/1221](https://github.com/ansible-collections/community.aws/pull/1221) ). * route53\_info - The CamelCase return values for `HostedZones`, `ResourceRecordSets`, and `HealthChecks` have been deprecated, in the future release you must use snake\_case return values `hosted_zones`, `resource_record_sets`, and `health_checks` instead respectively”. #### community.crypto[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#community-crypto "Link to this heading") * Support for Ansible 2.9 and ansible-base 2.10 is deprecated, and will be removed in the next major release (community.crypto 3.0.0). Some modules might still work with these versions afterwards, but we will no longer keep compatibility code that was needed to support them ([https://github.com/ansible-collections/community.crypto/pull/460](https://github.com/ansible-collections/community.crypto/pull/460) ). #### community.docker[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#community-docker "Link to this heading") * Support for Docker API version 1.20 to 1.24 has been deprecated and will be removed in community.docker 3.0.0. The first Docker version supporting API version 1.25 was Docker 1.13, released in January 2017. This affects the modules `docker_container`, `docker_container_exec`, `docker_container_info`, `docker_compose`, `docker_login`, `docker_image`, `docker_image_info`, `docker_image_load`, `docker_host_info`, `docker_network`, `docker_network_info`, `docker_node_info`, `docker_swarm_info`, `docker_swarm_service`, `docker_swarm_service_info`, `docker_volume_info`, and `docker_volume`, whose minimally supported API version is between 1.20 and 1.24 ([https://github.com/ansible-collections/community.docker/pull/396](https://github.com/ansible-collections/community.docker/pull/396) ). * Support for Python 2.6 is deprecated and will be removed in the next major release (community.docker 3.0.0). Some modules might still work with Python 2.6, but we will no longer try to ensure compatibility ([https://github.com/ansible-collections/community.docker/pull/388](https://github.com/ansible-collections/community.docker/pull/388) ). #### community.general[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id32 "Link to this heading") * cmd\_runner module utils - deprecated `fmt` in favour of `cmd_runner_fmt` as the parameter format object ([https://github.com/ansible-collections/community.general/pull/4777](https://github.com/ansible-collections/community.general/pull/4777) ). [Porting Guide for v6.0.0](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id118) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#porting-guide-for-v6-0-0 "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [Added Collections](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id119) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id33 "Link to this heading") * cisco.dnac (version 6.4.0) * community.sap (version 1.0.0) * community.sap\_libs (version 1.1.0) * vmware.vmware\_rest (version 2.1.5) ### [Known Issues](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id120) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id34 "Link to this heading") #### Ansible-core[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#ansible-core "Link to this heading") * get\_url - document `check_mode` correctly with unreliable changed status ([https://github.com/ansible/ansible/issues/65687](https://github.com/ansible/ansible/issues/65687) ). #### ansible.netcommon[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#ansible-netcommon "Link to this heading") * eos - When using eos modules on Ansible 2.9, tasks will occasionally fail with `import_modules` enabled. This can be avoided by setting `import_modules: no` #### community.general[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id35 "Link to this heading") * pacman - `update_cache` cannot differentiate between up to date and outdated package lists and will report `changed` in both situations ([https://github.com/ansible-collections/community.general/pull/4318](https://github.com/ansible-collections/community.general/pull/4318) ). * pacman - binaries specified in the `executable` parameter must support `--print-format` in order to be used by this module. In particular, AUR helper `yay` is known not to currently support it ([https://github.com/ansible-collections/community.general/pull/4312](https://github.com/ansible-collections/community.general/pull/4312) ). #### dellemc.openmanage[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id36 "Link to this heading") * idrac\_user - Issue(192043) The module may error out with the message `unable to perform the import or export operation because there are pending attribute changes or a configuration job is in progress`. Wait for the job to complete and run the task again. * ome\_application\_alerts\_smtp - Issue(212310) - The module does not provide a proper error message if the destination\_address is more than 255 characters. * ome\_application\_alerts\_syslog - Issue(215374) - The module does not provide a proper error message if the destination\_address is more than 255 characters. * ome\_application\_console\_preferences - Issue(224690) - The module does not display a proper error message when an unsupported value is provided for the parameters report\_row\_limit, email\_sender\_settings, and metric\_collection\_settings, and the value is applied on OpenManage Enterprise. * ome\_device\_local\_access\_configuration - Issue(215035) - The module reports `Successfully updated the local access setting` if an unsupported value is provided for the parameter timeout\_limit. However, this value is not actually applied on OpenManage Enterprise Modular. * ome\_device\_local\_access\_configuration - Issue(217865) - The module does not display a proper error message if an unsupported value is provided for the user\_defined and lcd\_language parameters. * ome\_device\_network\_services - Issue(212681) - The module does not provide a proper error message if unsupported values are provided for the parameters- port\_number, community\_name, max\_sessions, max\_auth\_retries, and idle\_timeout. * ome\_device\_power\_settings - Issue(212679) - The module displays the following message if the value provided for the parameter `power_cap` is not within the supported range of 0 to 32767, `Unable to complete the request because PowerCap does not exist or is not applicable for the resource URI.` * ome\_device\_power\_settings - Issue(212679) - The module errors out with the following message if the value provided for the parameter `power_cap` is not within the supported range of 0 to 32767, `Unable to complete the request because PowerCap does not  exist or is not applicable for the resource URI.` * ome\_device\_power\_settings - Issue(212679) - The module errors out with the following message if the value provided for the parameter `power_cap` is not within the supported range of 0 to 32767, `Unable to complete the request because PowerCap does not exist or is not applicable for the resource URI.` * ome\_device\_quick\_deploy - Issue(216352) - The module does not display a proper error message if an unsupported value is provided for the ipv6\_prefix\_length and vlan\_id parameters. * ome\_smart\_fabric\_uplink - Issue(186024) - The module does not allow the creation of multiple uplinks of the same name even though it is supported by OpenManage Enterprise Modular. If an uplink is created using the same name as an existing uplink, the existing uplink is modified. #### purestorage.flasharray[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#purestorage-flasharray "Link to this heading") * purefa\_admin - Once max\_login and lockout have been set there is currently no way to rest these to zero except through the FlashArray GUI ### [Breaking Changes](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id121) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id37 "Link to this heading") #### Ansible-core[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id38 "Link to this heading") * Module Python Dependency - Drop support for Python 2.6 in module execution. * Templating - it is no longer allowed to perform arithmetic and concatenation operations outside of the jinja template ([https://github.com/ansible/ansible/pull/75587](https://github.com/ansible/ansible/pull/75587) ) * The `finalize` method is no longer exposed in the globals for use in templating. #### amazon.aws[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#amazon-aws "Link to this heading") * aws\_caller\_facts - Remove deprecated `aws_caller_facts` alias. Please use `aws_caller_info` instead. * cloudformation\_facts - Remove deprecated `cloudformation_facts` alias. Please use `cloudformation_info` instead. * ec2\_ami\_facts - Remove deprecated `ec2_ami_facts` alias. Please use `ec2_ami_info` instead. * ec2\_eni\_facts - Remove deprecated `ec2_eni_facts` alias. Please use `ec2_eni_info` instead. * ec2\_group\_facts - Remove deprecated `ec2_group_facts` alias. Please use `ec2_group_info` instead. * ec2\_instance\_facts - Remove deprecated `ec2_instance_facts` alias. Please use `ec2_instance_info` instead. * ec2\_snapshot\_facts - Remove deprecated `ec2_snapshot_facts` alias. Please use `ec2_snapshot_info` instead. * ec2\_vol\_facts - Remove deprecated `ec2_vol_facts` alias. Please use `ec2_vol_info` instead. * ec2\_vpc\_dhcp\_option\_facts - Remove deprecated `ec2_vpc_dhcp_option_facts` alias. Please use `ec2_vpc_dhcp_option_info` instead. * ec2\_vpc\_endpoint\_facts - Remove deprecated `ec2_vpc_endpoint_facts` alias. Please use `ec2_vpc_endpoint_info` instead. * ec2\_vpc\_igw\_facts - Remove deprecated `ec2_vpc_igw_facts` alias. Please use `ec2_vpc_igw_info` instead. * ec2\_vpc\_nat\_gateway\_facts - Remove deprecated `ec2_vpc_nat_gateway_facts` alias. Please use `ec2_vpc_nat_gateway_info` instead. * ec2\_vpc\_net\_facts - Remove deprecated `ec2_vpc_net_facts` alias. Please use `ec2_vpc_net_info` instead. * ec2\_vpc\_route\_table\_facts - Remove deprecated `ec2_vpc_route_table_facts` alias. Please use `ec2_vpc_route_table_info` instead. * ec2\_vpc\_subnet\_facts - Remove deprecated `ec2_vpc_subnet_facts` alias. Please use `ec2_vpc_subnet_info` instead. #### ansible.netcommon[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id39 "Link to this heading") * httpapi - Change default value of `import_modules` option from `no` to `yes` * netconf - Change default value of `import_modules` option from `no` to `yes` * network\_cli - Change default value of `import_modules` option from `no` to `yes` #### arista.eos[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#arista-eos "Link to this heading") * eos\_command - new suboption `version` of parameter `command`, which controls the JSON response version. Previously the value was assumed to be “latest” for network\_cli and “1” for httpapi, but the default will now be “latest” for both connections. This option is also available for use in modules making their own device requests with `plugins.module_utils.network.eos.eos.run_commands()` with the same new default behavior. ([https://github.com/ansible-collections/arista.eos/pull/258](https://github.com/ansible-collections/arista.eos/pull/258) ). * httpapi - the `eos_use_sessions` option is now a boolean instead of an integer. #### community.aws[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id40 "Link to this heading") * aws\_acm\_facts - Remove deprecated alias `aws_acm_facts`. Please use `aws_acm_info` instead. * aws\_kms\_facts - Remove deprecated alias `aws_kms_facts`. Please use `aws_kms_info` instead. * aws\_kms\_info - Deprecated `keys_attr` field is now ignored ([https://github.com/ansible-collections/community.aws/pull/838](https://github.com/ansible-collections/community.aws/pull/838) ). * aws\_region\_facts - Remove deprecated alias `aws_region_facts`. Please use `aws_region_info` instead. * aws\_s3\_bucket\_facts - Remove deprecated alias `aws_s3_bucket_facts`. Please use `aws_s3_bucket_info` instead. * aws\_sgw\_facts - Remove deprecated alias `aws_sgw_facts`. Please use `aws_sgw_info` instead. * aws\_waf\_facts - Remove deprecated alias `aws_waf_facts`. Please use `aws_waf_info` instead. * cloudfront\_facts - Remove deprecated alias `cloudfront_facts`. Please use `cloudfront_info` instead. * cloudwatchlogs\_log\_group\_facts - Remove deprecated alias `cloudwatchlogs_log_group_facts`. Please use `cloudwatchlogs_log_group_info` instead. * dynamodb\_table - deprecated updates currently ignored for primary keys and global\_all indexes will now result in a failure. ([https://github.com/ansible-collections/community.aws/pull/837](https://github.com/ansible-collections/community.aws/pull/837) ). * ec2\_asg\_facts - Remove deprecated alias `ec2_asg_facts`. Please use `ec2_asg_info` instead. * ec2\_customer\_gateway\_facts - Remove deprecated alias `ec2_customer_gateway_facts`. Please use `ec2_customer_gateway_info` instead. * ec2\_eip\_facts - Remove deprecated alias `ec2_eip_facts`. Please use `ec2_eip_info` instead. * ec2\_elb\_facts - Remove deprecated alias `ec2_elb_facts`. Please use `ec2_elb_info` instead. * ec2\_elb\_info - The `ec2_elb_info` module has been removed. Please use `the ``elb_classic_lb_info` module. * ec2\_lc\_facts - Remove deprecated alias `ec2_lc_facts`. Please use `ec2_lc_info` instead. * ec2\_placement\_group\_facts - Remove deprecated alias `ec2_placement_group_facts`. Please use `ec2_placement_group_info` instead. * ec2\_vpc\_nacl\_facts - Remove deprecated alias `ec2_vpc_nacl_facts`. Please use `ec2_vpc_nacl_info` instead. * ec2\_vpc\_peering\_facts - Remove deprecated alias `ec2_vpc_peering_facts`. Please use `ec2_vpc_peering_info` instead. * ec2\_vpc\_route\_table\_facts - Remove deprecated alias `ec2_vpc_route_table_facts`. Please use `ec2_vpc_route_table_info` instead. * ec2\_vpc\_vgw\_facts - Remove deprecated alias `ec2_vpc_vgw_facts`. Please use `ec2_vpc_vgw_info` instead. * ec2\_vpc\_vpn\_facts - Remove deprecated alias `ec2_vpc_vpn_facts`. Please use `ec2_vpc_vpn_info` instead. * ecs\_service\_facts - Remove deprecated alias `ecs_service_facts`. Please use `ecs_service_info` instead. * ecs\_taskdefinition\_facts - Remove deprecated alias `ecs_taskdefinition_facts`. Please use `ecs_taskdefinition_info` instead. * efs\_facts - Remove deprecated alias `efs_facts`. Please use `efs_info` instead. * elasticache\_facts - Remove deprecated alias `elasticache_facts`. Please use `elasticache_info` instead. * elb\_application\_lb\_facts - Remove deprecated alias `elb_application_lb_facts`. Please use `elb_application_lb_info` instead. * elb\_classic\_lb\_facts - Remove deprecated alias `elb_classic_lb_facts`. Please use `elb_classic_lb_info` instead. * elb\_target\_facts - Remove deprecated alias `elb_target_facts`. Please use `elb_target_info` instead. * elb\_target\_group\_facts - Remove deprecated alias `elb_target_group_facts`. Please use `elb_target_group_info` instead. * iam - Removed deprecated `community.aws.iam` module. Please use `community.aws.iam_user`, `community.aws.iam_access_key` or `community.aws.iam_group` ([https://github.com/ansible-collections/community.aws/pull/839](https://github.com/ansible-collections/community.aws/pull/839) ). * iam\_cert\_facts - Remove deprecated alias `iam_cert_facts`. Please use `iam_cert_info` instead. * iam\_mfa\_device\_facts - Remove deprecated alias `iam_mfa_device_facts`. Please use `iam_mfa_device_info` instead. * iam\_role\_facts - Remove deprecated alias `iam_role_facts`. Please use `iam_role_info` instead. * iam\_server\_certificate\_facts - Remove deprecated alias `iam_server_certificate_facts`. Please use `iam_server_certificate_info` instead. * lambda\_facts - Remove deprecated module lambda\_facts\`\`. Please use `lambda_info` instead. * rds - Removed deprecated `community.aws.rds` module. Please use `community.aws.rds_instance` ([https://github.com/ansible-collections/community.aws/pull/839](https://github.com/ansible-collections/community.aws/pull/839) ). * rds\_instance\_facts - Remove deprecated alias `rds_instance_facts`. Please use `rds_instance_info` instead. * rds\_snapshot\_facts - Remove deprecated alias `rds_snapshot_facts`. Please use `rds_snapshot_info` instead. * redshift\_facts - Remove deprecated alias `redshift_facts`. Please use `redshift_info` instead. * route53\_facts - Remove deprecated alias `route53_facts`. Please use `route53_info` instead. #### community.general[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id41 "Link to this heading") * Parts of this collection do not work with ansible-core 2.11 on Python 3.12+. Please either upgrade to ansible-core 2.12+, or use Python 3.11 or earlier ([https://github.com/ansible-collections/community.general/pull/3988](https://github.com/ansible-collections/community.general/pull/3988) ). * The symbolic links used to implement flatmapping for all modules were removed and replaced by `meta/runtime.yml` redirects. This effectively breaks compatibility with Ansible 2.9 for all modules (without using their “long” names, which is discouraged and which can change without previous notice since they are considered an implementation detail) ([https://github.com/ansible-collections/community.general/pull/4548](https://github.com/ansible-collections/community.general/pull/4548) ). * a\_module test plugin - remove Ansible 2.9 compatibility code ([https://github.com/ansible-collections/community.general/pull/4548](https://github.com/ansible-collections/community.general/pull/4548) ). * archive - remove Ansible 2.9 compatibility code ([https://github.com/ansible-collections/community.general/pull/4548](https://github.com/ansible-collections/community.general/pull/4548) ). * git\_config - remove Ansible 2.9 and early ansible-base 2.10 compatibility code ([https://github.com/ansible-collections/community.general/pull/4548](https://github.com/ansible-collections/community.general/pull/4548) ). * java\_keystore - remove Ansible 2.9 compatibility code ([https://github.com/ansible-collections/community.general/pull/4548](https://github.com/ansible-collections/community.general/pull/4548) ). * lists\_mergeby and groupby\_as\_dict filter plugins - adjust filter plugin filename. This change is not visible to end-users, it only affects possible other collections importing Python paths ([https://github.com/ansible-collections/community.general/pull/4625](https://github.com/ansible-collections/community.general/pull/4625) ). * lists\_mergeby filter plugin - remove Ansible 2.9 compatibility code ([https://github.com/ansible-collections/community.general/pull/4548](https://github.com/ansible-collections/community.general/pull/4548) ). * maven\_artifact - remove Ansible 2.9 compatibility code ([https://github.com/ansible-collections/community.general/pull/4548](https://github.com/ansible-collections/community.general/pull/4548) ). * memcached cache plugin - remove Ansible 2.9 compatibility code ([https://github.com/ansible-collections/community.general/pull/4548](https://github.com/ansible-collections/community.general/pull/4548) ). * path\_join filter plugin shim - remove Ansible 2.9 compatibility code ([https://github.com/ansible-collections/community.general/pull/4548](https://github.com/ansible-collections/community.general/pull/4548) ). * redis cache plugin - remove Ansible 2.9 compatibility code ([https://github.com/ansible-collections/community.general/pull/4548](https://github.com/ansible-collections/community.general/pull/4548) ). * yarn - remove unsupported and unnecessary `--no-emoji` flag ([https://github.com/ansible-collections/community.general/pull/4662](https://github.com/ansible-collections/community.general/pull/4662) ). #### community.mysql[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id42 "Link to this heading") * mysql\_replication - remove `Is_Slave` and `Is_Master` return values (were replaced with `Is_Primary` and `Is_Replica` ([https://github.com/ansible-collections](https://github.com/ansible-collections) /community.mysql/issues/145). * mysql\_replication - remove the mode options values containing `master`/`slave` and the master\_use\_gtid option `slave_pos` (were replaced with corresponding `primary`/`replica` values) ([https://github.com/ansible-collections/community.mysql/issues/145](https://github.com/ansible-collections/community.mysql/issues/145) ). * mysql\_user - remove support for the REQUIRESSL special privilege as it has ben superseded by the tls\_requires option ([https://github.com/ansible-collections/community.mysql/discussions/121](https://github.com/ansible-collections/community.mysql/discussions/121) ). * mysql\_user - validate privileges using database engine directly ([https://github.com/ansible-collections/community.mysql/issues/234](https://github.com/ansible-collections/community.mysql/issues/234) [https://github.com/ansible-collections/community.mysql/pull/243](https://github.com/ansible-collections/community.mysql/pull/243) ). Do not validate privileges in this module anymore. #### community.vmware[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#community-vmware "Link to this heading") * The collection now requires at least ansible-core 2.11.0. Ansible 3 and before, and ansible-base versions are no longer supported. * vmware\_cluster\_drs - The default for `enable` has been changed from `false` to `true`. * vmware\_cluster\_drs - The parameter alias `enable_drs` has been removed, use `enable` instead. * vmware\_cluster\_ha - The default for `enable` has been changed from `false` to `true`. * vmware\_cluster\_ha - The parameter alias `enable_ha` has been removed, use `enable` instead. * vmware\_cluster\_vsan - The default for `enable` has been changed from `false` to `true`. * vmware\_cluster\_vsan - The parameter alias `enable_vsan` has been removed, use `enable` instead. * vmware\_guest - Virtualization Based Security has some requirements (`nested_virt`, `secure_boot` and `iommu`) that the module silently enabled. They have to be enabled explicitly now. #### dellemc.openmanage[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id43 "Link to this heading") * HTTPS SSL certificate validation is a **breaking change** and will require modification in the existing playbooks. Please refer to [SSL Certificate Validation](https://github.com/dell/dellemc-openmanage-ansible-modules#ssl-certificate-validation) section in the [README.md](https://github.com/dell/dellemc-openmanage-ansible-modules/blob/collections/README.md#SSL-Certificate-Validation) for modification to existing playbooks. #### theforeman.foreman[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#theforeman-foreman "Link to this heading") * Set use\_reports\_api default value to true for the inventory plugin * Support for Ansible 2.8 is removed ### [Major Changes](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id122) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id44 "Link to this heading") * Add a `ansible-community` CLI tool that allows to print the version of the Ansible community distribution. Use `ansible-community --version` to print this version. #### Ansible-core[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id45 "Link to this heading") * Jinja2 Controller Requirement - Jinja2 3.0.0 or newer is required for the control node (the machine that runs Ansible) ([https://github.com/ansible/ansible/pull/75881](https://github.com/ansible/ansible/pull/75881) ) * Templating - remove `safe_eval` in favor of using `NativeEnvironment` but utilizing `literal_eval` only in cases when `safe_eval` was used ([https://github.com/ansible/ansible/pull/75587](https://github.com/ansible/ansible/pull/75587) ) #### amazon.aws[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id46 "Link to this heading") * amazon.aws collection - The amazon.aws collection has dropped support for `botocore<1.19.0` and `boto3<1.16.0`. Most modules will continue to work with older versions of the AWS SDK, however compatibility with older versions of the SDK is not guaranteed and will not be tested. When using older versions of the SDK a warning will be emitted by Ansible ([https://github.com/ansible-collections/amazon.aws/pull/574](https://github.com/ansible-collections/amazon.aws/pull/574) ). #### ansible.netcommon[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id47 "Link to this heading") * cli\_parse - this module has been moved to the ansible.utils collection. `ansible.netcommon.cli_parse` will continue to work to reference the module in its new location, but this redirect will be removed in a future release * network\_cli - Change default value of ssh\_type option from paramiko to auto. This value will use libssh if the ansible-pylibssh module is installed, otherwise will fallback to paramiko. #### arista.eos[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id48 "Link to this heading") * Minimum required ansible.netcommon version is 2.5.1. * Updated base plugin references to ansible.netcommon. * eos\_facts - change default gather\_subset to min from !config ([https://github.com/ansible-collections/arista.eos/issues/306](https://github.com/ansible-collections/arista.eos/issues/306) ). #### chocolatey.chocolatey[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id49 "Link to this heading") * win\_chocolatey - Added choco\_args option to pass additional arguments directly to Chocolatey. #### cisco.asa[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#cisco-asa "Link to this heading") * Minimum required ansible.netcommon version is 2.5.1. * Updated base plugin references to ansible.netcommon. #### cisco.ios[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id50 "Link to this heading") * Minimum required ansible.netcommon version is 2.5.1. * Updated base plugin references to ansible.netcommon. * facts - default value for gather\_subset is changed to min instead of !config. #### cisco.iosxr[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#cisco-iosxr "Link to this heading") * Minimum required ansible.netcommon version is 2.5.1. * Updated base plugin references to ansible.netcommon. * facts - default value for gather\_subset is changed to min instead of !config. #### cisco.ise[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#cisco-ise "Link to this heading") * Update ciscoisesdk requirement to 1.2.0 * anc\_endpoint\_bulk\_monitor\_status\_info - change return value, it returns BulkStatus content. * anc\_policy\_bulk\_monitor\_status\_info - change return value, it returns BulkStatus content. * backup\_last\_status\_info - change return value, it returns response content. * device\_administration\_authentication\_rules - deletes parameter identitySourceId. * device\_administration\_authentication\_rules\_info - change return value, it returns response content. * device\_administration\_authorization\_rules\_info - change return value, it returns response content. * device\_administration\_conditions - deletes parameter attributeId. * device\_administration\_conditions\_for\_authentication\_rule\_info - change return value, it returns response content. * device\_administration\_conditions\_for\_authorization\_rule\_info - change return value, it returns response content. * device\_administration\_conditions\_for\_policy\_set\_info - change return value, it returns response content. * device\_administration\_conditions\_info - change return value, it returns response content. * device\_administration\_dictionary\_attributes\_authentication\_info - change return value, it returns response content. * device\_administration\_dictionary\_attributes\_authorization\_info - change return value, it returns response content. * device\_administration\_dictionary\_attributes\_policy\_set\_info - change return value, it returns response content. * device\_administration\_global\_exception\_rules\_info - change return value, it returns response content. * device\_administration\_network\_conditions\_info - change return value, it returns response content. * device\_administration\_time\_date\_conditions - deletes parameter attributeId. * device\_administration\_time\_date\_conditions\_info - change return value, it returns response content. * egress\_matrix\_cell\_bulk\_monitor\_status\_info - change return value, it returns BulkStatus content. * network\_access\_authentication\_rules - deletes parameter identitySourceId. * network\_access\_conditions - deletes parameter attributeId. * network\_access\_time\_date\_conditions - deletes parameter attributeId. * node\_deployment - update parameters. * node\_deployment\_info - add filter and filterType parameters. * node\_group - fixes response recollection. * node\_group\_info - fixes response recollection. * repository\_files\_info - change return value, it returns response content. * repository\_info - change return value, it returns response content. * sg\_acl\_bulk\_monitor\_status\_info - change return value, it returns BulkStatus content. * sg\_mapping\_bulk\_monitor\_status\_info - change return value, it returns BulkStatus content. * sg\_mapping\_group\_bulk\_monitor\_status\_info - change return value, it returns BulkStatus content. * sg\_mapping\_group\_info - change return value, it returns BulkStatus content. * sg\_to\_vn\_to\_vlan\_bulk\_monitor\_status\_info - change return value, it returns BulkStatus content. * sgt - change generationId type from int to str. * sgt\_bulk\_monitor\_status\_info - change return value, it returns BulkStatus content. * sxp\_connections\_bulk\_monitor\_status\_info - change return value, it returns BulkStatus content. * sxp\_local\_bindings\_bulk\_monitor\_status\_info - change return value, it returns BulkStatus content. * sxp\_vpns\_bulk\_monitor\_status\_info - change return value, it returns BulkStatus content. * system\_certificate - new parameters portalTagTransferForSameSubject and roleTransferForSameSubject. * system\_certificate - portalTagTransferForSameSubject parameter renamed to allowPortalTagTransferForSameSubject. * system\_certificate - roleTransferForSameSubject parameter renamed to allowRoleTransferForSameSubject. * system\_certificate\_import - new parameters portalTagTransferForSameSubject and roleTransferForSameSubject. * system\_certificate\_import - portalTagTransferForSameSubject parameter renamed to allowPortalTagTransferForSameSubject. * system\_certificate\_import - roleTransferForSameSubject parameter renamed to allowRoleTransferForSameSubject. * trustsec\_nbar\_app\_info - change type from str to list. * trustsec\_vn\_info - change type from str to list. #### cisco.meraki[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id51 "Link to this heading") * meraki\_mr\_radio - New module #### cisco.nxos[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#cisco-nxos "Link to this heading") * The minimum required ansible.netcommon version has been bumped to v2.6.1. * Updated base plugin references to ansible.netcommon. * nxos\_facts - change default gather\_subset to min from !config ([https://github.com/ansible-collections/cisco.nxos/issues/418](https://github.com/ansible-collections/cisco.nxos/issues/418) ). * nxos\_file\_copy has been rewritten as a module. This change also removes the dependency on pexpect for file\_pull operation. Since this now uses AnsibleModule class for argspec validation, the validation messages will be slightly different. Expect changes in the return payload in some cases. All functionality remains unchanged. #### community.aws[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id52 "Link to this heading") * community.aws collection - The community.aws collection has dropped support for `botocore<1.19.0` and `boto3<1.16.0`. Most modules will continue to work with older versions of the AWS SDK, however compatibility with older versions of the SDK is not guaranteed and will not be tested. When using older versions of the SDK a warning will be emitted by Ansible ([https://github.com/ansible-collections/community.aws/pull/809](https://github.com/ansible-collections/community.aws/pull/809) ). * s3\_bucket\_notifications - refactor module to support SNS / SQS targets as well as the existing support for Lambda functions ([https://github.com/ansible-collections/community.aws/issues/140](https://github.com/ansible-collections/community.aws/issues/140) ). #### community.general[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id53 "Link to this heading") * The community.general collection no longer supports Ansible 2.9 and ansible-base 2.10. While we take no active measures to prevent usage, we will remove a lot of compatibility code and other compatility measures that will effectively prevent using most content from this collection with Ansible 2.9, and some content of this collection with ansible-base 2.10. Both Ansible 2.9 and ansible-base 2.10 will very soon be End of Life and if you are still using them, you should consider upgrading to ansible-core 2.11 or later as soon as possible ([https://github.com/ansible-collections/community.general/pull/4548](https://github.com/ansible-collections/community.general/pull/4548) ). #### community.mysql[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id54 "Link to this heading") * The community.mysql collection no longer supports `Ansible 2.9` and `ansible-base 2.10`. While we take no active measures to prevent usage and there are no plans to introduce incompatible code to the modules, we will stop testing against `Ansible 2.9` and `ansible-base 2.10`. Both will very soon be End of Life and if you are still using them, you should consider upgrading to the `latest Ansible / ansible-core 2.11 or later` as soon as possible ([https://github.com/ansible-collections/community.mysql/pull/343](https://github.com/ansible-collections/community.mysql/pull/343) ). #### community.network[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#community-network "Link to this heading") * The community.network collection no longer supports Ansible 2.9 and ansible-base 2.10. While we take no active measures to prevent usage, we will remove compatibility code and other compatility measures that will effectively prevent using most content from this collection with Ansible 2.9, and some content of this collection with ansible-base 2.10. Both Ansible 2.9 and ansible-base 2.10 will very soon be End of Life and if you are still using them, you should consider upgrading to ansible-core 2.11 or later as soon as possible ([https://github.com/ansible-collections/community.network/pull/426](https://github.com/ansible-collections/community.network/pull/426) ). #### community.postgresql[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id55 "Link to this heading") * The community.postgresql collection no longer supports `Ansible 2.9` and `ansible-base 2.10`. While we take no active measures to prevent usage and there are no plans to introduce incompatible code to the modules, we will stop testing against `Ansible 2.9` and `ansible-base 2.10`. Both will very soon be End of Life and if you are still using them, you should consider upgrading to the `latest Ansible / ansible-core 2.11 or later` as soon as possible ([https://github.com/ansible-collections/community.postgresql/pull/245](https://github.com/ansible-collections/community.postgresql/pull/245) ). * postgresql\_privs - the `usage_on_types` feature have been deprecated and will be removed in `community.postgresql 3.0.0`. Please use the `type` option with the `type` value to explicitly grant/revoke privileges on types ([https://github.com/ansible-collections/community.postgresql/issues/207](https://github.com/ansible-collections/community.postgresql/issues/207) ). * postgresql\_query - the `path_to_script` and `as_single_query` options as well as the `query_list` and `query_all_results` return values have been deprecated and will be removed in `community.postgresql 3.0.0`. Please use the `community.postgresql.postgresql_script` module to execute statements from scripts ([https://github.com/ansible-collections/community.postgresql/issues/189](https://github.com/ansible-collections/community.postgresql/issues/189) ). * postgresql\_query - the default value of the `as_single_query` option changes to `yes`. If the related behavior of your tasks where the module is involved changes, please adjust the parameter’s value correspondingly ([https://github.com/ansible-collections/community.postgresql/issues/85](https://github.com/ansible-collections/community.postgresql/issues/85) ). * postgresql\_user - the `priv` argument has been deprecated and will be removed in `community.postgresql 3.0.0`. Please use the `postgresql_privs` module to grant/revoke privileges instead ([https://github.com/ansible-collections/community.postgresql/issues/212](https://github.com/ansible-collections/community.postgresql/issues/212) ). #### community.vmware[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id56 "Link to this heading") * Drop VCSIM as a test target ([https://github.com/ansible-collections/community.vmware/pull/1294](https://github.com/ansible-collections/community.vmware/pull/1294) ). #### containers.podman[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id57 "Link to this heading") * Add podman\_tag module * Add secrets driver and driver opts support #### dellemc.openmanage[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id58 "Link to this heading") * All modules can read custom or organizational CA signed certificate from the environment variables. Please refer to [SSL Certificate Validation](https://github.com/dell/dellemc-openmanage-ansible-modules#ssl-certificate-validation) section in the [README.md](https://github.com/dell/dellemc-openmanage-ansible-modules/blob/collections/README.md#SSL-Certificate-Validation) for modification to existing playbooks or setting environment variable. * All modules now support SSL over HTTPS and socket level timeout. * idrac\_server\_config\_profile - The module is enhanced to support export, import, and preview the SCP configuration using Redfish and added support for check mode. #### f5networks.f5\_modules[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#f5networks-f5-modules "Link to this heading") * bigip\_device\_info - pagination logic has also been added to help with api stability. * bigip\_device\_info - the module no longer gathers information from all partitions on device. This change will stabalize the module by gathering resources only from the given partition and prevent the module from gathering way too much information that might result in crashing. #### fortinet.fortios[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id61 "Link to this heading") * Support FortiOS 7.0.2, 7.0.3, 7.0.4, 7.0.5. #### frr.frr[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#frr-frr "Link to this heading") * Minimum required ansible.netcommon version is 2.5.1. * Updated base plugin references to ansible.netcommon. #### ibm.qradar[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#ibm-qradar "Link to this heading") * Minimum required ansible.netcommon version is 2.5.1. * Updated base plugin references to ansible.netcommon. #### junipernetworks.junos[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#junipernetworks-junos "Link to this heading") * Minimum required ansible.netcommon version is 2.5.1. * Updated base plugin references to ansible.netcommon. * junos\_facts - change default gather\_subset to min from !config. #### ovirt.ovirt[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#ovirt-ovirt "Link to this heading") * manageiq - role removed ([https://github.com/oVirt/ovirt-ansible-collection/pull/375](https://github.com/oVirt/ovirt-ansible-collection/pull/375) ). #### splunk.es[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#splunk-es "Link to this heading") * Minimum required ansible.netcommon version is 2.5.1. * Updated base plugin references to ansible.netcommon. #### vyos.vyos[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#vyos-vyos "Link to this heading") * Add ‘pool’ as value to server key in ntp\_global. * Minimum required ansible.netcommon version is 2.5.1. * Updated base plugin references to ansible.netcommon. * vyos\_facts - change default gather\_subset to min from !config ([https://github.com/ansible-collections/vyos.vyos/issues/231](https://github.com/ansible-collections/vyos.vyos/issues/231) ). ### [Removed Collections](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id123) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#removed-collections "Link to this heading") * community.kubernetes (previously included version: 2.0.1) * community.kubevirt (previously included version: 1.0.0) ### [Removed Features](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id124) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#removed-features "Link to this heading") * The community.kubernetes collection has been removed from Ansible 6. It has been deprecated since Ansible 4.2, and version 2.0.0 included since Ansible 5 is only a set of deprecated redirects from community.kubernetes to kubernetes.core. If you still need the redirects, you can manually install community.kubernetes with `ansible-galaxy collection install community.kubernetes` ([https://github.com/ansible-community/community-topics/issues/93](https://github.com/ansible-community/community-topics/issues/93) ). * The community.kubevirt collection has been removed from Ansible 6. It has not been working with the community.kubernetes collection included since Ansible 5.0.0, and unfortunately nobody managed to adjust the collection to work with kubernetes.core >= 2.0.0. If you need to use this collection, you need to manually install community.kubernetes < 2.0.0 together with community.kubevirt with `ansible-galaxy collection install community.kubevirt 'community.kubernetes:<2.0.0'` ([https://github.com/ansible-community/community-topics/issues/92](https://github.com/ansible-community/community-topics/issues/92) ). #### Ansible-core[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id62 "Link to this heading") * Remove deprecated `Templar.set_available_variables()` method ([https://github.com/ansible/ansible/issues/75828](https://github.com/ansible/ansible/issues/75828) ) * cli - remove deprecated ability to set verbosity before the sub-command ([https://github.com/ansible/ansible/issues/75823](https://github.com/ansible/ansible/issues/75823) ) * copy - remove deprecated `thirsty` alias ([https://github.com/ansible/ansible/issues/75824](https://github.com/ansible/ansible/issues/75824) ) * psrp - Removed fallback on `put_file` with older `pypsrp` versions. Users must have at least `pypsrp>=0.4.0`. * url\_argument\_spec - remove deprecated `thirsty` alias for `get_url` and `uri` modules ([https://github.com/ansible/ansible/issues/75825](https://github.com/ansible/ansible/issues/75825) , [https://github.com/ansible/ansible/issues/75826](https://github.com/ansible/ansible/issues/75826) ) #### community.general[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id63 "Link to this heading") * ali\_instance\_info - removed the options `availability_zone`, `instance_ids`, and `instance_names`. Use filter item `zone_id` instead of `availability_zone`, filter item `instance_ids` instead of `instance_ids`, and filter item `instance_name` instead of `instance_names` ([https://github.com/ansible-collections/community.general/pull/4516](https://github.com/ansible-collections/community.general/pull/4516) ). * apt\_rpm - removed the deprecated alias `update-cache` of `update_cache` ([https://github.com/ansible-collections/community.general/pull/4516](https://github.com/ansible-collections/community.general/pull/4516) ). * compose - removed various deprecated aliases. Use the version with `_` instead of `-` instead ([https://github.com/ansible-collections/community.general/pull/4516](https://github.com/ansible-collections/community.general/pull/4516) ). * dnsimple - remove support for dnsimple < 2.0.0 ([https://github.com/ansible-collections/community.general/pull/4516](https://github.com/ansible-collections/community.general/pull/4516) ). * github\_deploy\_key - removed the deprecated alias `2fa_token` of `otp` ([https://github.com/ansible-collections/community.general/pull/4516](https://github.com/ansible-collections/community.general/pull/4516) ). * homebrew, homebrew\_cask - removed the deprecated alias `update-brew` of `update_brew` ([https://github.com/ansible-collections/community.general/pull/4516](https://github.com/ansible-collections/community.general/pull/4516) ). * linode - removed the `backupsenabled` option. Use `backupweeklyday` or `backupwindow` to enable backups ([https://github.com/ansible-collections/community.general/pull/4516](https://github.com/ansible-collections/community.general/pull/4516) ). * opkg - removed the deprecated alias `update-cache` of `update_cache` ([https://github.com/ansible-collections/community.general/pull/4516](https://github.com/ansible-collections/community.general/pull/4516) ). * pacman - if `update_cache=true` is used with `name` or `upgrade`, the changed state will now also indicate if only the cache was updated. To keep the old behavior - only indicate `changed` when a package was installed/upgraded -, use `changed_when` as indicated in the module examples ([https://github.com/ansible-collections/community.general/pull/4516](https://github.com/ansible-collections/community.general/pull/4516) ). * pacman - removed the deprecated alias `update-cache` of `update_cache` ([https://github.com/ansible-collections/community.general/pull/4516](https://github.com/ansible-collections/community.general/pull/4516) ). * proxmox, proxmox\_kvm, proxmox\_snap - no longer allow to specify a VM name that matches multiple VMs. If this happens, the modules now fail ([https://github.com/ansible-collections/community.general/pull/4516](https://github.com/ansible-collections/community.general/pull/4516) ). * serverless - removed the `functions` option. It was not used by the module ([https://github.com/ansible-collections/community.general/pull/4516](https://github.com/ansible-collections/community.general/pull/4516) ). * slackpkg - removed the deprecated alias `update-cache` of `update_cache` ([https://github.com/ansible-collections/community.general/pull/4516](https://github.com/ansible-collections/community.general/pull/4516) ). * urpmi - removed the deprecated alias `no-recommends` of `no_recommends` ([https://github.com/ansible-collections/community.general/pull/4516](https://github.com/ansible-collections/community.general/pull/4516) ). * urpmi - removed the deprecated alias `update-cache` of `update_cache` ([https://github.com/ansible-collections/community.general/pull/4516](https://github.com/ansible-collections/community.general/pull/4516) ). * xbps - removed the deprecated alias `update-cache` of `update_cache` ([https://github.com/ansible-collections/community.general/pull/4516](https://github.com/ansible-collections/community.general/pull/4516) ). * xfconf - the `get` state has been removed. Use the `xfconf_info` module instead ([https://github.com/ansible-collections/community.general/pull/4516](https://github.com/ansible-collections/community.general/pull/4516) ). #### community.hashi\_vault[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id64 "Link to this heading") * aws\_iam auth - the deprecated alias `aws_iam_login` for the `aws_iam` value of the `auth_method` option has been removed ([https://github.com/ansible-collections/community.hashi\_vault/issues/194](https://github.com/ansible-collections/community.hashi_vault/issues/194) ). * community.hashi\_vault collection - support for Ansible 2.9 and ansible-base 2.10 has been removed ([https://github.com/ansible-collections/community.hashi\_vault/issues/189](https://github.com/ansible-collections/community.hashi_vault/issues/189) ). * hashi\_vault lookup - the deprecated `[lookup_hashi_vault]` INI config section has been removed in favor of the collection-wide `[hashi_vault_collection]` section ([https://github.com/ansible-collections/community.hashi\_vault/issues/179](https://github.com/ansible-collections/community.hashi_vault/issues/179) ). * the “legacy” integration test setup has been removed; this does not affect end users and is only relevant to contributors ([https://github.com/ansible-collections/community.hashi\_vault/pull/191](https://github.com/ansible-collections/community.hashi_vault/pull/191) ). #### community.network[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id65 "Link to this heading") * aireos modules - removed deprecated `connection: local` support. Use `connection: network_cli` instead ([https://github.com/ansible-collections/community.network/pull/440](https://github.com/ansible-collections/community.network/pull/440) ). * aireos modules - removed deprecated `provider` option. Use `connection: network_cli` instead ([https://github.com/ansible-collections/community.network/pull/440](https://github.com/ansible-collections/community.network/pull/440) ). * aruba modules - removed deprecated `connection: local` support. Use `connection: network_cli` instead ([https://github.com/ansible-collections/community.network/pull/440](https://github.com/ansible-collections/community.network/pull/440) ). * aruba modules - removed deprecated `provider` option. Use `connection: network_cli` instead ([https://github.com/ansible-collections/community.network/pull/440](https://github.com/ansible-collections/community.network/pull/440) ). * ce modules - removed deprecated `connection: local` support. Use `connection: network_cli` instead ([https://github.com/ansible-collections/community.network/pull/440](https://github.com/ansible-collections/community.network/pull/440) ). * ce modules - removed deprecated `provider` option. Use `connection: network_cli` instead ([https://github.com/ansible-collections/community.network/pull/440](https://github.com/ansible-collections/community.network/pull/440) ). * enos modules - removed deprecated `connection: local` support. Use `connection: network_cli` instead ([https://github.com/ansible-collections/community.network/pull/440](https://github.com/ansible-collections/community.network/pull/440) ). * enos modules - removed deprecated `provider` option. Use `connection: network_cli` instead ([https://github.com/ansible-collections/community.network/pull/440](https://github.com/ansible-collections/community.network/pull/440) ). * ironware modules - removed deprecated `connection: local` support. Use `connection: network_cli` instead ([https://github.com/ansible-collections/community.network/pull/440](https://github.com/ansible-collections/community.network/pull/440) ). * ironware modules - removed deprecated `provider` option. Use `connection: network_cli` instead ([https://github.com/ansible-collections/community.network/pull/440](https://github.com/ansible-collections/community.network/pull/440) ). * sros modules - removed deprecated `connection: local` support. Use `connection: network_cli` instead ([https://github.com/ansible-collections/community.network/pull/440](https://github.com/ansible-collections/community.network/pull/440) ). * sros modules - removed deprecated `provider` option. Use `connection: network_cli` instead ([https://github.com/ansible-collections/community.network/pull/440](https://github.com/ansible-collections/community.network/pull/440) ). #### community.vmware[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id66 "Link to this heading") * vcenter\_extension\_facts - The deprecated module `vcenter_extension_facts` has been removed, use `vcenter_extension_info` instead. * vmware\_about\_facts - The deprecated module `vmware_about_facts` has been removed, use `vmware_about_info` instead. * vmware\_category\_facts - The deprecated module `vmware_category_facts` has been removed, use `vmware_category_info` instead. * vmware\_cluster - Remove DRS configuration in favour of module `vmware_cluster_drs`. * vmware\_cluster - Remove HA configuration in favour of module `vmware_cluster_ha`. * vmware\_cluster - Remove VSAN configuration in favour of module `vmware_cluster_vsan`. * vmware\_cluster\_facts - The deprecated module `vmware_cluster_facts` has been removed, use `vmware_cluster_info` instead. * vmware\_datastore\_facts - The deprecated module `vmware_datastore_facts` has been removed, use `vmware_datastore_info` instead. * vmware\_drs\_group\_facts - The deprecated module `vmware_drs_group_facts` has been removed, use `vmware_drs_group_info` instead. * vmware\_drs\_rule\_facts - The deprecated module `vmware_drs_rule_facts` has been removed, use `vmware_drs_rule_info` instead. * vmware\_dvs\_portgroup - The deprecated parameter `portgroup_type` has been removed, use `port_binding` instead. * vmware\_dvs\_portgroup\_facts - The deprecated module `vmware_dvs_portgroup_facts` has been removed, use `vmware_dvs_portgroup_info` instead. * vmware\_guest\_boot\_facts - The deprecated module `vmware_guest_boot_facts` has been removed, use `vmware_guest_boot_info` instead. * vmware\_guest\_customization\_facts - The deprecated module `vmware_guest_customization_facts` has been removed, use `vmware_guest_customization_info` instead. * vmware\_guest\_disk\_facts - The deprecated module `vmware_guest_disk_facts` has been removed, use `vmware_guest_disk_info` instead. * vmware\_guest\_facts - The deprecated module `vmware_guest_facts` has been removed, use `vmware_guest_info` instead. * vmware\_guest\_snapshot\_facts - The deprecated module `vmware_guest_snapshot_facts` has been removed, use `vmware_guest_snapshot_info` instead. * vmware\_host\_capability\_facts - The deprecated module `vmware_host_capability_facts` has been removed, use `vmware_host_capability_info` instead. * vmware\_host\_config\_facts - The deprecated module `vmware_host_config_facts` has been removed, use `vmware_host_config_info` instead. * vmware\_host\_dns\_facts - The deprecated module `vmware_host_dns_facts` has been removed, use `vmware_host_dns_info` instead. * vmware\_host\_feature\_facts - The deprecated module `vmware_host_feature_facts` has been removed, use `vmware_host_feature_info` instead. * vmware\_host\_firewall\_facts - The deprecated module `vmware_host_firewall_facts` has been removed, use `vmware_host_firewall_info` instead. * vmware\_host\_ntp\_facts - The deprecated module `vmware_host_ntp_facts` has been removed, use `vmware_host_ntp_info` instead. * vmware\_host\_package\_facts - The deprecated module `vmware_host_package_facts` has been removed, use `vmware_host_package_info` instead. * vmware\_host\_service\_facts - The deprecated module `vmware_host_service_facts` has been removed, use `vmware_host_service_info` instead. * vmware\_host\_ssl\_facts - The deprecated module `vmware_host_ssl_facts` has been removed, use `vmware_host_ssl_info` instead. * vmware\_host\_vmhba\_facts - The deprecated module `vmware_host_vmhba_facts` has been removed, use `vmware_host_vmhba_info` instead. * vmware\_host\_vmnic\_facts - The deprecated module `vmware_host_vmnic_facts` has been removed, use `vmware_host_vmnic_info` instead. * vmware\_local\_role\_facts - The deprecated module `vmware_local_role_facts` has been removed, use `vmware_local_role_info` instead. * vmware\_local\_user\_facts - The deprecated module `vmware_local_user_facts` has been removed, use `vmware_local_user_info` instead. * vmware\_portgroup\_facts - The deprecated module `vmware_portgroup_facts` has been removed, use `vmware_portgroup_info` instead. * vmware\_resource\_pool\_facts - The deprecated module `vmware_resource_pool_facts` has been removed, use `vmware_resource_pool_info` instead. * vmware\_tag\_facts - The deprecated module `vmware_tag_facts` has been removed, use `vmware_tag_info` instead. * vmware\_target\_canonical\_facts - The deprecated module `vmware_target_canonical_facts` has been removed, use `vmware_target_canonical_info` instead. * vmware\_vm\_facts - The deprecated module `vmware_vm_facts` has been removed, use `vmware_vm_info` instead. * vmware\_vmkernel\_facts - The deprecated module `vmware_vmkernel_facts` has been removed, use `vmware_vmkernel_info` instead. * vmware\_vmkernel\_ip\_config - The deprecated module `vmware_vmkernel_ip_config` has been removed, use `vmware_vmkernel` instead. * vmware\_vswitch\_facts - The deprecated module `vmware_vswitch_facts` has been removed, use `vmware_vswitch_info` instead. ### [Deprecated Features](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id125) [](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id67 "Link to this heading") * The collection `community.sap` has been renamed to `community.sap_libs`. For now both collections are included in Ansible. The content in `community.sap` will be replaced with deprecated redirects to the new collection in Ansible 7.0.0, and these redirects will eventually be removed from Ansible. Please update your FQCNs for `community.sap`. #### Ansible-core[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id68 "Link to this heading") * ansible-core - Remove support for Python 2.6. * ansible-test - Remove support for Python 2.6. * ssh connection plugin option scp\_if\_ssh in favor of ssh\_transfer\_method. #### amazon.aws[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id69 "Link to this heading") * ec2\_instance - The default value for `` `instance_type` `` has been deprecated, in the future release you must set an instance\_type or a launch\_template ([https://github.com/ansible-collections/amazon.aws/pull/587](https://github.com/ansible-collections/amazon.aws/pull/587) ). * module\_utils - support for the original AWS SDK boto has been deprecated in favour of the boto3/botocore SDK. All boto based modules have either been deprecated or migrated to botocore, and the remaining support code in module\_utils will be removed in release 4.0.0 of the amazon.aws collection. Any modules outside of the amazon.aws and community.aws collections based on the boto library will need to be migrated to the boto3/botocore libraries ([https://github.com/ansible-collections/amazon.aws/pull/575](https://github.com/ansible-collections/amazon.aws/pull/575) ). #### cisco.ios[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id70 "Link to this heading") * Deprecates lldp module. * ios\_acls - Deprecated fragment attribute added boolean alternate as enable\_fragment. #### cisco.nxos[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id71 "Link to this heading") * Deprecated nxos\_snmp\_community module. * Deprecated nxos\_snmp\_contact module. * Deprecated nxos\_snmp\_host module. * Deprecated nxos\_snmp\_location module. * Deprecated nxos\_snmp\_traps module. * Deprecated nxos\_snmp\_user module. #### community.docker[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id72 "Link to this heading") * Support for Ansible 2.9 and ansible-base 2.10 is deprecated, and will be removed in the next major release (community.docker 3.0.0). Some modules might still work with these versions afterwards, but we will no longer keep compatibility code that was needed to support them ([https://github.com/ansible-collections/community.docker/pull/361](https://github.com/ansible-collections/community.docker/pull/361) ). * The dependency on docker-compose for Execution Environments is deprecated and will be removed in community.docker 3.0.0. The [Python docker-compose library](https://pypi.org/project/docker-compose/) is unmaintained and can cause dependency issues. You can manually still install it in an Execution Environment when needed ([https://github.com/ansible-collections/community.docker/pull/373](https://github.com/ansible-collections/community.docker/pull/373) ). * Various modules - the default of `tls_hostname` that was supposed to be removed in community.docker 2.0.0 will now be removed in version 3.0.0 ([https://github.com/ansible-collections/community.docker/pull/362](https://github.com/ansible-collections/community.docker/pull/362) ). * docker\_stack - the return values `out` and `err` that were supposed to be removed in community.docker 2.0.0 will now be removed in version 3.0.0 ([https://github.com/ansible-collections/community.docker/pull/362](https://github.com/ansible-collections/community.docker/pull/362) ). #### community.general[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id73 "Link to this heading") * ansible\_galaxy\_install - deprecated support for `ansible` 2.9 and `ansible-base` 2.10 ([https://github.com/ansible-collections/community.general/pull/4601](https://github.com/ansible-collections/community.general/pull/4601) ). * dig lookup plugin - the `DLV` record type has been decommissioned in 2017 and support for it will be removed from community.general 6.0.0 ([https://github.com/ansible-collections/community.general/pull/4618](https://github.com/ansible-collections/community.general/pull/4618) ). * gem - the default of the `norc` option has been deprecated and will change to `true` in community.general 6.0.0. Explicitly specify a value to avoid a deprecation warning ([https://github.com/ansible-collections/community.general/pull/4517](https://github.com/ansible-collections/community.general/pull/4517) ). * mail callback plugin - not specifying `sender` is deprecated and will be disallowed in community.general 6.0.0 ([https://github.com/ansible-collections/community.general/pull/4140](https://github.com/ansible-collections/community.general/pull/4140) ). * module\_helper module utils - deprecated the attribute `ModuleHelper.VarDict` ([https://github.com/ansible-collections/community.general/pull/3801](https://github.com/ansible-collections/community.general/pull/3801) ). * nmcli - deprecate default hairpin mode for a bridge. This so we can change it to `false` in community.general 7.0.0, as this is also the default in `nmcli` ([https://github.com/ansible-collections/community.general/pull/4334](https://github.com/ansible-collections/community.general/pull/4334) ). * pacman - from community.general 5.0.0 on, the `changed` status of `update_cache` will no longer be ignored if `name` or `upgrade` is specified. To keep the old behavior, add something like `register: result` and `changed_when: result.packages | length > 0` to your task ([https://github.com/ansible-collections/community.general/pull/4329](https://github.com/ansible-collections/community.general/pull/4329) ). * proxmox inventory plugin - the current default `true` of the `want_proxmox_nodes_ansible_host` option has been deprecated. The default will change to `false` in community.general 6.0.0. To keep the current behavior, explicitly set `want_proxmox_nodes_ansible_host` to `true` in your inventory configuration. We suggest to already switch to the new behavior by explicitly setting it to `false`, and by using `compose:` to set `ansible_host` to the correct value. See the examples in the plugin documentation for details ([https://github.com/ansible-collections/community.general/pull/4466](https://github.com/ansible-collections/community.general/pull/4466) ). * vmadm - deprecated module parameter `debug` that was not used anywhere ([https://github.com/ansible-collections/community.general/pull/4580](https://github.com/ansible-collections/community.general/pull/4580) ). #### community.hashi\_vault[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id74 "Link to this heading") * Support for Ansible 2.9 and ansible-base 2.10 is deprecated, and will be removed in the next major release (community.hashi\_vault 3.0.0) next spring ([https://github.com/ansible-community/community-topics/issues/50](https://github.com/ansible-community/community-topics/issues/50) , [https://github.com/ansible-collections/community.hashi\_vault/issues/189](https://github.com/ansible-collections/community.hashi_vault/issues/189) ). * aws\_iam\_login auth method - the `aws_iam_login` method has been renamed to `aws_iam`. The old name will be removed in collection version `3.0.0`. Until then both names will work, and a warning will be displayed when using the old name ([https://github.com/ansible-collections/community.hashi\_vault/pull/193](https://github.com/ansible-collections/community.hashi_vault/pull/193) ). * token\_validate options - the shared auth option `token_validate` will change its default from `True` to `False` in community.hashi\_vault version 4.0.0. The `vault_login` lookup and module will keep the default value of `True` ([https://github.com/ansible-collections/community.hashi\_vault/issues/248](https://github.com/ansible-collections/community.hashi_vault/issues/248) ). * token\_validate options - the shared auth option `token_validate` will change its default from `true` to `false` in community.hashi\_vault version 4.0.0. The `vault_login` lookup and module will keep the default value of `true` ([https://github.com/ansible-collections/community.hashi\_vault/issues/248](https://github.com/ansible-collections/community.hashi_vault/issues/248) ). #### community.network[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id75 "Link to this heading") * Support for Ansible 2.9 and ansible-base 2.10 is deprecated, and will be removed in the next major release (community.network 4.0.0) this spring. While most content will probably still work with ansible-base 2.10, we will remove symbolic links for modules and action plugins, which will make it impossible to use them with Ansible 2.9 anymore. Please use community.network 3.x.y with Ansible 2.9 and ansible-base 2.10, as these releases will continue to support Ansible 2.9 and ansible-base 2.10 even after they are End of Life ([https://github.com/ansible-community/community-topics/issues/50](https://github.com/ansible-community/community-topics/issues/50) , [https://github.com/ansible-collections/community.network/pull/382](https://github.com/ansible-collections/community.network/pull/382) ). #### junipernetworks.junos[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id76 "Link to this heading") * ‘router\_id’ options is deprecated from junos\_ospf\_interfaces, junos\_ospfv2 and junos\_ospfv3 resource module. #### purestorage.flasharray[](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_6.html#id77 "Link to this heading") * purefa\_sso - Deprecated in favor of M(purefa\_admin). Will be removed in Collection 2.0 --- # Roles — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * [Using Ansible playbooks](https://docs.ansible.com/projects/ansible/latest/playbook_guide/index.html) * [Working with playbooks](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks.html) * Roles * [Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr) * * * Roles[](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#roles "Link to this heading") ================================================================================================================================== Roles let you automatically load related vars, files, tasks, handlers, and other Ansible artifacts based on a known file structure. After you group your content into roles, you can easily reuse them and share them with other users. [Role directory structure](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#id3) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#role-directory-structure "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- An Ansible role has a defined directory structure with seven main standard directories. You must include at least one of these directories in each role. You can omit any directories the role does not use. For example: \# playbooks site.yml webservers.yml fooservers.yml roles/ common/ # this hierarchy represents a "role" tasks/ # main.yml # <-- tasks file can include smaller files if warranted handlers/ # main.yml # <-- handlers file templates/ # <-- files for use with the template resource ntp.conf.j2 # <------- templates end in .j2 files/ # bar.txt # <-- files for use with the copy resource foo.sh # <-- script files for use with the script resource vars/ # main.yml # <-- variables associated with this role defaults/ # main.yml # <-- default lower priority variables for this role meta/ # main.yml # <-- role dependencies library/ # roles can also include custom modules module\_utils/ # roles can also include custom module\_utils lookup\_plugins/ # or other types of plugins, like lookup in this case webtier/ # same kind of structure as "common" was above, done for the webtier role monitoring/ # "" fooapp/ # "" By default, Ansible will look in most role directories for a `main.yml` file for relevant content (also `main.yaml` and `main`): * `tasks/main.yml` - A list of tasks that the role provides to the play for execution. * `handlers/main.yml` - handlers that are imported into the parent play for use by the role or other roles and tasks in the play. * `defaults/main.yml` - very low precedence values for variables provided by the role (see [Using variables](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#playbooks-variables) for more information). A role’s own defaults will take priority over other role’s defaults, but any/all other variable sources will override this. * `vars/main.yml` - high precedence variables provided by the role to the play (see [Using variables](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#playbooks-variables) for more information). * `files/stuff.txt` - one or more files that are available for the role and it’s children. * `templates/something.j2` - templates to use in the role or child roles. * `meta/main.yml` - metadata for the role, including role dependencies and optional Galaxy metadata such as platforms supported. This is required for uploading into galaxy as a standalone role, but not for using the role in your play. Note * None of the files above are required for a role. For example, you can just provide `files/something.txt` or `vars/for_import.yml` and it will still be a valid role. * On stand alone roles you can also include custom modules and/or plugins, for example `library/my_module.py`, which may be used within this role (see [Embedding modules and plugins in roles](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#embedding-modules-and-plugins-in-roles) for more information). * A ‘stand alone’ role refers to role that is not part of a collection but as individually installable content. * Variables from `vars/` and `defaults/` are imported into play scope unless you disable it via the `public` option in `import_role`/`include_role`. You can add other YAML files in some directories, but they won’t be used by default. They can be included/imported directly or specified when using `include_role/import_role`. For example, you can place platform-specific tasks in separate files and refer to them in the `tasks/main.yml` file: \# roles/example/tasks/main.yml \- name: Install the correct web server for RHEL ansible.builtin.import\_tasks: redhat.yml when: ansible\_facts\['os\_family'\]|lower == 'redhat' \- name: Install the correct web server for Debian ansible.builtin.import\_tasks: debian.yml when: ansible\_facts\['os\_family'\]|lower == 'debian' \# roles/example/tasks/redhat.yml \- name: Install web server ansible.builtin.yum: name: "httpd" state: present \# roles/example/tasks/debian.yml \- name: Install web server ansible.builtin.apt: name: "apache2" state: present Or call those tasks directly when loading the role, which bypasses the `main.yml` files: \- name: include apt tasks ansible.builtin.include\_role: name: package\_manager\_bootstrap tasks\_from: apt.yml when: ansible\_facts\['os\_family'\] == 'Debian' Directories `defaults` and `vars` may also include _nested directories_. If your variables file is a directory, Ansible reads all variables files and directories inside in alphabetical order. If a nested directory contains variables files as well as directories, Ansible reads the directories first. Below is an example of a `vars/main` directory: roles/ common/ # this hierarchy represents a "role" vars/ main/ # <-- variables associated with this role first\_nested\_directory/ first\_variables\_file.yml second\_nested\_directory/ second\_variables\_file.yml third\_variables\_file.yml [Storing and finding roles](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#id4) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#storing-and-finding-roles "Link to this heading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- By default, Ansible looks for roles in the following locations: * in collections, if you are using them * in a directory called `roles/`, relative to the playbook file * in the configured [roles\_path](https://docs.ansible.com/projects/ansible/latest/reference_appendices/config.html#default-roles-path) . The default search path is `~/.ansible/roles:/usr/share/ansible/roles:/etc/ansible/roles`. * in the directory where the playbook file is located If you store your roles in a different location, set the [roles\_path](https://docs.ansible.com/projects/ansible/latest/reference_appendices/config.html#default-roles-path) configuration option so Ansible can find your roles. Checking shared roles into a single location makes them easier to use in multiple playbooks. See [Configuring Ansible](https://docs.ansible.com/projects/ansible/latest/installation_guide/intro_configuration.html#intro-configuration) for details about managing settings in `ansible.cfg`. Alternatively, you can call a role with a fully qualified path: \--- \- hosts: webservers roles: \- role: '/path/to/my/roles/common' [Using roles](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#id5) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#using-roles "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can use roles in the following ways: * at the play level with the `roles` option: This is the classic way of using roles in a play. * at the tasks level with `include_role`: You can reuse roles dynamically anywhere in the `tasks` section of a play using `include_role`. * at the tasks level with `import_role`: You can reuse roles statically anywhere in the `tasks` section of a play using `import_role`. * as a dependency of another role (see the `dependencies` keyword in `meta/main.yml` in this same page). ### [Using roles at the play level](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#id6) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#using-roles-at-the-play-level "Link to this heading") The classic (original) way to use roles is with the `roles` option for a given play: \--- \- hosts: webservers roles: \- common \- webservers When you use the `roles` option at the play level, each role ‘x’ looks for a `main.yml` (also `main.yaml` and `main`) in the following directories: * `roles/x/tasks/` * `roles/x/handlers/` * `roles/x/vars/` * `roles/x/defaults/` * `roles/x/meta/` * Any copy, script, template or include tasks (in the role) can reference files in roles/x/{files,templates,tasks}/ (dir depends on task) without having to path them relatively or absolutely. Note `vars` and `defaults` can also match to a directory of the same name and Ansible will process all the files contained in that directory. See [Role directory structure](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#role-directory-structure) for more details. Note If you use `include_role/import_role`, you can specify a custom file name instead of `main`. The `meta` directory is an exception because it does not allow for customization. When you use the `roles` option at the play level, Ansible treats the roles as static imports and processes them during playbook parsing. Ansible executes each play in this order: * Any `pre_tasks` defined in the play. * Any handlers triggered by pre\_tasks. * Each role listed in `roles:`, in the order listed. Any role dependencies defined in the role’s `meta/main.yml` run first, subject to tag filtering and conditionals. See [Using role dependencies](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#role-dependencies) for more details. * Any `tasks` defined in the play. * Any handlers triggered by the roles or tasks. * Any `post_tasks` defined in the play. * Any handlers triggered by post\_tasks. Note If using tags with tasks in a role, be sure to also tag your pre\_tasks, post\_tasks, and role dependencies and pass those along as well, especially if the pre/post tasks and role dependencies are used for monitoring outage window control or load balancing. See [Tags](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_tags.html#tags) for details on adding and using tags. You can pass other keywords to the `roles` option: \--- \- hosts: webservers roles: \- common \- role: foo\_app\_instance vars: dir: '/opt/a' app\_port: 5000 tags: typeA \- role: foo\_app\_instance vars: dir: '/opt/b' app\_port: 5001 tags: typeB When you add a tag to the `role` option, Ansible applies the tag to ALL tasks within the role. Note Prior to `ansible-core` 2.15, `vars:` within the `roles:` section of a playbook are added to the play variables, making them available to all tasks within the play before and after the role. This behavior can be changed by [DEFAULT\_PRIVATE\_ROLE\_VARS](https://docs.ansible.com/projects/ansible/latest/reference_appendices/config.html#default-private-role-vars) . On more recent versions, `vars:` do not leak into the play’s variable scope. ### [Including roles: dynamic reuse](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#id7) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#including-roles-dynamic-reuse "Link to this heading") You can reuse roles dynamically anywhere in the `tasks` section of a play using `include_role`. While roles added in a `roles` section run before any other tasks in a play, included roles run in the order they are defined. If there are other tasks before an `include_role` task, the other tasks will run first. To include a role: \--- \- hosts: webservers tasks: \- name: Print a message ansible.builtin.debug: msg: "this task runs before the example role" \- name: Include the example role ansible.builtin.include\_role: name: example \- name: Print a message ansible.builtin.debug: msg: "this task runs after the example role" You can pass other keywords, including variables and tags, when including roles: \--- \- hosts: webservers tasks: \- name: Include the foo\_app\_instance role ansible.builtin.include\_role: name: foo\_app\_instance vars: dir: '/opt/a' app\_port: 5000 tags: typeA \# ... When you add a [tag](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_tags.html#tags) to an `include_role` task, Ansible applies the tag **only** to the include itself. This means you can pass `--tags` to run only selected tasks from the role, if those tasks themselves have the same tag as the include statement. See [Selectively running tagged tasks in reusable files](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_tags.html#selective-reuse) for details. You can conditionally include a role: \--- \- hosts: webservers tasks: \- name: Include the some\_role role ansible.builtin.include\_role: name: some\_role when: "ansible\_facts\['os\_family'\] \== 'RedHat'" ### [Importing roles: static reuse](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#id8) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#importing-roles-static-reuse "Link to this heading") You can reuse roles statically anywhere in the `tasks` section of a play using `import_role`. The behavior is the same as using the `roles` keyword. For example: \--- \- hosts: webservers tasks: \- name: Print a message ansible.builtin.debug: msg: "before we run our role" \- name: Import the example role ansible.builtin.import\_role: name: example \- name: Print a message ansible.builtin.debug: msg: "after we ran our role" You can pass other keywords, including variables and tags when importing roles: \--- \- hosts: webservers tasks: \- name: Import the foo\_app\_instance role ansible.builtin.import\_role: name: foo\_app\_instance vars: dir: '/opt/a' app\_port: 5000 \# ... When you add a tag to an `import_role` statement, Ansible applies the tag to **all** tasks within the role. See [Tag inheritance: adding tags to multiple tasks](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_tags.html#tag-inheritance) for details. [Role argument validation](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#id9) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#role-argument-validation "Link to this heading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Beginning with version 2.11, you may choose to enable role argument validation based on an argument specification. This specification is defined in the `meta/argument_specs.yml` file (or with the `.yaml` file extension). When this argument specification is defined, a new task is inserted at the beginning of role execution that will validate the parameters supplied for the role against the specification. If the parameters fail validation, the role will fail execution. Note Ansible also supports role specifications defined in the role `meta/main.yml` file, as well. However, any role that defines the specs within this file will not work on versions below 2.11. For this reason, we recommend using the `meta/argument_specs.yml` file to maintain backward compatibility. Note When role argument validation is used on a role that has defined [dependencies](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#role-dependencies) , then validation on those dependencies will run before the dependent role, even if argument validation fails for the dependent role. Note Ansible tags the inserted role argument validation task with [always](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_tags.html#special-tags) . If the role is [statically imported](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse.html#dynamic-vs-static) this task runs unless you use the `--skip-tags` flag. ### [Specification format](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#id10) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#specification-format "Link to this heading") The role argument specification must be defined in a top-level `argument_specs` block within the role `meta/argument_specs.yml` file. All fields are lowercase. entry-point-name: * The name of the role entry point. * This should be `main` in the case of an unspecified entry point. * This will be the base name of the tasks file to execute, with no `.yml` or `.yaml` file extension. short\_description: * A short, one-line description of the entry point. Ideally, it is a phrase and not a sentence. * The `short_description` is displayed by `ansible-doc -t role -l`. * It also becomes part of the title for the role page in the documentation. * The short description should always be a string and never a list, and should not end in a period. * You can use [Ansible markup](https://docs.ansible.com/projects/ansible/latest/dev_guide/ansible_markup.html#ansible-markup) in this field. description: * A longer description that may contain multiple lines. * This can be a single string or a list of strings. In case this is a list of strings, every list element is a new paragraph. * You can use [Ansible markup](https://docs.ansible.com/projects/ansible/latest/dev_guide/ansible_markup.html#ansible-markup) in this field. version\_added: * The version of the role when the entrypoint was added. * This is a string, and not a float, for example, `version_added: '2.1'`. * In collections, this must be the collection version the entrypoint was added to. For example, `version_added: 1.0.0`. author: * Name of the entry point authors. * This can be a single string or a list of strings. Use one list entry per author. If there is only a single author, use a string or a one-element list. options: * Options are often called “parameters” or “arguments”. This section defines those options. * For each role option (argument), you may include: option-name: * The name of the option/argument. description: * Detailed explanation of what this option does. It should be written in full sentences. * This can be a single string or a list of strings. In case this is a list of strings, every list element is a new paragraph. * You can use [Ansible markup](https://docs.ansible.com/projects/ansible/latest/dev_guide/ansible_markup.html#ansible-markup) in this field. version\_added: * Only needed if this option was added after the initial role/entry point 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.1'`. * In collections, this must be the collection version the option was added to. For example, `version_added: 1.0.0`. type: * The data type of the option. See [Argument spec](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_program_flow_modules.html#argument-spec) for allowed values for `type`. The default is `str`. * If an option is of type `list`, `elements` should be specified. required: * Only needed if `true`. * If missing, the option is not required. default: * If `required` is `false`/missing, `default` may be specified (assumed `null` if missing). * Ensure that the default value in the docs matches the default value in the code. The actual default for the role variable will always come from the role defaults (as defined in [Role directory structure](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#role-directory-structure) ). * The default field must not be listed as part of the description unless it requires additional information or conditions. * If the option is a boolean value, you should use `true`/`false` if you want to be compatible with `ansible-lint`. choices: * List of option values. * Should be absent if empty. elements: * Specifies the data type for list elements when the type is `list`. options: * If this option takes a dict or list of dicts, you can define the structure here. ### [Sample specification](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#id11) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#sample-specification "Link to this heading") \# roles/myapp/meta/argument\_specs.yml \--- argument\_specs: \# roles/myapp/tasks/main.yml entry point main: short\_description: Main entry point for the myapp role description: \- This is the main entrypoint for the C(myapp) role. \- Here we can describe what this entrypoint does in lengthy words. \- Every new list item is a new paragraph. You can have multiple sentences per paragraph. author: \- Daniel Ziegenberg options: myapp\_int: type: "int" required: false default: 42 description: \- "The integer value, defaulting to 42." \- "This is a second paragraph." myapp\_str: type: "str" required: true description: "The string value" myapp\_list: type: "list" elements: "str" required: true description: "A list of string values." version\_added: 1.3.0 myapp\_list\_with\_dicts: type: "list" elements: "dict" required: false default: \- myapp\_food\_kind: "meat" myapp\_food\_boiling\_required: true myapp\_food\_preparation\_time: 60 \- myapp\_food\_kind: "fruits" myapp\_food\_preparation\_time: 5 description: "A list of dicts with a defined structure and with default a value." options: myapp\_food\_kind: type: "str" choices: \- "vegetables" \- "fruits" \- "grains" \- "meat" required: false description: "A string value with a limited list of allowed choices." myapp\_food\_boiling\_required: type: "bool" required: false default: false description: "Whether the kind of food requires boiling before consumption." myapp\_food\_preparation\_time: type: int required: true description: "Time to prepare a dish in minutes." myapp\_dict\_with\_suboptions: type: "dict" required: false default: myapp\_host: "bar.foo" myapp\_exclude\_host: true myapp\_path: "/etc/myapp" description: "A dict with a defined structure and default values." options: myapp\_host: type: "str" choices: \- "foo.bar" \- "bar.foo" \- "ansible.foo.bar" required: true description: "A string value with a limited list of allowed choices." myapp\_exclude\_host: type: "bool" required: true description: "A boolean value." myapp\_path: type: "path" required: true description: "A path value." original\_name: type: list elements: "str" required: false description: "An optional list of string values." \# roles/myapp/tasks/alternate.yml entry point alternate: short\_description: Alternate entry point for the myapp role description: \- This is the alternate entrypoint for the C(myapp) role. version\_added: 1.2.0 options: myapp\_int: type: "int" required: false default: 1024 description: "The integer value, defaulting to 1024." [Running a role multiple times in one play](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#id12) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#running-a-role-multiple-times-in-one-play "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Ansible only executes each role once in a play, even if you define it multiple times unless the parameters defined on the role are different for each definition. For example, Ansible only runs the role `foo` once in a play like this: \--- \- hosts: webservers roles: \- foo \- bar \- foo You have two options to force Ansible to run a role more than once. ### [Passing different parameters](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#id13) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#passing-different-parameters "Link to this heading") If you pass different parameters in each role definition, Ansible runs the role more than once. Providing different variable values is not the same as passing different role parameters. You must use the `roles` keyword for this behavior, since `import_role` and `include_role` do not accept role parameters. This play runs the `foo` role twice: \--- \- hosts: webservers roles: \- { role: foo, message: "first" } \- { role: foo, message: "second" } This syntax also runs the `foo` role twice; \--- \- hosts: webservers roles: \- role: foo message: "first" \- role: foo message: "second" In these examples, Ansible runs `foo` twice because each role definition has different parameters. ### [Using `allow_duplicates: true`](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#id14) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#using-allow-duplicates-true "Link to this heading") Add `allow_duplicates: true` to the `meta/main.yml` file for the role: \# playbook.yml \--- \- hosts: webservers roles: \- foo \- foo \# roles/foo/meta/main.yml \--- allow\_duplicates: true In this example, Ansible runs `foo` twice because we have explicitly enabled it to do so. [Using role dependencies](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#id15) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#using-role-dependencies "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Role dependencies let you automatically pull in other roles when using a role. Role dependencies are prerequisites, not true dependencies. The roles do not have a parent/child relationship. Ansible loads all listed roles, runs the roles listed under `dependencies` first, then runs the role that lists them. The play object is the parent of all roles, including roles called by a `dependencies` list. Role dependencies are stored in the `meta/main.yml` file within the role directory. This file should contain a list of roles and parameters to insert before the specified role. For example: \# roles/myapp/meta/main.yml \--- dependencies: \- role: common vars: some\_parameter: 3 \- role: apache vars: apache\_port: 80 \- role: postgres vars: dbname: blarg other\_parameter: 12 Ansible always executes roles listed in `dependencies` before the role that lists them. Ansible executes this pattern recursively when you use the `roles` keyword. For example, if you list role `foo` under `roles:`, role `foo` lists role `bar` under `dependencies` in its meta/main.yml file, and role `bar` lists role `baz` under `dependencies` in its meta/main.yml, Ansible executes `baz`, then `bar`, then `foo`. ### [Running role dependencies multiple times in one play](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#id16) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#running-role-dependencies-multiple-times-in-one-play "Link to this heading") Ansible treats duplicate role dependencies like duplicate roles listed under `roles:`: Ansible only executes role dependencies once, even if defined multiple times, unless the parameters, tags, or when clause defined on the role are different for each definition. If two roles in a play both list a third role as a dependency, Ansible only runs that role dependency once, unless you pass different parameters, tags, when clause, or use `allow_duplicates: true` in the role you want to run multiple times. See [Galaxy role dependencies](https://docs.ansible.com/projects/ansible/latest/galaxy/user_guide.html#galaxy-dependencies) for more details. Note Role deduplication does not consult the invocation signature of parent roles. Additionally, when using `vars:` instead of role params, there is a side effect of changing variable scoping. Using `vars:` results in those variables being scoped at the play level. In the below example, using `vars:` would cause `n` to be defined as `4` throughout the entire play, including roles called before it. In addition to the above, users should be aware that role de-duplication occurs before variable evaluation. This means that [Lazy Evaluation](https://docs.ansible.com/projects/ansible/latest/reference_appendices/glossary.html#term-Lazy-Evaluation) may make seemingly different role invocations equivalently the same, preventing the role from running more than once. For example, a role named `car` depends on a role named `wheel` as follows: \--- dependencies: \- role: wheel n: 1 \- role: wheel n: 2 \- role: wheel n: 3 \- role: wheel n: 4 And the `wheel` role depends on two roles: `tire` and `brake`. The `meta/main.yml` for wheel would then contain the following: \--- dependencies: \- role: tire \- role: brake And the `meta/main.yml` for `tire` and `brake` would contain the following: \--- allow\_duplicates: true The resulting order of execution would be as follows: tire(n=1) brake(n=1) wheel(n=1) tire(n=2) brake(n=2) wheel(n=2) ... car To use `allow_duplicates: true` with role dependencies, you must specify it for the role listed under `dependencies`, not for the role that lists it. In the example above, `allow_duplicates: true` appears in the `meta/main.yml` of the `tire` and `brake` roles. The `wheel` role does not require `allow_duplicates: true`, because each instance defined by `car` uses different parameter values. Note See [Using variables](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#playbooks-variables) for details on how Ansible chooses among variable values defined in different places (variable inheritance and scope). Also, deduplication happens ONLY at the play level, so multiple plays in the same playbook may rerun the roles. [Embedding modules and plugins in roles](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#id17) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#embedding-modules-and-plugins-in-roles "Link to this heading") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Note This applies only to standalone roles. Roles in collections do not support plugin embedding; they must use the collection’s `plugins` structure to distribute plugins. If you write a custom module (see [Should you develop a module?](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules.html#developing-modules) ) or a plugin (see [Developing plugins](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_plugins.html#developing-plugins) ), you might wish to distribute it as part of a role. For example, if you write a module that helps configure your company’s internal software, and you want other people in your organization to use this module, but do not want to tell everyone how to configure their Ansible library path, you can include the module in your internal\_config role. To add a module or a plugin to a role: Alongside the ‘tasks’ and ‘handlers’ structure of a role, add a directory named ‘library’ and then include the module directly inside the ‘library’ directory. Assuming you had this: roles/ my\_custom\_modules/ library/ module1 module2 The module will be usable in the role itself, as well as any roles that are called _after_ this role, as follows: \--- \- hosts: webservers roles: \- my\_custom\_modules \- some\_other\_role\_using\_my\_custom\_modules \- yet\_another\_role\_using\_my\_custom\_modules If necessary, you can also embed a module in a role to modify a module in Ansible’s core distribution. For example, you can use the development version of a particular module before it is released in production releases by copying the module and embedding the copy in a role. Use this approach with caution, as API signatures may change in core components, and this workaround is not guaranteed to work. The same mechanism can be used to embed and distribute plugins in a role, using the same schema. For example, for a filter plugin: roles/ my\_custom\_filter/ filter\_plugins filter1 filter2 These filters can then be used in a Jinja template in any role called after ‘my\_custom\_filter’. [Sharing roles: Ansible Galaxy](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#id18) [](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#sharing-roles-ansible-galaxy "Link to this heading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- [Ansible Galaxy](https://galaxy.ansible.com/) is a free site for finding, downloading, rating, and reviewing all kinds of community-developed Ansible roles and can be a great way to get a jumpstart on your automation projects. The client `ansible-galaxy` is included in Ansible. The Galaxy client allows you to download roles from Ansible Galaxy and provides an excellent default framework for creating your own roles. Read the [Ansible Galaxy documentation](https://ansible.readthedocs.io/projects/galaxy-ng/en/latest/) page for more information. See also [Galaxy User Guide](https://docs.ansible.com/projects/ansible/latest/galaxy/user_guide.html#ansible-galaxy) How to create new roles, share roles on Galaxy, role management [YAML Syntax](https://docs.ansible.com/projects/ansible/latest/reference_appendices/YAMLSyntax.html#yaml-syntax) Learn about YAML syntax [Working with playbooks](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks.html#working-with-playbooks) Review the basic Playbook language features [General tips](https://docs.ansible.com/projects/ansible/latest/tips_tricks/ansible_tips_tricks.html#tips-and-tricks) Tips and tricks for playbooks [Using variables](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_variables.html#playbooks-variables) Variables in playbooks [Conditionals](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_conditionals.html#playbooks-conditionals) Conditionals in playbooks [Loops](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_loops.html#playbooks-loops) Loops in playbooks [Tags](https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_tags.html#tags) Using tags to select or skip roles/tasks in long playbooks [Collection Index](https://docs.ansible.com/projects/ansible/latest/collections/index.html#list-of-collections) Browse existing collections, modules, and plugins [Should you develop a module?](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules.html#developing-modules) Extending Ansible by writing your own modules [Communication](https://docs.ansible.com/projects/ansible/latest/community/communication.html#communication) Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide --- # Collection Index — Ansible Community Documentation * [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [![Ansible Logo](https://docs.ansible.com/projects/ansible/latest/_static/images/Ansible-Mark-RGB_White.png)\ \ Ansible Community Documentation](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * Collection Index * * * * Collection Index[](https://docs.ansible.com/projects/ansible/latest/collections/index.html#collection-index "Link to this heading") ===================================================================================================================================== These are the collections with docs hosted on [docs.ansible.com](https://docs.ansible.com/) . * [amazon.aws](https://docs.ansible.com/projects/ansible/latest/collections/amazon/aws/index.html#plugins-in-amazon-aws) * [ansible.builtin](https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/index.html#plugins-in-ansible-builtin) * [ansible.netcommon](https://docs.ansible.com/projects/ansible/latest/collections/ansible/netcommon/index.html#plugins-in-ansible-netcommon) * [ansible.posix](https://docs.ansible.com/projects/ansible/latest/collections/ansible/posix/index.html#plugins-in-ansible-posix) * [ansible.utils](https://docs.ansible.com/projects/ansible/latest/collections/ansible/utils/index.html#plugins-in-ansible-utils) * [ansible.windows](https://docs.ansible.com/projects/ansible/latest/collections/ansible/windows/index.html#plugins-in-ansible-windows) * [arista.eos](https://docs.ansible.com/projects/ansible/latest/collections/arista/eos/index.html#plugins-in-arista-eos) * [awx.awx](https://docs.ansible.com/projects/ansible/latest/collections/awx/awx/index.html#plugins-in-awx-awx) **DEPRECATED: REMOVED IN 14** * [azure.azcollection](https://docs.ansible.com/projects/ansible/latest/collections/azure/azcollection/index.html#plugins-in-azure-azcollection) * [check\_point.mgmt](https://docs.ansible.com/projects/ansible/latest/collections/check_point/mgmt/index.html#plugins-in-check-point-mgmt) * [chocolatey.chocolatey](https://docs.ansible.com/projects/ansible/latest/collections/chocolatey/chocolatey/index.html#plugins-in-chocolatey-chocolatey) * [cisco.aci](https://docs.ansible.com/projects/ansible/latest/collections/cisco/aci/index.html#plugins-in-cisco-aci) * [cisco.dnac](https://docs.ansible.com/projects/ansible/latest/collections/cisco/dnac/index.html#plugins-in-cisco-dnac) **DEPRECATED: REMOVED IN 14** * [cisco.intersight](https://docs.ansible.com/projects/ansible/latest/collections/cisco/intersight/index.html#plugins-in-cisco-intersight) * [cisco.ios](https://docs.ansible.com/projects/ansible/latest/collections/cisco/ios/index.html#plugins-in-cisco-ios) * [cisco.iosxr](https://docs.ansible.com/projects/ansible/latest/collections/cisco/iosxr/index.html#plugins-in-cisco-iosxr) * [cisco.meraki](https://docs.ansible.com/projects/ansible/latest/collections/cisco/meraki/index.html#plugins-in-cisco-meraki) * [cisco.mso](https://docs.ansible.com/projects/ansible/latest/collections/cisco/mso/index.html#plugins-in-cisco-mso) * [cisco.nxos](https://docs.ansible.com/projects/ansible/latest/collections/cisco/nxos/index.html#plugins-in-cisco-nxos) * [cisco.ucs](https://docs.ansible.com/projects/ansible/latest/collections/cisco/ucs/index.html#plugins-in-cisco-ucs) * [cloudscale\_ch.cloud](https://docs.ansible.com/projects/ansible/latest/collections/cloudscale_ch/cloud/index.html#plugins-in-cloudscale-ch-cloud) * [community.aws](https://docs.ansible.com/projects/ansible/latest/collections/community/aws/index.html#plugins-in-community-aws) * [community.ciscosmb](https://docs.ansible.com/projects/ansible/latest/collections/community/ciscosmb/index.html#plugins-in-community-ciscosmb) * [community.clickhouse](https://docs.ansible.com/projects/ansible/latest/collections/community/clickhouse/index.html#plugins-in-community-clickhouse) * [community.crypto](https://docs.ansible.com/projects/ansible/latest/collections/community/crypto/index.html#plugins-in-community-crypto) * [community.dns](https://docs.ansible.com/projects/ansible/latest/collections/community/dns/index.html#plugins-in-community-dns) * [community.docker](https://docs.ansible.com/projects/ansible/latest/collections/community/docker/index.html#plugins-in-community-docker) * [community.general](https://docs.ansible.com/projects/ansible/latest/collections/community/general/index.html#plugins-in-community-general) * [community.grafana](https://docs.ansible.com/projects/ansible/latest/collections/community/grafana/index.html#plugins-in-community-grafana) * [community.hashi\_vault](https://docs.ansible.com/projects/ansible/latest/collections/community/hashi_vault/index.html#plugins-in-community-hashi-vault) * [community.hrobot](https://docs.ansible.com/projects/ansible/latest/collections/community/hrobot/index.html#plugins-in-community-hrobot) * [community.library\_inventory\_filtering\_v1](https://docs.ansible.com/projects/ansible/latest/collections/community/library_inventory_filtering_v1/index.html#plugins-in-community-library-inventory-filtering-v1) * [community.libvirt](https://docs.ansible.com/projects/ansible/latest/collections/community/libvirt/index.html#plugins-in-community-libvirt) * [community.mongodb](https://docs.ansible.com/projects/ansible/latest/collections/community/mongodb/index.html#plugins-in-community-mongodb) * [community.mysql](https://docs.ansible.com/projects/ansible/latest/collections/community/mysql/index.html#plugins-in-community-mysql) * [community.okd](https://docs.ansible.com/projects/ansible/latest/collections/community/okd/index.html#plugins-in-community-okd) * [community.postgresql](https://docs.ansible.com/projects/ansible/latest/collections/community/postgresql/index.html#plugins-in-community-postgresql) * [community.proxmox](https://docs.ansible.com/projects/ansible/latest/collections/community/proxmox/index.html#plugins-in-community-proxmox) * [community.proxysql](https://docs.ansible.com/projects/ansible/latest/collections/community/proxysql/index.html#plugins-in-community-proxysql) * [community.rabbitmq](https://docs.ansible.com/projects/ansible/latest/collections/community/rabbitmq/index.html#plugins-in-community-rabbitmq) * [community.routeros](https://docs.ansible.com/projects/ansible/latest/collections/community/routeros/index.html#plugins-in-community-routeros) * [community.sap\_libs](https://docs.ansible.com/projects/ansible/latest/collections/community/sap_libs/index.html#plugins-in-community-sap-libs) * [community.sops](https://docs.ansible.com/projects/ansible/latest/collections/community/sops/index.html#plugins-in-community-sops) * [community.vmware](https://docs.ansible.com/projects/ansible/latest/collections/community/vmware/index.html#plugins-in-community-vmware) * [community.windows](https://docs.ansible.com/projects/ansible/latest/collections/community/windows/index.html#plugins-in-community-windows) * [community.zabbix](https://docs.ansible.com/projects/ansible/latest/collections/community/zabbix/index.html#plugins-in-community-zabbix) * [containers.podman](https://docs.ansible.com/projects/ansible/latest/collections/containers/podman/index.html#plugins-in-containers-podman) * [cyberark.conjur](https://docs.ansible.com/projects/ansible/latest/collections/cyberark/conjur/index.html#plugins-in-cyberark-conjur) * [cyberark.pas](https://docs.ansible.com/projects/ansible/latest/collections/cyberark/pas/index.html#plugins-in-cyberark-pas) * [dellemc.enterprise\_sonic](https://docs.ansible.com/projects/ansible/latest/collections/dellemc/enterprise_sonic/index.html#plugins-in-dellemc-enterprise-sonic) * [dellemc.openmanage](https://docs.ansible.com/projects/ansible/latest/collections/dellemc/openmanage/index.html#plugins-in-dellemc-openmanage) * [dellemc.powerflex](https://docs.ansible.com/projects/ansible/latest/collections/dellemc/powerflex/index.html#plugins-in-dellemc-powerflex) * [dellemc.unity](https://docs.ansible.com/projects/ansible/latest/collections/dellemc/unity/index.html#plugins-in-dellemc-unity) * [f5networks.f5\_modules](https://docs.ansible.com/projects/ansible/latest/collections/f5networks/f5_modules/index.html#plugins-in-f5networks-f5-modules) * [fortinet.fortimanager](https://docs.ansible.com/projects/ansible/latest/collections/fortinet/fortimanager/index.html#plugins-in-fortinet-fortimanager) * [fortinet.fortios](https://docs.ansible.com/projects/ansible/latest/collections/fortinet/fortios/index.html#plugins-in-fortinet-fortios) * [google.cloud](https://docs.ansible.com/projects/ansible/latest/collections/google/cloud/index.html#plugins-in-google-cloud) * [grafana.grafana](https://docs.ansible.com/projects/ansible/latest/collections/grafana/grafana/index.html#plugins-in-grafana-grafana) * [graphiant.naas](https://docs.ansible.com/projects/ansible/latest/collections/graphiant/naas/index.html#plugins-in-graphiant-naas) * [hetzner.hcloud](https://docs.ansible.com/projects/ansible/latest/collections/hetzner/hcloud/index.html#plugins-in-hetzner-hcloud) * [hitachivantara.vspone\_block](https://docs.ansible.com/projects/ansible/latest/collections/hitachivantara/vspone_block/index.html#plugins-in-hitachivantara-vspone-block) * [hitachivantara.vspone\_object](https://docs.ansible.com/projects/ansible/latest/collections/hitachivantara/vspone_object/index.html#plugins-in-hitachivantara-vspone-object) * [ibm.storage\_virtualize](https://docs.ansible.com/projects/ansible/latest/collections/ibm/storage_virtualize/index.html#plugins-in-ibm-storage-virtualize) * [ieisystem.inmanage](https://docs.ansible.com/projects/ansible/latest/collections/ieisystem/inmanage/index.html#plugins-in-ieisystem-inmanage) * [infinidat.infinibox](https://docs.ansible.com/projects/ansible/latest/collections/infinidat/infinibox/index.html#plugins-in-infinidat-infinibox) * [infoblox.nios\_modules](https://docs.ansible.com/projects/ansible/latest/collections/infoblox/nios_modules/index.html#plugins-in-infoblox-nios-modules) * [inspur.ispim](https://docs.ansible.com/projects/ansible/latest/collections/inspur/ispim/index.html#plugins-in-inspur-ispim) * [junipernetworks.junos](https://docs.ansible.com/projects/ansible/latest/collections/junipernetworks/junos/index.html#plugins-in-junipernetworks-junos) **DEPRECATED: REMOVED IN 14** * [kaytus.ksmanage](https://docs.ansible.com/projects/ansible/latest/collections/kaytus/ksmanage/index.html#plugins-in-kaytus-ksmanage) * [kubernetes.core](https://docs.ansible.com/projects/ansible/latest/collections/kubernetes/core/index.html#plugins-in-kubernetes-core) * [kubevirt.core](https://docs.ansible.com/projects/ansible/latest/collections/kubevirt/core/index.html#plugins-in-kubevirt-core) * [lowlydba.sqlserver](https://docs.ansible.com/projects/ansible/latest/collections/lowlydba/sqlserver/index.html#plugins-in-lowlydba-sqlserver) * [microsoft.ad](https://docs.ansible.com/projects/ansible/latest/collections/microsoft/ad/index.html#plugins-in-microsoft-ad) * [microsoft.iis](https://docs.ansible.com/projects/ansible/latest/collections/microsoft/iis/index.html#plugins-in-microsoft-iis) * [netapp.cloudmanager](https://docs.ansible.com/projects/ansible/latest/collections/netapp/cloudmanager/index.html#plugins-in-netapp-cloudmanager) **DEPRECATED: REMOVED IN 15** * [netapp.ontap](https://docs.ansible.com/projects/ansible/latest/collections/netapp/ontap/index.html#plugins-in-netapp-ontap) * [netapp.storagegrid](https://docs.ansible.com/projects/ansible/latest/collections/netapp/storagegrid/index.html#plugins-in-netapp-storagegrid) * [netapp\_eseries.santricity](https://docs.ansible.com/projects/ansible/latest/collections/netapp_eseries/santricity/index.html#plugins-in-netapp-eseries-santricity) * [netbox.netbox](https://docs.ansible.com/projects/ansible/latest/collections/netbox/netbox/index.html#plugins-in-netbox-netbox) * [ngine\_io.cloudstack](https://docs.ansible.com/projects/ansible/latest/collections/ngine_io/cloudstack/index.html#plugins-in-ngine-io-cloudstack) * [openstack.cloud](https://docs.ansible.com/projects/ansible/latest/collections/openstack/cloud/index.html#plugins-in-openstack-cloud) * [ovirt.ovirt](https://docs.ansible.com/projects/ansible/latest/collections/ovirt/ovirt/index.html#plugins-in-ovirt-ovirt) * [pcg.alpaca\_operator](https://docs.ansible.com/projects/ansible/latest/collections/pcg/alpaca_operator/index.html#plugins-in-pcg-alpaca-operator) * [purestorage.flasharray](https://docs.ansible.com/projects/ansible/latest/collections/purestorage/flasharray/index.html#plugins-in-purestorage-flasharray) * [purestorage.flashblade](https://docs.ansible.com/projects/ansible/latest/collections/purestorage/flashblade/index.html#plugins-in-purestorage-flashblade) * [ravendb.ravendb](https://docs.ansible.com/projects/ansible/latest/collections/ravendb/ravendb/index.html#plugins-in-ravendb-ravendb) * [splunk.es](https://docs.ansible.com/projects/ansible/latest/collections/splunk/es/index.html#plugins-in-splunk-es) * [telekom\_mms.icinga\_director](https://docs.ansible.com/projects/ansible/latest/collections/telekom_mms/icinga_director/index.html#plugins-in-telekom-mms-icinga-director) * [theforeman.foreman](https://docs.ansible.com/projects/ansible/latest/collections/theforeman/foreman/index.html#plugins-in-theforeman-foreman) * [vmware.vmware](https://docs.ansible.com/projects/ansible/latest/collections/vmware/vmware/index.html#plugins-in-vmware-vmware) * [vmware.vmware\_rest](https://docs.ansible.com/projects/ansible/latest/collections/vmware/vmware_rest/index.html#plugins-in-vmware-vmware-rest) * [vultr.cloud](https://docs.ansible.com/projects/ansible/latest/collections/vultr/cloud/index.html#plugins-in-vultr-cloud) * [vyos.vyos](https://docs.ansible.com/projects/ansible/latest/collections/vyos/vyos/index.html#plugins-in-vyos-vyos) * [wti.remote](https://docs.ansible.com/projects/ansible/latest/collections/wti/remote/index.html#plugins-in-wti-remote) ---