# Ansible Documentation

## About Ansible

Ansible is an IT automation tool. It can configure systems, deploy software, and orchestrate more advanced IT tasks such as continuous deployments or zero downtime rolling updates.

Ansible’s main goals are simplicity and ease-of-use. It also has a strong focus on security and reliability, featuring a minimum of moving parts, usage of OpenSSH for transport (with other transports and pull modes as alternatives), and a language that is designed around auditability by humans–even those not familiar with the program.

We believe simplicity is relevant to all sizes of environments, so we design for busy users of all types: developers, sysadmins, release engineers, IT managers, and everyone in between. Ansible is appropriate for managing all environments, from small setups with a handful of instances to enterprise environments with many thousands of instances.

Ansible manages machines in an agent-less manner. There is never a question of how to upgrade remote daemons or the problem of not being able to manage systems because daemons are uninstalled. Because OpenSSH is one of the most peer-reviewed open source components, security exposure is greatly reduced. Ansible is decentralized–it relies on your existing OS credentials to control access to remote machines. If needed, Ansible can easily connect with Kerberos, LDAP, and other centralized authentication management systems.

This documentation covers the current released version of Ansible (2.5) and also some development version features. For recent features, we note in each section the version of Ansible where the feature was added.

Ansible releases a new major release of Ansible approximately every two months. The core application evolves somewhat conservatively, valuing simplicity in language design and setup. However, the community around new modules and plugins being developed and contributed moves very quickly, adding many new modules in each release.

Installation, Upgrade & Configuration

- Installation Guide
  - Basics / What Will Be Installed
  - What Version To Pick?
  - Control Machine Requirements
  - Managed Node Requirements
  - Installing the Control Machine
  - Ansible on GitHub
- Configuring Ansible
  - Configuration file
  - Environmental configuration
  - Command line options
- Ansible Porting Guides
  - Ansible 2.0 Porting Guide
  - Ansible 2.3 Porting Guide
  - Ansible 2.4 Porting Guide
  - Ansible 2.5 Porting Guide
  - Ansible 2.6 Porting Guide

Using Ansible

- User Guide
  - Ansible Quickstart
  - Getting Started
  - Working with Command Line Tools
  - Introduction To Ad-Hoc Commands
  - Working with Inventory
  - Working With Dynamic Inventory
  - Working With Playbooks
  - Understanding Privilege Escalation
  - Ansible Vault
  - Working with Patterns
  - Working With Modules
  - Working With Plugins
  - BSD Support
  - Windows Guides

Contributing to Ansible

- Ansible Community Guide
  - Community Code of Conduct
  - The Ansible Development Process
  - Road Maps
  - Pull Requests
  - Ansibullbot
  - Reporting Bugs And Requesting Features
  - How To Help
  - Module Maintainer Guidelines
  - Release Managers
  - Release Process
  - Communicating
  - Other Tools And Programs

Extending Ansible

- Developer Guide
  - Ansible Architecture
  - Developing Modules
  - Ansible Module Architecture
  - Appendix: Module Utilities
  - Developing Plugins
  - Developing Dynamic Inventory Sources
  - Developing the Ansible Core Engine
  - Ansible and Python 3
  - Python API
  - Rebasing a Pull Request
  - Testing Ansible
  - Repo Merge
  - Release and maintenance
  - Committers Guidelines (for people with commit rights to Ansible on GitHub)
  - Ansible Style Guide

Scenario Guides

- Cisco ACI Guide
  - What is Cisco ACI ?
  - Using the ACI modules
  - ACI authentication
  - Using ACI REST with Ansible
  - Operational examples
  - APIC error messages
  - Known issues
  - ACI Ansible community
- Amazon Web Services Guide
  - Introduction
  - Authentication
  - Provisioning
  - Host Inventory
  - Tags And Groups And Variables
  - Autoscaling with Ansible Pull
  - Autoscaling with Ansible Tower
  - Ansible With (And Versus) CloudFormation
  - AWS Image Building With Ansible
  - Next Steps: Explore Modules
- Microsoft Azure Guide
  - Requirements
  - Authenticating with Azure
  - Other Cloud Environments
  - Creating Virtual Machines
  - Dynamic Inventory Script
