As described in :doc:`../intro_dynamic_inventory`, Ansible can pull inventory information from dynamic sources, including cloud sources. You can also create a new dynamic inventory provider by creating a script or program that can output JSON in the correct format when invoked with the proper arguments. There is no restriction on the language used for creating a dynamic inventory provider.
As described in :ref:`dynamic_inventory`, Ansible can pull inventory information from dynamic sources, including cloud sources. You can also create a new dynamic inventory provider by creating a script or program that can output JSON in the correct format when invoked with the proper arguments. There is no restriction on the language used for creating a dynamic inventory provider.
@ -188,7 +188,7 @@ The following fields can be used and are all required unless specified otherwise
:module:
:module:
The name of the module. This must be the same as the filename, without the ``.py`` extension.
The name of the module. This must be the same as the filename, without the ``.py`` extension.
:short_description:
:short_description:
* A short description which is displayed on the :doc:`../list_of_all_modules` page and ``ansible-doc -l``.
* A short description which is displayed on the :ref:`all_modules` page and ``ansible-doc -l``.
* As the short description is displayed by ``ansible-doc -l`` without the category grouping it needs enough detail to explain its purpose without the context of the directory structure in which it lives.
* As the short description is displayed by ``ansible-doc -l`` without the category grouping it needs enough detail to explain its purpose without the context of the directory structure in which it lives.
* Unlike ``description:`` this field should not have a trailing full stop.
* Unlike ``description:`` this field should not have a trailing full stop.
@ -22,12 +22,12 @@ Although it's tempting to get straight into coding, there are a few things to be
* For new modules going into Ansible 2.4 we are raising the bar so they must be PEP 8 compliant. See :doc:`testing_pep8` for more information.
* For new modules going into Ansible 2.4 we are raising the bar so they must be PEP 8 compliant. See :doc:`testing_pep8` for more information.
* Starting with Ansible version 2.4, all new modules must support Python 2.6 and Python 3.5+. If this is an issue, please contact us (see the "Speak to us" section later in this document to learn how).
* Starting with Ansible version 2.4, all new modules must support Python 2.6 and Python 3.5+. If this is an issue, please contact us (see the "Speak to us" section later in this document to learn how).
* All modules shipped with Ansible must be done so under the GPLv3 license. Files under the ``lib/ansible/module_utils/`` directory should be done so under the BSD license.
* All modules shipped with Ansible must be done so under the GPLv3 license. Files under the ``lib/ansible/module_utils/`` directory should be done so under the BSD license.
* Have a look at the existing modules and how they've been named in the :doc:`../list_of_all_modules`, especially in the same functional area (such as cloud, networking, databases).
* Have a look at the existing modules and how they've been named in the :ref:`all_modules`, especially in the same functional area (such as cloud, networking, databases).
* Shared code can be placed into ``lib/ansible/module_utils/``
* Shared code can be placed into ``lib/ansible/module_utils/``
* Shared documentation (for example describing common arguments) can be placed in ``lib/ansible/utils/module_docs_fragments/``.
* Shared documentation (for example describing common arguments) can be placed in ``lib/ansible/utils/module_docs_fragments/``.
* With great power comes great responsibility: Ansible module maintainers have a duty to help keep modules up to date. As with all successful community projects, module maintainers should keep a watchful eye for reported issues and contributions.
* With great power comes great responsibility: Ansible module maintainers have a duty to help keep modules up to date. As with all successful community projects, module maintainers should keep a watchful eye for reported issues and contributions.
* Although not required, unit and/or integration tests are strongly recommended. Unit tests are especially valuable when external resources (such as cloud or network devices) are required. For more information see :doc:`testing` and the `Testing Working Group <https://github.com/ansible/community/blob/master/meetings/README.md>`_.
* Although not required, unit and/or integration tests are strongly recommended. Unit tests are especially valuable when external resources (such as cloud or network devices) are required. For more information see :doc:`testing` and the `Testing Working Group <https://github.com/ansible/community/blob/master/meetings/README.md>`_.
* Starting with Ansible 2.4 all :doc:`../list_of_network_modules` MUST have unit tests.
* Starting with Ansible 2.4 all :ref:`network_modules` MUST have unit tests.
Naming Convention
Naming Convention
@ -37,7 +37,7 @@ As you may have noticed when looking under ``lib/ansible/modules/`` we support u
The directory name should represent the *product* or *OS* name, not the company name.
The directory name should represent the *product* or *OS* name, not the company name.
Each module should have the above (or similar) prefix; see existing :doc:`../list_of_all_modules` for existing examples.
Each module should have the above (or similar) prefix; see existing :ref:`all_modules` for existing examples.
**Note:**
**Note:**
@ -61,7 +61,7 @@ Where to get support
Ansible has a thriving and knowledgeable community of module developers that is a great resource for getting your questions answered.
Ansible has a thriving and knowledgeable community of module developers that is a great resource for getting your questions answered.
On :doc:`../community` you can find how to:
In the :ref:`ansible_community_guide` you can find how to:
* Subscribe to the Mailing Lists - We suggest "Ansible Development List" (for codefreeze info) and "Ansible Announce list"
* Subscribe to the Mailing Lists - We suggest "Ansible Development List" (for codefreeze info) and "Ansible Announce list"
* ``#ansible-devel`` - We have found that IRC ``#ansible-devel`` on FreeNode's IRC network works best for module developers so we can have an interactive dialogue.
* ``#ansible-devel`` - We have found that IRC ``#ansible-devel`` on FreeNode's IRC network works best for module developers so we can have an interactive dialogue.
@ -93,7 +93,7 @@ And that's it.
Before pushing your PR to GitHub it's a good idea to review the :doc:`developing_modules_checklist` again.
Before pushing your PR to GitHub it's a good idea to review the :doc:`developing_modules_checklist` again.
After publishing your PR to https://github.com/ansible/ansible, a Shippable CI test should run within a few minutes. Check the results (at the end of the PR page) to ensure that it's passing (green). If it's not passing, inspect each of the results. Most of the errors should be self-explanatory and are often related to badly formatted documentation (see :doc:`../YAMLSyntax`) or code that isn't valid Python 2.6 or valid Python 3.5 (see :doc:`developing_python3`). If you aren't sure what a Shippable test message means, copy it into the PR along with a comment and we will review.
After publishing your PR to https://github.com/ansible/ansible, a Shippable CI test should run within a few minutes. Check the results (at the end of the PR page) to ensure that it's passing (green). If it's not passing, inspect each of the results. Most of the errors should be self-explanatory and are often related to badly formatted documentation (see :ref:`yaml_syntax`) or code that isn't valid Python 2.6 or valid Python 3.5 (see :ref:`developing_python_3`). If you aren't sure what a Shippable test message means, copy it into the PR along with a comment and we will review.
If you need further advice, consider join the ``#ansible-devel`` IRC channel (see how in the "Where to get support").
If you need further advice, consider join the ``#ansible-devel`` IRC channel (see how in the "Where to get support").
@ -149,7 +151,7 @@ Connection plugins allow Ansible to connect to the target hosts so it can execut
By default, Ansible ships with several plugins. The most commonly used are the 'paramiko' SSH, native ssh (just called 'ssh'), and 'local' connection types. All of these can be used in playbooks and with /usr/bin/ansible to decide how you want to talk to remote machines.
By default, Ansible ships with several plugins. The most commonly used are the 'paramiko' SSH, native ssh (just called 'ssh'), and 'local' connection types. All of these can be used in playbooks and with /usr/bin/ansible to decide how you want to talk to remote machines.
The basics of these connection types are covered in the :doc:`../intro_getting_started` section.
The basics of these connection types are covered in the :ref:`intro_getting_started` section.
Should you want to extend Ansible to support other transports (SNMP, Message bus, etc) it's as simple as copying the format of one of the existing modules and dropping it into the connection plugins directory.
Should you want to extend Ansible to support other transports (SNMP, Message bus, etc) it's as simple as copying the format of one of the existing modules and dropping it into the connection plugins directory.
@ -362,8 +364,8 @@ When shipped as part of a role, the plugin will be available as soon as the role
@ -15,9 +15,9 @@ We believe simplicity is relevant to all sizes of environments, so we design for
Ansible manages machines in an agent-less manner. There is never a question of how to
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.
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.3) and also some development version features (2.4). For recent features, we note in each section the version of Ansible where the feature was added.
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, Inc. 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, typically adding 20 or so new modules in each release.
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.
..toctree::
..toctree::
@ -80,6 +80,7 @@ Ansible, Inc. releases a new major release of Ansible approximately every two mo
An `example file is available on Github <https://raw.github.com/ansible/ansible/devel/examples/ansible.cfg>`_.
An `example file is available on Github <https://raw.github.com/ansible/ansible/devel/examples/ansible.cfg>`_.
For more details and a full listing of available configurations go to :ref:`configuration_settings`. Starting with Ansible version 2.4, you can use the :doc:`ansible-config` command line utility to list your available options and inspect the current values.
For more details and a full listing of available configurations go to :ref:`configuration_settings`. Starting with Ansible version 2.4, you can use the :ref:`ansible-config` command line utility to list your available options and inspect the current values.
@ -99,7 +99,7 @@ In addition to the deprecation warnings, many new tests have been introduced tha
when: result is successful
when: result is successful
See :doc:`playbooks_tests` for more information.
See :ref:`playbook_tests` for more information.
Additionally, a script was created to assist in the conversion for tests using filter syntax to proper jinja test syntax. This script has been used to convert all of the Ansible integration tests to the correct format. There are a few limitations documented, and all changes made by this script should be evaluated for correctness before executing the modified playbooks. The script can be found at `https://github.com/ansible/ansible/blob/devel/hacking/fix_test_syntax.py <https://github.com/ansible/ansible/blob/devel/hacking/fix_test_syntax.py>`_.
Additionally, a script was created to assist in the conversion for tests using filter syntax to proper jinja test syntax. This script has been used to convert all of the Ansible integration tests to the correct format. There are a few limitations documented, and all changes made by this script should be evaluated for correctness before executing the modified playbooks. The script can be found at `https://github.com/ansible/ansible/blob/devel/hacking/fix_test_syntax.py <https://github.com/ansible/ansible/blob/devel/hacking/fix_test_syntax.py>`_.
@ -271,4 +271,4 @@ NEW In Ansible 2.5
from ansible.module_utils.network.vyos.vyos import get_config, load_config
from ansible.module_utils.network.vyos.vyos import get_config, load_config
See the module utilities developer guide see :doc:`dev_guide/developing_module_utilities` for more information.
See the module utilities developer guide see :ref:`appendix_module_utilities` for more information.
@ -54,7 +56,7 @@ The following provides an example of using *--roles-path* to install the role in
..seealso::
..seealso::
:doc:`intro_configuration`
:ref:`intro_configuration`
All about configuration files
All about configuration files
version
version
@ -198,7 +200,7 @@ The complex form can also be used as follows:
version: 775396299f2da1f519f0d8885022ca2d6ee80ee8
version: 775396299f2da1f519f0d8885022ca2d6ee80ee8
name: composer
name: composer
When dependencies are encountered by ``ansible-galaxy``, it will automatically install each dependency to the ``roles_path``. To understand how dependencies are handled during play execution, see :doc:`playbooks_reuse_roles`.
When dependencies are encountered by ``ansible-galaxy``, it will automatically install each dependency to the ``roles_path``. To understand how dependencies are handled during play execution, see :ref:`playbooks_reuse_roles`.
..note::
..note::
@ -507,7 +509,7 @@ Provide the ID of the integration to be disabled. You can find the ID by using t
..seealso::
..seealso::
:doc:`playbooks_reuse_roles`
:ref:`playbooks_reuse_roles`
All about ansible roles
All about ansible roles
`Mailing List <http://groups.google.com/group/ansible-project>`_
`Mailing List <http://groups.google.com/group/ansible-project>`_
Questions? Help? Ideas? Stop by the list on Google Groups
Questions? Help? Ideas? Stop by the list on Google Groups
Once your nodes are spun up, you'll probably want to talk to them again. With a cloud setup, it's best to not maintain a static list of cloud hostnames
Once your nodes are spun up, you'll probably want to talk to them again. With a cloud setup, it's best to not maintain a static list of cloud hostnames
in text files. Rather, the best way to handle this is to use the ec2 dynamic inventory script. See :doc:`intro_dynamic_inventory`.
in text files. Rather, the best way to handle this is to use the ec2 dynamic inventory script. See :ref:`dynamic_inventory`.
This will also dynamically select nodes that were even created outside of Ansible, and allow Ansible to manage them.
This will also dynamically select nodes that were even created outside of Ansible, and allow Ansible to manage them.
See :doc:`intro_dynamic_inventory` for how to use this, then flip back over to this chapter.
See :ref:`dynamic_inventory` for how to use this, then return to this chapter.
.._aws_tags_and_groups:
.._aws_tags_and_groups:
@ -190,7 +190,7 @@ Read :ref:`ansible-pull` for more information on pull-mode playbooks.
Autoscaling with Ansible Tower
Autoscaling with Ansible Tower
``````````````````````````````
``````````````````````````````
:doc:`tower` also contains a very nice feature for auto-scaling use cases. In this mode, a simple curl script can call
:ref:`ansible_tower` also contains a very nice feature for auto-scaling use cases. In this mode, a simple curl script can call
a defined URL and the server will "dial out" to the requester and configure an instance that is spinning up. This can be a great way
a defined URL and the server will "dial out" to the requester and configure an instance that is spinning up. This can be a great way
to reconfigure ephemeral nodes. See the Tower install and product documentation for more details.
to reconfigure ephemeral nodes. See the Tower install and product documentation for more details.
@ -241,11 +241,11 @@ documentation for a full list with examples.
..seealso::
..seealso::
:doc:`modules`
:ref:`all_modules`
All the documentation for Ansible modules
All the documentation for Ansible modules
:doc:`playbooks`
:ref:`working_with_playbooks`
An introduction to playbooks
An introduction to playbooks
:doc:`playbooks_delegation`
:ref:`playbooks_delegation`
Delegation, useful for working with loud balancers, clouds, and locally executed steps.
Delegation, useful for working with loud balancers, clouds, and locally executed steps.
`User Mailing List <http://groups.google.com/group/ansible-devel>`_
`User Mailing List <http://groups.google.com/group/ansible-devel>`_
@ -169,7 +169,7 @@ To use the rackspace dynamic inventory script, copy ``rax.py`` into your invento
..note:: Dynamic inventory scripts (like ``rax.py``) are saved in ``/usr/share/ansible/inventory`` if Ansible has been installed globally. If installed to a virtualenv, the inventory scripts are installed to ``$VIRTUALENV/share/inventory``.
..note:: Dynamic inventory scripts (like ``rax.py``) are saved in ``/usr/share/ansible/inventory`` if Ansible has been installed globally. If installed to a virtualenv, the inventory scripts are installed to ``$VIRTUALENV/share/inventory``.
..note:: Users of :doc:`tower` will note that dynamic inventory is natively supported by Tower, and all you have to do is associate a group with your Rackspace Cloud credentials, and it will easily synchronize without going through these steps::
..note:: Users of :ref:`ansible_tower` will note that dynamic inventory is natively supported by Tower, and all you have to do is associate a group with your Rackspace Cloud credentials, and it will easily synchronize without going through these steps::
$ RAX_CREDS_FILE=~/.raxpub ansible all -i rax.py -m setup
$ RAX_CREDS_FILE=~/.raxpub ansible all -i rax.py -m setup
@ -797,7 +797,7 @@ Advanced Usage
Autoscaling with Tower
Autoscaling with Tower
++++++++++++++++++++++
++++++++++++++++++++++
:doc:`tower` also contains a very nice feature for auto-scaling use cases.
:ref:`ansible_tower` also contains a very nice feature for auto-scaling use cases.
In this mode, a simple curl script can call a defined URL and the server will "dial out" to the requester
In this mode, a simple curl script can call a defined URL and the server will "dial out" to the requester
and configure an instance that is spinning up. This can be a great way to reconfigure ephemeral nodes.
and configure an instance that is spinning up. This can be a great way to reconfigure ephemeral nodes.
@ -77,7 +77,7 @@ as push updates to all of the servers::
..note::
..note::
If you're not familiar with terms like playbooks and plays, you should review :doc:`playbooks`.
If you're not familiar with terms like playbooks and plays, you should review :ref:`working_with_playbooks`.
In this playbook we have 5 plays. The first one targets ``all`` hosts and applies the ``common`` role to all of the hosts.
In this playbook we have 5 plays. The first one targets ``all`` hosts and applies the ``common`` role to all of the hosts.
This is for site-wide things like yum repository configuration, firewall configuration, and anything else that needs to apply to all of the servers.
This is for site-wide things like yum repository configuration, firewall configuration, and anything else that needs to apply to all of the servers.
@ -100,7 +100,7 @@ your roles is up to you and your application, but most sites will have one or mo
all systems, and then a series of application-specific roles that install and configure particular parts of the site.
all systems, and then a series of application-specific roles that install and configure particular parts of the site.
Roles can have variables and dependencies, and you can pass in parameters to roles to modify their behavior.
Roles can have variables and dependencies, and you can pass in parameters to roles to modify their behavior.
You can read more about roles in the :doc:`playbooks_reuse_roles` section.
You can read more about roles in the :ref:`playbooks_reuse_roles` section.
.._lamp_group_variables:
.._lamp_group_variables:
@ -185,7 +185,7 @@ This loops over all of the hosts in the group called ``monitoring``, and adds an
each monitoring hosts' default IPv4 address to the current machine's iptables configuration, so that Nagios can monitor those hosts.
each monitoring hosts' default IPv4 address to the current machine's iptables configuration, so that Nagios can monitor those hosts.
You can learn a lot more about Jinja2 and its capabilities `here <http://jinja.pocoo.org/docs/>`_, and you
You can learn a lot more about Jinja2 and its capabilities `here <http://jinja.pocoo.org/docs/>`_, and you
can read more about Ansible variables in general in the :doc:`playbooks_variables` section.
can read more about Ansible variables in general in the :ref:`playbooks_variables` section.
.._lamp_rolling_upgrade:
.._lamp_rolling_upgrade:
@ -269,9 +269,9 @@ Again, if you were using a Netscaler or F5 or Elastic Load Balancer, you would j
Managing Other Load Balancers
Managing Other Load Balancers
`````````````````````````````
`````````````````````````````
In this example, we use the simple HAProxy load balancer to front-end the web servers. It's easy to configure and easy to manage. As we have mentioned, Ansible has built-in support for a variety of other load balancers like Citrix NetScaler, F5 BigIP, Amazon Elastic Load Balancers, and more. See the :doc:`modules` documentation for more information.
In this example, we use the simple HAProxy load balancer to front-end the web servers. It's easy to configure and easy to manage. As we have mentioned, Ansible has built-in support for a variety of other load balancers like Citrix NetScaler, F5 BigIP, Amazon Elastic Load Balancers, and more. See the :ref:`working_with_modules` documentation for more information.
For other load balancers, you may need to send shell commands to them (like we do for HAProxy above), or call an API, if your load balancer exposes one. For the load balancers for which Ansible has modules, you may want to run them as a ``local_action`` if they contact an API. You can read more about local actions in the :doc:`playbooks_delegation` section. Should you develop anything interesting for some hardware where there is not a core module, it might make for a good module for core inclusion!
For other load balancers, you may need to send shell commands to them (like we do for HAProxy above), or call an API, if your load balancer exposes one. For the load balancers for which Ansible has modules, you may want to run them as a ``local_action`` if they contact an API. You can read more about local actions in the :ref:`playbooks_delegation` section. Should you develop anything interesting for some hardware where there is not a core module, it might make for a good module for core inclusion!
.._lamp_end_to_end:
.._lamp_end_to_end:
@ -282,7 +282,7 @@ Now that you have an automated way to deploy updates to your application, how do
Depending on your environment, you might be deploying continuously to a test environment, running an integration test battery against that environment, and then deploying automatically into production. Or you could keep it simple and just use the rolling-update for on-demand deployment into test or production specifically. This is all up to you.
Depending on your environment, you might be deploying continuously to a test environment, running an integration test battery against that environment, and then deploying automatically into production. Or you could keep it simple and just use the rolling-update for on-demand deployment into test or production specifically. This is all up to you.
For integration with Continuous Integration systems, you can easily trigger playbook runs using the ``ansible-playbook`` command line tool, or, if you're using :doc:`tower`, the ``tower-cli`` or the built-in REST API. (The tower-cli command 'joblaunch' will spawn a remote job over the REST API and is pretty slick).
For integration with Continuous Integration systems, you can easily trigger playbook runs using the ``ansible-playbook`` command line tool, or, if you're using :ref:`ansible_tower`, the ``tower-cli`` or the built-in REST API. (The tower-cli command 'joblaunch' will spawn a remote job over the REST API and is pretty slick).
This should give you a good idea of how to structure a multi-tier application with Ansible, and orchestrate operations upon that app, with the eventual goal of continuous delivery to your customers. You could extend the idea of the rolling upgrade to lots of different parts of the app; maybe add front-end web servers along with application servers, for instance, or replace the SQL database with something like MongoDB or Riak. Ansible gives you the capability to easily manage complicated environments and automate common operations.
This should give you a good idea of how to structure a multi-tier application with Ansible, and orchestrate operations upon that app, with the eventual goal of continuous delivery to your customers. You could extend the idea of the rolling upgrade to lots of different parts of the app; maybe add front-end web servers along with application servers, for instance, or replace the SQL database with something like MongoDB or Riak. Ansible gives you the capability to easily manage complicated environments and automate common operations.
@ -290,11 +290,11 @@ This should give you a good idea of how to structure a multi-tier application wi
`lamp_haproxy example <https://github.com/ansible/ansible-examples/tree/master/lamp_haproxy>`_
`lamp_haproxy example <https://github.com/ansible/ansible-examples/tree/master/lamp_haproxy>`_
Often a user of a configuration management system will want to keep inventory
Often a user of a configuration management system will want to keep inventory
in a different software system. Ansible provides a basic text-based system as described in
in a different software system. Ansible provides a basic text-based system as described in
:doc:`intro_inventory` but what if you want to use something else?
:ref:`inventory` but what if you want to use something else?
Frequent examples include pulling inventory from a cloud provider, LDAP, `Cobbler <http://cobbler.github.com>`_,
Frequent examples include pulling inventory from a cloud provider, LDAP, `Cobbler <http://cobbler.github.com>`_,
or a piece of expensive enterprisey CMDB software.
or a piece of expensive enterprisey CMDB software.
Ansible easily supports all of these options via an external inventory system. The contrib/inventory directory contains some of these already -- including options for EC2/Eucalyptus, Rackspace Cloud, and OpenStack, examples of some of which will be detailed below.
Ansible easily supports all of these options via an external inventory system. The contrib/inventory directory contains some of these already -- including options for EC2/Eucalyptus, Rackspace Cloud, and OpenStack, examples of some of which will be detailed below.
:doc:`tower` also provides a database to store inventory results that is both web and REST Accessible. Tower syncs with all Ansible dynamic inventory sources you might be using, and also includes a graphical inventory editor. By having a database record of all of your hosts, it's easy to correlate past event history and see which ones have had failures on their last playbook runs.
:ref:`ansible_tower` also provides a database to store inventory results that is both web and REST Accessible. Tower syncs with all Ansible dynamic inventory sources you might be using, and also includes a graphical inventory editor. By having a database record of all of your hosts, it's easy to correlate past event history and see which ones have had failures on their last playbook runs.
For information about writing your own dynamic inventory source, see :doc:`dev_guide/developing_inventory`.
For information about writing your own dynamic inventory source, see :ref:`developing_inventory`.
Now that you've read :doc:`../installation_guide/intro_installation` and installed Ansible, it's time to get
Now that you've read :ref:`intro_installation` and installed Ansible, it's time to get
started with some ad-hoc commands.
started with some ad-hoc commands.
What we are showing first are not the powerful configuration/deployment/orchestration features of Ansible.
What we are showing first are not the powerful configuration/deployment/orchestration features of Ansible.
@ -28,7 +30,7 @@ By default, Ansible will try to use native
OpenSSH for remote communication when possible. This enables ControlPersist (a performance feature), Kerberos, and options in ``~/.ssh/config`` such as Jump Host setup. However, when using Enterprise Linux 6 operating systems as the control machine (Red Hat Enterprise Linux and derivatives such as CentOS), the version of OpenSSH may be too old to support ControlPersist. On these operating systems, Ansible will fallback into using a high-quality Python implementation of
OpenSSH for remote communication when possible. This enables ControlPersist (a performance feature), Kerberos, and options in ``~/.ssh/config`` such as Jump Host setup. However, when using Enterprise Linux 6 operating systems as the control machine (Red Hat Enterprise Linux and derivatives such as CentOS), the version of OpenSSH may be too old to support ControlPersist. On these operating systems, Ansible will fallback into using a high-quality Python implementation of
OpenSSH called 'paramiko'. If you wish to use features like Kerberized SSH and more, consider using Fedora, OS X, or Ubuntu as your control machine until a newer version of OpenSSH is available for your platform.
OpenSSH called 'paramiko'. If you wish to use features like Kerberized SSH and more, consider using Fedora, OS X, or Ubuntu as your control machine until a newer version of OpenSSH is available for your platform.
Occasionally you'll encounter a device that doesn't support SFTP. This is rare, but should it occur, you can switch to SCP mode in :doc:`intro_configuration`.
Occasionally you'll encounter a device that doesn't support SFTP. This is rare, but should it occur, you can switch to SCP mode in :ref:`intro_configuration`.
When speaking with remote machines, Ansible by default assumes you are using SSH keys. SSH keys are encouraged but password authentication can also be used where needed by supplying the option ``--ask-pass``. If using sudo features and when sudo requires a password, also supply ``--ask-become-pass`` (previously ``--ask-sudo-pass`` which has been deprecated).
When speaking with remote machines, Ansible by default assumes you are using SSH keys. SSH keys are encouraged but password authentication can also be used where needed by supplying the option ``--ask-pass``. If using sudo features and when sudo requires a password, also supply ``--ask-become-pass`` (previously ``--ask-sudo-pass`` which has been deprecated).
@ -145,15 +147,15 @@ Also note that host key checking in paramiko mode is reasonably slow, therefore
Ansible will log some information about module arguments on the remote system in the remote syslog, unless a task or play is marked with a "no_log: True" attribute. This is explained later.
Ansible will log some information about module arguments on the remote system in the remote syslog, unless a task or play is marked with a "no_log: True" attribute. This is explained later.
To enable basic logging on the control machine see :doc:`intro_configuration` document and set the 'log_path' configuration file setting. Enterprise users may also be interested in :doc:`tower`. Tower provides a very robust database logging feature where it is possible to drill down and see history based on hosts, projects, and particular inventories over time -- explorable both graphically and through a REST API.
To enable basic logging on the control machine see :ref:`intro_configuration` document and set the 'log_path' configuration file setting. Enterprise users may also be interested in :ref:`ansible_tower`. Tower provides a very robust database logging feature where it is possible to drill down and see history based on hosts, projects, and particular inventories over time -- explorable both graphically and through a REST API.
..seealso::
..seealso::
:doc:`intro_inventory`
:ref:`intro_inventory`
More information about inventory
More information about inventory
:doc:`intro_adhoc`
:ref:`intro_adhoc`
Examples of basic commands
Examples of basic commands
:doc:`playbooks`
:ref:`working_with_playbooks`
Learning Ansible's configuration management language
Learning Ansible's configuration management language
`Mailing List <http://groups.google.com/group/ansible-project>`_
`Mailing List <http://groups.google.com/group/ansible-project>`_
Questions? Help? Ideas? Stop by the list on Google Groups
Questions? Help? Ideas? Stop by the list on Google Groups
You can also select the connection type and user on a per host basis:
You can also select the connection type and user on a per host basis:
..code-block::ini
..code-block:: guess
[targets]
[targets]
@ -132,7 +131,7 @@ Host Variables
As described above, it is easy to assign variables to hosts that will be used later in playbooks:
As described above, it is easy to assign variables to hosts that will be used later in playbooks:
..code-block::ini
..code-block::guess
[atlanta]
[atlanta]
host1 http_port=80 maxRequestsPerChild=808
host1 http_port=80 maxRequestsPerChild=808
@ -147,7 +146,7 @@ Variables can also be applied to an entire group at once:
The INI way:
The INI way:
..code-block::ini
..code-block::guess
[atlanta]
[atlanta]
host1
host1
@ -180,7 +179,7 @@ It is also possible to make groups of groups using the ``:children`` suffix in I
You can apply variables using ``:vars`` or ``vars:``:
You can apply variables using ``:vars`` or ``vars:``:
..code-block::ini
..code-block::guess
[atlanta]
[atlanta]
host1
host1
@ -259,7 +258,7 @@ The preferred practice in Ansible is to not store variables in the main inventor
In addition to storing variables directly in the inventory file, host and group variables can be stored in individual files relative to the inventory file (not directory, it is always the file).
In addition to storing variables directly in the inventory file, host and group variables can be stored in individual files relative to the inventory file (not directory, it is always the file).
These variable files are in YAML format. Valid file extensions include '.yml', '.yaml', '.json', or no file extension.
These variable files are in YAML format. Valid file extensions include '.yml', '.yaml', '.json', or no file extension.
See :doc:`YAMLSyntax` if you are new to YAML.
See :ref:`yaml_syntax` if you are new to YAML.
Assuming the inventory file path is::
Assuming the inventory file path is::
@ -340,9 +339,6 @@ Host connection:
ansible_connection
ansible_connection
Connection type to the host. This can be the name of any of ansible's connection plugins. SSH protocol types are ``smart``, ``ssh`` or ``paramiko``. The default is smart. Non-SSH based types are described in the next section.
Connection type to the host. This can be the name of any of ansible's connection plugins. SSH protocol types are ``smart``, ``ssh`` or ``paramiko``. The default is smart. Non-SSH based types are described in the next section.
:doc:`Jinja2 lookups playbooks_lookups`, :doc:`filters playbooks_filters` and :doc:`tests playbooks_tests`
make for some powerful data generation and manipulation.
..note::``with_`` loops are actually a combination of things ``with_`` + ``lookup()``, even ``items`` is a lookup. ``loop`` can be used in the same way as shown above.
..note::``with_`` loops are actually a combination of things ``with_`` + ``lookup()``, even ``items`` is a lookup. ``loop`` can be used in the same way as shown above.
@ -298,7 +300,7 @@ Embedding Modules and Plugins In Roles
This is an advanced topic that should not be relevant for most users.
This is an advanced topic that should not be relevant for most users.
If you write a custom module (see :doc:`dev_guide/developing_modules`) or a plugin (see :doc:`dev_guide/developing_plugins`), you may wish to distribute it as part of a role.
If you write a custom module (see :ref:`developing_modules`) or a plugin (see :ref:`developing_plugins`), you may wish to distribute it as part of a role.
Generally speaking, Ansible as a project is very interested in taking high-quality modules into ansible core for inclusion, so this shouldn't be the norm, but it's quite easy to do.
Generally speaking, Ansible as a project is very interested in taking high-quality modules into ansible core for inclusion, so this shouldn't be the norm, but it's quite easy to do.
A good example for this is if you worked at a company called AcmeWidgets, and wrote an internal module that helped configure your internal software, and you wanted other
A good example for this is if you worked at a company called AcmeWidgets, and wrote an internal module that helped configure your internal software, and you wanted other
@ -345,7 +347,7 @@ Ansible will search for roles in the following way:
- A ``roles/`` directory, relative to the playbook file.
- A ``roles/`` directory, relative to the playbook file.
- By default, in ``/etc/ansible/roles``
- By default, in ``/etc/ansible/roles``
In Ansible 1.4 and later you can configure an additional roles_path to search for roles. Use this to check all of your common roles out to one location, and share them easily between multiple playbook projects. See :doc:`intro_configuration` for details about how to set this up in ansible.cfg.
In Ansible 1.4 and later you can configure an additional roles_path to search for roles. Use this to check all of your common roles out to one location, and share them easily between multiple playbook projects. See :ref:`intro_configuration` for details about how to set this up in ansible.cfg.
Ansible Galaxy
Ansible Galaxy
``````````````
``````````````
@ -358,23 +360,23 @@ Read the "About" page on the Galaxy site for more information.
..seealso::
..seealso::
:doc:`galaxy`
:ref:`ansible_galaxy`
How to share roles on galaxy, role management
How to share roles on galaxy, role management
:doc:`YAMLSyntax`
:ref:`yaml_syntax`
Learn about YAML syntax
Learn about YAML syntax
:doc:`playbooks`
:ref:`working_with_playbooks`
Review the basic Playbook language features
Review the basic Playbook language features
:doc:`playbooks_best_practices`
:ref:`playbooks_best_practices`
Various tips about managing playbooks in the real world
Various tips about managing playbooks in the real world
:doc:`playbooks_variables`
:ref:`playbooks_variables`
All about variables in playbooks
All about variables in playbooks
:doc:`playbooks_conditionals`
:ref:`playbooks_conditionals`
Conditionals in playbooks
Conditionals in playbooks
:doc:`playbooks_loops`
:ref:`playbooks_loops`
Loops in playbooks
Loops in playbooks
:doc:`modules`
:ref:`all_modules`
Learn about available modules
Learn about available modules
:doc:`dev_guide/developing_modules`
:ref:`developing_modules`
Learn how to extend Ansible by writing your own modules
Learn how to extend Ansible by writing your own modules
Ansible 2.0 has deprecated the "ssh" from ``ansible_ssh_user``, ``ansible_ssh_host``, and ``ansible_ssh_port`` to become ``ansible_user``, ``ansible_host``, and ``ansible_port``. If you are using a version of Ansible prior to 2.0, you should continue using the older style variables (``ansible_ssh_*``). These shorter variables are ignored, without warning, in older versions of Ansible.
scottb
7 years ago
committed by