@ -13,8 +13,8 @@ The mechanism for doing this is the "ansible.cfg" file, which is looked for in t
* ~/.ansible.cfg
* ansible.cfg (in the playbook directory)
If multiple file locations matching the above exist, the last location on the list is used. Settings are not merged.
The last file in the list is found and the others will be ignored.
If multiple file locations matching the above exist, the last location on the above list is used. Settings in files
are not merged together.
..contents::
:depth:2
@ -39,15 +39,16 @@ Environmental configuration
```````````````````````````
Ansible also allows configuration of settings via environment variables. If these environment variables are set, they will
override any setting loaded from the configuration file. These variables are for brevity not defined here, but look in 'constants.py'
in the source tree if you want to use these. They are mostly considered to be a legacy system as compared to the config file, but
are equally valid.
override any setting loaded from the configuration file. These variables are for brevity not defined here, but look in 'constants.py' in the source tree if you want to use these. They are mostly considered to be a legacy system as compared to the config file, but are equally valid.
.._config_values_by_section:
Explanation of values by section
````````````````````````````````
The configuration file is broken up into sections. Most options are in the "general" section but some sections of the file
Often a user of a configuration management system will want to keep inventory
in a different software system. Ansible provides a basic 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?
Frequent examples include pulling inventory from a cloud provider, LDAP, `Cobbler <http://cobbler.github.com>`_,
or a piece of expensive enterprisey CMDB software.
Ansible easily supports all of these options via an external inventory system. The plugins directory contains some of these already -- including options for EC2/Eucalyptus and OpenStack, which will be detailed below.
Ansible easily supports all of these options via an external inventory system. The plugins directory contains some of these already -- including options for EC2/Eucalyptus, Rackspace Cloud, and OpenStack, examples of some of which will be detailed below.
For information about writing your own, see :doc:`developing_inventory`.
`AnsibleWorks AWX <http://ansibleworks.com/ansibleworks-awx/>`_ also provides a database to store inventory results that is both web and REST Accessible. AWX syncs with all Ansible dynamic inventory sources. By having a database record of all of your hosts, it's easy to corrolate 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:`developing_inventory`.
..contents::
:depth:2
@ -23,7 +25,7 @@ For information about writing your own, see :doc:`developing_inventory`.
Example: The Cobbler External Inventory Script
``````````````````````````````````````````````
It is expected that many Ansible users with physical hardware may also be `Cobbler <http://cobbler.github.com>`_ users. (note: Cobbler was originally written by Michael DeHaan and is now lead by James Cammarata, who also works for AnsibleWorks).
It is expected that many Ansible users with a reasonable amount of physical hardware may also be `Cobbler <http://cobbler.github.com>`_ users. (note: Cobbler was originally written by Michael DeHaan and is now lead by James Cammarata, who also works for AnsibleWorks).
While primarily used to kickoff OS installations and manage DHCP and DNS, Cobbler has a generic
layer that allows it to represent data for multiple configuration management systems (even at the same time), and has
What we are showing first are not the powerful configuration/deployment/orchestration of Ansible, called playbooks.
Playbooks are covered in a seperate section.
This is basically about how to get going initially. Once you have this down, read :doc:`intro_adhoc` for some more
detail, and then you'll be ready to dive into playbooks.
This section is about how to get going initially. Once you have these concepts down, read :doc:`intro_adhoc` for some more
detail, and then you'll be ready to dive into playbooks and explore the most interesting parts!
.._remote_connection_information:
@ -27,19 +27,17 @@ Before we get started, it's important to understand how Ansible is communicating
machines over SSH.
By default, ansible 1.3 and later will try to use native
OpenSSH for remote communication when possible. This enables both ControlPersist (a performance feature), Kerbos, and options in ~/.ssh/config such as Jump Host setup. When using Enterprise Linux 6 operating systems as the control machine (Red Hat Enterprise Linux and derivatives such as CentOS), however, the version of OpenSSH may be too old to support Control Persist. 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 for remote communication when possible. This enables both ControlPersist (a performance feature), Kerberos, and options in ~/.ssh/config such as Jump Host setup. When using Enterprise Linux 6 operating systems as the control machine (Red Hat Enterprise Linux and derivatives such as CentOS), however, the version of OpenSSH may be too old to support Control Persist. 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 -- or engage 'accelerated mode' in Ansible. See :doc:`playbooks_acceleration`.
In Ansible 1.2 and before, the default was strictly paramiko and native SSH had to be explicitly selected with -c ssh or set in the configuration file.
If talking with some remote devices that don't support SFTP, you can switch to SCP mode in :doc:`intro_configuration`.
Occasionally you'll encounter a device that doesn't do SFTP. This is rare, but if talking with some remote devices that don't support SFTP, you can switch to SCP mode in :doc:`intro_configuration`.
When speaking with remote machines, Ansible will by default assume you are using SSH keys. To enable password auth, supply the option --ask-pass where needed. If using sudo features and when sudo requires a password, also supply --ask-sudo-pass as appropriate.
When speaking with remote machines, Ansible will by default assume you are using SSH keys -- which we encourage -- but passwords are fine too. To enable password auth, supply the option --ask-pass where needed. If using sudo features and when sudo requires a password, also supply --ask-sudo-pass as appropriate.
Ansible also contains a feature called :doc:`playbooks_acceleration` which uses SSH for initial key exchange
and then communicates over a high speed encrypted connection.
While it may be common sense, it is worth sharing: Any management system benefits from being run near your machines you are being managed. If running in a cloud, onsider running Ansible from a machine inside that cloud.
While it may be common sense, it is worth sharing: Any management system benefits from being run near your machines you are being managed. If running in a cloud, consider running Ansible from a machine inside that cloud. It will work better than on the open
intranet in most cases.
As an advanced topic, ansible doesn't just have to connect remotely over SSH. The transports are pluggable, and there are options for managing things locally, as well as managing chroot, lxc, and jail containers. A mode called 'ansible-pull' can also invert the system and have systems 'phone home' via scheduled git checkouts to pull configuration directives from a central repository.
@ -48,7 +46,7 @@ As an advanced topic, ansible doesn't just have to connect remotely over SSH. T
Your first commands
```````````````````
Now that you've installed Ansible, it's time to get started with some basic tests.
Now that you've installed Ansible, it's time to get started with some basics/
Edit (or create) /etc/ansible/hosts and put one or more remote systems in it, for
which you have your SSH key in ``authorized_keys``::
@ -59,7 +57,8 @@ which you have your SSH key in ``authorized_keys``::
This is an inventory file, which is also explained in greater depth here: :doc:`intro_inventory`.
We'll assume you are using SSH keys for authentication. Set up SSH agent to avoid retyping passwords:
We'll assume you are using SSH keys for authentication. To set up SSH agent to avoid retyping passwords, you can
do::
..code-block:: bash
@ -89,7 +88,7 @@ If you would like to access sudo mode, there are also flags to do that:
$ ansible all -m ping -u bruce --sudo --sudo-user batman
(The sudo implementation is changeable in ansible's configuration file if you happen to want to use a sudo
replacement. Flags passed dot sudo can also be set.)
replacement. Flags passed to sudo (like -H) can also be set there.)
Now run a live command on all of your nodes:
@ -111,7 +110,7 @@ A note about Host Key Checking
Ansible 1.2.1 and later have host key checking enabled by default.
If a host is reinstalled and has a different key in 'known_hosts', this will result in a error message until corrected. If a host is not initially in 'known_hosts' this will result in prompting for confirmation of the key, which results in a interactive experience if using Ansible, from say, cron.
If a host is reinstalled and has a different key in 'known_hosts', this will result in a error message until corrected. If a host is not initially in 'known_hosts' this will result in prompting for confirmation of the key, which results in a interactive experience if using Ansible, from say, cron. You might not want this.
If you wish to disable this behavior and understand the implications, you can do so by editing /etc/ansible/ansible.cfg or ~/.ansible.cfg::
@ -339,7 +339,7 @@ Assuming you load balance your checkout location, ansible-pull scales essentiall
Run 'ansible-pull --help' for details.
There's also a `<clever playbook> https://github.com/ansible/ansible-examples/blob/master/language_features/ansible_pull.yml>`_ available to using ansible in push mode to configure ansible-pull via a crontab!
There's also a `clever playbook <https://github.com/ansible/ansible-examples/blob/master/language_features/ansible_pull.yml>`_ available to using ansible in push mode to configure ansible-pull via a crontab!
While OpenSSH using the ControlPersist feature is quite fast and scalable, there is a certain amount of overhead involved in
using SSH connections. If you are running on a platform that doesn't have ControlPersist support (such as an EL6 control
machine), you'll probably be even more interested in options.
While OpenSSH using the ControlPersist feature is quite fast and scalable, there is a certain small amount of overhead involved in
using SSH connections. While many people will not encounter a need, if you are running on a platform that doesn't have ControlPersist support (such as an EL6 control machine), you'll probably be even more interested in tuning options.
Accelerate mode is there to help connections work faster, but still uses SSH for initial secure key exchange. There is no
additional public key infrastructure to manage, and this does not require things like NTP or even DNS.
additional public key infrastructure to manage, and this does not require things like NTP or even DNS.
Accelerated mode can be anywhere from
2-6x faster than SSH with ControlPersist enabled, and 10x faster than paramiko.
Accelerated mode can be anywhere from 2-6x faster than SSH with ControlPersist enabled, and 10x faster than paramiko.
Accelerated mode works by launching a temporary daemon over SSH. Once the daemon is running, Ansible will connect directly
to it via a socket connection. Ansible secures this communication by using a temporary AES key that is uploaded during
the SSH connection (this key is different for every host, and is also regenerated every time the daemon is started). By default,
Ansible will use port 5099 for the accelerated connection, though this is configurable. Once running, the daemon will accept
connections for 30 minutes, after which time it will terminate itself and need to be restarted over SSH.
to it via a socket connection. Ansible secures this communication by using a temporary AES key that is exchanged during
the SSH connection (this key is different for every host, and is also regenerated periodically).
Accelerated mode offers several improvments over the original fireball mode:
By default, Ansible will use port 5099 for the accelerated connection, though this is configurable. Once running, the daemon will accept connections for 30 minutes, after which time it will terminate itself and need to be restarted over SSH.
Accelerated mode offers several improvments over the original fireball mode from which it was based:
* No bootstrapping is required, only a single line needs to be added to each play you wish to run in accelerated mode.
* Support for sudo commands (see below for more details and caveats).
* Fewer requirements. ZeroMQ is no longer required, nor are there any special packages beyond python-keyczar.
* Support for sudo commands (see below for more details and caveats) is available.
* There are fewer requirements. ZeroMQ is no longer required, nor are there any special packages beyond python-keyczar.
In order to use accelerated mode, simply add `accelerate: true` to your play::
@ -57,7 +55,7 @@ The `accelerate_port` option can also be specified in the environment variable A
As noted above, accelerated mode also supports running tasks via sudo, however there are two important caveats:
* You must remove requiretty from your sudoers options.
* Prompting for the sudo password is not yet supported, so the NOPASSWD option is required for commands.
* Prompting for the sudo password is not yet supported, so the NOPASSWD option is required for sudo'ed commands.
Here are some tips for making the most of Ansible.
Here are some tips for making the most of Ansible playbooks.
You can find some example playbooks illustrating these best practices in our `ansible-examples repository <https://github.com/ansible/ansible-examples>`_. (NOTE: These may not use all of the features in the latest release just yet).
You can find some example playbooks illustrating these best practices in our `ansible-examples repository <https://github.com/ansible/ansible-examples>`_. (NOTE: These may not use all of the features in the latest release, but are still an excellent reference!).
..contents::
:depth:2
@ -13,11 +13,10 @@ You can find some example playbooks illustrating these best practices in our `an
Content Organization
++++++++++++++++++++++
The following section shows one of many possible ways to organize content. Your usage of Ansible should fit your needs,
so feel free to modify this approach and organize as you see fit.
The following section shows one of many possible ways to organize playbook content. Your usage of Ansible should fit your needs, however, not ours, so feel free to modify this approach and organize as you see fit.
(One thing you will definitely want to do though, is use the "roles" organization feature, which is documented as part
of the main playbooks page)
of the main playbooks page. See :doc:`playbooks_roles`).
.._directory_layout:
@ -63,8 +62,9 @@ The top level of the directory would contain files and directories like so::
How to Arrange Inventory, Stage vs Production
`````````````````````````````````````````````
In this example, the *production* file contains the inventory of all of your production hosts. Of course you can pull inventory from an external
data source as well, but this is just a basic example. Define groups based on purpose of the host (roles) and also geography or datacenter location::
In the example below, the *production* file contains the inventory of all of your production hosts. Of course you can pull inventory from an external data source as well, but this is just a basic example.
It is suggested that you define groups based on purpose of the host (roles) and also geography or datacenter location (if applicable)::
# file: production
@ -103,21 +103,20 @@ data source as well, but this is just a basic example. Define groups based on p
boston-webservers
boston-dbservers
.._groups_and_hosts:
Group And Host Variables
````````````````````````
Now, groups are nice for organization, but that's not all groups are good for. You can also assign variables to them! For instance, atlanta
has its own NTP servers, so when setting up ntp.conf, we should use them. Let's set those now::
Now, groups are nice for organization, but that's not all groups are good for. You can also assign variables to them! For instance, atlanta has its own NTP servers, so when setting up ntp.conf, we should use them. Let's set those now::
---
# file: group_vars/atlanta
ntp: ntp-atlanta.example.com
backup: backup-atlanta.example.com
Variables aren't just for geographic information either! Maybe the webservers have some configuration that doesn't make sense for the database
servers::
Variables aren't just for geographic information either! Maybe the webservers have some configuration that doesn't make sense for the database servers::
---
# file: group_vars/webservers
@ -138,18 +137,6 @@ We can define specific hardware variance in systems in a host_vars file, but avo
foo_agent_port: 86
bar_agent_port: 99
.._role_vars:
Role Variables
``````````````
Variables that are associated with a given role can be defined in a main.yml file within the "vars" directory for that role. These variables are accessible not only to the role itself, but to all other roles and tasks that are part of the same playbook.::
When ansible-playbook is executed with --check it will not make any changes on remote systems. Instead, any module
instrumented to support 'check mode' (which contains the primary core modules, but it is not required that all modules do
this) will report what changes they would have made. Other modules that do not support check mode will also take no
action, but just will not report what changes they might have made.
instrumented to support 'check mode' (which contains most of the primary core modules, but it is not required that all modules do
this) will report what changes they would have made rather than making them. Other modules that do not support check mode will also take no action, but just will not report what changes they might have made.
Check mode is just a simulation, and if you have steps that use conditionals that depend on the results of prior commands,
it may be less useful for you. However it is great for one-node-at-time basic configuration management use cases.
Michael DeHaan
11 years ago