- CloudStack Cloud Guide
  - Introduction
  - Prerequisites
  - Limitations and Known Issues
  - Credentials File
  - Regions
  - Environment Variables
  - Use Cases
- Getting Started with Docker
  - Requirements
  - Connecting to the Docker API
  - Dynamic Inventory Script
- Google Cloud Platform Guide
  - Introduction
  - Introduction
  - Credentials
  - GCE Dynamic Inventory
- Using Ansible with the Packet host
  - Introduction
  - Requirements
  - Device Creation
  - Updating Devices
  - More Complex Playbooks
  - Dynamic Inventory Script
- Rackspace Cloud Guide
  - Introduction
  - Credentials File
  - Provisioning
  - Host Inventory
  - Use Cases
  - Advanced Usage
- Continuous Delivery and Rolling Upgrades
  - Introduction
  - Site Deployment
  - Reusable Content: Roles
  - Configuration: Group Variables
  - The Rolling Upgrade
  - Managing Other Load Balancers
  - Continuous Delivery End-To-End
- Using Vagrant and Ansible
  - Introduction
  - Vagrant Setup
  - Running Ansible Manually
  - Advanced Usages

Ansible for VMWare

- Ansible for VMware
  - Introduction to Ansible for VMware
  - Ansible for VMware Concepts
  - VMware Prerequisites
  - Getting Started with Ansible for VMware
  - Ansible for VMware Scenarios
  - Ansible VMware Module Guide
  - Troubleshooting Ansible for VMware
  - List of useful links to VMware
  - Ansible VMware FAQ

Ansible for Network Automation

- Ansible for Network Automation
  - Getting Started with Ansible for Network Automation
  - Advanced Topics with Ansible for Network Automation

Reference & Appendices

- Ansible Galaxy
  - The Website
  - The command line tool
- Return Values
  - Common
  - Internal use
- YAML Syntax
  - YAML Basics
  - Gotchas
- Python 3 Support
  - On the controller side
  - Using Python 3 on the managed machines with commands and playbooks
  - What to do if an incompatibility is found
- Release and maintenance
  - Release cycle
  - Release status
  - Development and stable version maintenance workflow
  - Deprecation Cycle
- Testing Strategies
  - Integrating Testing With Ansible Playbooks
  - The Right Level of Testing
  - Check Mode As A Drift Test
  - Modules That Are Useful for Testing
  - Testing Lifecycle
  - Integrating Testing With Rolling Updates
  - Achieving Continuous Deployment
  - Conclusion
- Frequently Asked Questions
  - How can I set the PATH or any other environment variable for a task or entire playbook?
  - How do I handle different machines needing different user accounts or ports to log in with?
  - How do I get ansible to reuse connections, enable Kerberized SSH, or have Ansible pay attention to my local SSH config file?
  - How do I configure a jump host to access servers that I have no direct access to?
  - How do I speed up management inside EC2?
  - How do I handle python not having a Python interpreter at /usr/bin/python on a remote machine?
  - Common Platform Issues
  - What is the best way to make content reusable/redistributable?
  - Where does the configuration file live and what can I configure in it?
  - How do I disable cowsay?
  - How do I see a list of all of the ansible_ variables?
  - How do I see all the inventory vars defined for my host?
  - How do I loop over a list of hosts in a group, inside of a template?
  - How do I access a variable name programmatically?
  - How do I access a variable of the first host in a group?
  - How do I copy files recursively onto a target host?
  - How do I access shell environment variables?
  - How do I generate crypted passwords for the user module?
  - Ansible supports dot notation and array notation for variables. Which notation should I use?
  - Can I get training on Ansible?
  - Is there a web interface / REST API / etc?
  - How do I submit a change to the documentation?
  - How do I keep secret data in my playbook?
  - When should I use {{ }}? Also, how to interpolate variables or dynamic variable names
  - Why don’t you ship in X format?
  - I don’t see my question here
- Glossary
- Ansible Tower

Roadmaps

- Ansible Roadmap
  - Ansible 2.1
  - Ansible 2.2
  - Ansible 2.3
  - Ansible 2.4
  - Ansible 2.5
  - Ansible 2.6