1******************** 2Ansible architecture 3******************** 4 5Ansible is a radically simple IT automation engine that automates cloud provisioning, configuration management, application deployment, intra-service orchestration, and many other IT needs. 6 7Being 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. 8 9It uses no agents and no additional custom security infrastructure, so it's easy to deploy - and most importantly, it uses a very simple language (YAML, in the form of Ansible Playbooks) that allow you to describe your automation jobs in a way that approaches plain English. 10 11In this section, we'll give you a really quick overview of how Ansible works so you can see how the pieces fit together. 12 13.. contents:: 14 :local: 15 16Modules 17======= 18 19Ansible 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. 20Ansible 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. 21 22You can :ref:`write your own modules <developing_modules_general>`, though you should first consider :ref:`whether you should <developing_modules>`. Typically you'll work with your favorite terminal program, a text editor, and probably a version control system to keep track of changes to your content. You may write specialized modules in any language that can return JSON (Ruby, Python, bash, and so on). 23 24Module utilities 25================ 26 27When multiple modules use the same code, Ansible stores those functions as module utilities to minimize duplication and maintenance. For example, the code that parses URLs is ``lib/ansible/module_utils/url.py``. You can :ref:`write your own module utilities <developing_module_utilities>` as well. Module utilities may only be written in Python or in PowerShell. 28 29Plugins 30======= 31 32:ref:`Plugins <plugins_lookup>` augment Ansible's core functionality. While modules execute on the target system in separate processes (usually that means on a remote system), plugins execute on the control node within the ``/usr/bin/ansible`` process. Plugins offer options and extensions for the core features of Ansible - transforming data, logging output, connecting to inventory, and more. Ansible ships with a number of handy plugins, and you can easily :ref:`write your own <developing_plugins>`. For example, you can write an :ref:`inventory plugin <developing_inventory>` to connect to any datasource that returns JSON. Plugins must be written in Python. 33 34Inventory 35========= 36 37By 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. 38 39To 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. 40 41If 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. 42 43Here's what a plain text inventory file looks like:: 44 45 --- 46 [webservers] 47 www1.example.com 48 www2.example.com 49 50 [dbservers] 51 db0.example.com 52 db1.example.com 53 54Once 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. 55 56Or, as already mentioned, use a dynamic inventory to pull your inventory from data sources like EC2, Rackspace, or OpenStack. 57 58Playbooks 59========= 60 61Playbooks 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. 62 63Ansible'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. 64 65Here's what a simple playbook looks like:: 66 67 --- 68 - hosts: webservers 69 serial: 5 # update 5 machines at a time 70 roles: 71 - common 72 - webapp 73 74 - hosts: content_servers 75 roles: 76 - common 77 - content 78 79.. _ansible_search_path: 80 81The Ansible search path 82======================= 83 84Modules, module utilities, plugins, playbooks, and roles can live in multiple locations. If you 85write 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. 86 87Ansible's search path grows incrementally over a run. As 88Ansible finds each playbook and role included in a given run, it appends 89any directories related to that playbook or role to the search path. Those 90directories remain in scope for the duration of the run, even after the playbook or role 91has finished executing. Ansible loads modules, module utilities, and plugins in this order: 92 931. 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: 94 95 .. code-block:: bash 96 97 /path/to/modules 98 /path/to/module_utils 99 /path/to/plugins 100 1012. Directories adjacent to a playbook that is statically imported by a 102 playbook specified on the command line. If ``play.yml`` includes 103 ``- import_playbook: /path/to/subdir/play1.yml``, Ansible appends these directories if they exist: 104 105 .. code-block:: bash 106 107 /path/to/subdir/modules 108 /path/to/subdir/module_utils 109 /path/to/subdir/plugins 110 1113. Subdirectories of a role directory referenced by a playbook. If 112 ``play.yml`` runs ``myrole``, Ansible appends these directories if they exist: 113 114 .. code-block:: bash 115 116 /path/to/roles/myrole/modules 117 /path/to/roles/myrole/module_utils 118 /path/to/roles/myrole/plugins 119 1204. Directories specified as default paths in ``ansible.cfg`` or by the related 121 environment variables, including the paths for the various plugin types. See :ref:`ansible_configuration_settings` for more information. 122 Sample ``ansible.cfg`` fields: 123 124 .. code-block:: bash 125 126 DEFAULT_MODULE_PATH 127 DEFAULT_MODULE_UTILS_PATH 128 DEFAULT_CACHE_PLUGIN_PATH 129 DEFAULT_FILTER_PLUGIN_PATH 130 131 Sample environment variables: 132 133 .. code-block:: bash 134 135 ANSIBLE_LIBRARY 136 ANSIBLE_MODULE_UTILS 137 ANSIBLE_CACHE_PLUGINS 138 ANSIBLE_FILTER_PLUGINS 139 1405. The standard directories that ship as part of the Ansible distribution. 141 142.. caution:: 143 144 Modules, module utilities, and plugins in user-specified directories will 145 override the standard versions. This includes some files with generic names. 146 For example, if you have a file named ``basic.py`` in a user-specified 147 directory, it will override the standard ``ansible.module_utils.basic``. 148 149 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. 150