Let's build a very-basic module to get and set the system time. For starters, let's build
a module that just outputs the current time.
We are going to use Python here but any language is possible. Only File I/O and outputing to standard
We are going to use Python here but any language is possible. Only File I/O and outputting to standard
out are required. So, bash, C++, clojure, Python, Ruby, whatever you want
is fine.
@ -224,7 +224,7 @@ only shorter in terms of code, they are actually FASTER in terms of execution ti
Rather than mention these here, the best way to learn is to read some of the `source of the modules <https://github.com/ansible/ansible/tree/devel/library>`_ that come with Ansible.
The 'group' and 'user' modules are reasonably non-trival and showcase what this looks like.
The 'group' and 'user' modules are reasonably non-trivial and showcase what this looks like.
Key parts include always ending the module file with::
@ -341,7 +341,7 @@ and guidelines:
* Return codes from modules are not actually not signficant, but continue on with 0=success and non-zero=failure for reasons of future proofing.
* As results from many hosts will be aggregrated at once, modules should return only relevant output. Returning the entire contents of a log file is generally bad form.
* As results from many hosts will be aggregated at once, modules should return only relevant output. Returning the entire contents of a log file is generally bad form.
Ansible is pluggable in a lot of other ways seperate from inventory scripts and callbacks. Many of these features are there to cover fringe use cases and are infrequently needed, and others are pluggable simply because they are there to implement core features
in ansible and were most convient to be made pluggable.
Ansible is pluggable in a lot of other ways separate from inventory scripts and callbacks. Many of these features are there to cover fringe use cases and are infrequently needed, and others are pluggable simply because they are there to implement core features
in ansible and were most convenient to be made pluggable.
This section will explore these features, though they are generally not common in terms of things people would look to extend quite
@ -46,7 +46,7 @@ Ansible modules are resources that are distributed to remote nodes to make them
state. Ansible follows a "batteries included" philosophy, so you have a lot of great modules for all manner of
IT tasks in the core distribution. This means modules are well up-to-date and you don't have to hunt for an implementation
that will work on your platform. You may think of the module library as a toolbox full of useful system management tools,
and playbooks as the instructions for buildilng something using those tools.
and playbooks as the instructions for building something using those tools.
..toctree::
:maxdepth:1
@ -121,7 +121,7 @@ AnsibleWorks AWX
`AnsibleWorks <http://ansibleworks.com>`_, who also sponsors the Ansible community, also produces 'AWX', which is a web-based solution that makes Ansible even more easy to use for IT teams of all kinds. It's designed to be the hub for all of your automation tasks.
AWX allows you to control access to who can access what, even allowing sharing of SSH credentials without someone being able to transfer those credentials. Inventory can be graphically managed or synced with a widde variety of cloud sources. It logs all of your jobs, integrates well with LDAP, and has an amazing browseable REST API. Command line tools are available for easy integration
AWX allows you to control access to who can access what, even allowing sharing of SSH credentials without someone being able to transfer those credentials. Inventory can be graphically managed or synced with a wide variety of cloud sources. It logs all of your jobs, integrates well with LDAP, and has an amazing browsable REST API. Command line tools are available for easy integration
with Jenkins as well.
Find out more about AWX features and how to download it on the `AWX webpage <http://ansibleworks.com/ansibleworks-awx>`_. AWX
@ -157,7 +157,7 @@ IT automation solutions that work well for them. Should you wish to get more i
Developer Information
`````````````````````
Learn how to build modules of your own in any language, and also how to extend ansible through several kinds of plugins. Explore Ansible's Python API and write Python plugins to integrate with other solutions in your environment.
Learn how to build modules of your own in any language, and also how to extend Ansible through several kinds of plugins. Explore Ansible's Python API and write Python plugins to integrate with other solutions in your environment.
Ansible prefers to use Jinja2 syntax '{{ like_this }}' to indicate a variable should be substituted in a particular string. However,
older versions of playbooks used a more Perl-style syntax. This syntax was undesirable as it frequently conflicted with bash and
was hard to explain to new users when deferencing complicated variable hierarchies, so we have standardized on the '{{ jinja2 }}' way.
was hard to explain to new users when referencing complicated variable hierarchies, so we have standardized on the '{{ jinja2 }}' way.
To ensure a string like '$foo' is not inadvertedly replaced in a Perl or Bash script template, the old form of templating (which is
To ensure a string like '$foo' is not indadvertedly replaced in a Perl or Bash script template, the old form of templating (which is
still enabled as of Ansible 1.4) can be disabled like so ::
legacy_playbook_variables = no
@ -261,7 +261,7 @@ This is the default location Ansible looks to find modules::
library = /usr/share/ansible
Ansible knows how to look in multiple locations if you feed it a colon seperated path, and it also will look for modules in the
Ansible knows how to look in multiple locations if you feed it a colon separated path, and it also will look for modules in the
"./library" directory alongside a playbook.
.._log_path:
@ -358,7 +358,7 @@ value here to avoid re-specifying --ansible-private-keyfile with every invocatio
remote_port
===========
This sets the default SSH port on all of your systems, for systems that didn't specify an alternative value in inventroy.
This sets the default SSH port on all of your systems, for systems that didn't specify an alternative value in inventory.
The default is the standard 22::
remote_port = 22
@ -563,6 +563,6 @@ This setting controls the timeout for the socket connect call, and should be kep
accelerate_connect_timeout = 1.0
Note, this value can be set to less than one second, however it is probably not a good idea to do so unless you're on a very fast and reliable LAN. If you're connecting to systems over the internet, it may be neccessary to increase this timeout.
Note, this value can be set to less than one second, however it is probably not a good idea to do so unless you're on a very fast and reliable LAN. If you're connecting to systems over the internet, it may be necessary to increase this timeout.
@ -12,7 +12,7 @@ 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, Rackspace Cloud, and OpenStack, examples of some of which will be detailed below.
`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.
`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 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:`developing_inventory`.
@ -220,7 +220,7 @@ Using Multiple Inventory Sources
````````````````````````````````
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 thes same time. When doing so, it is possible to mix both dynamic and staticly managed inventory sources in the same ansible run. Instant
at thes same time. When doing so, it is possible to mix both dynamic and statically managed inventory sources in the same ansible run. Instant
@ -32,7 +32,7 @@ machines, many users will actually track the development version.
Ansible's release cycles are usually about two months long. Due to this
short release cycle, minor bugs will generally be fixed in the next release versus maintaining
backports on the stable branch. Major bugs will still have maintaince releases when needed, though
backports on the stable branch. Major bugs will still have maintenance releases when needed, though
these are infrequent.
If you are wishing to run the latest released version of Ansible and you are running Red Hat Enterprise Linux (TM), CentOS, Fedora, Debian, or Ubuntu, we recommend using the OS package manager.
@ -40,7 +40,7 @@ If you are wishing to run the latest released version of Ansible and you are run
For other installation options, we recommend installing via "pip", which is the Python package manager, though other options are also available.
If you wish to track the development release to use and test the latest features, we will share
information about running from source. It's not neccessary to install the program to run from source.
information about running from source. It's not necessary to install the program to run from source.
@ -20,7 +20,7 @@ the SSH connection (this key is different for every host, and is also regenerate
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:
Accelerated mode offers several improvements 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) is available.
While it is possible to write a playbook in one very large file (and you might start out learning playbooks this way),
eventually you'll want to reuse files and start to organize things.
At a basic level, including task files allows you to break up bits of configuration policy into smaller files. Taks includes
At a basic level, including task files allows you to break up bits of configuration policy into smaller files. Task includes
pull in tasks from other files. Since handlers are tasks too, you can also include handler files from the 'handlers:' section.
See :doc:`playbooks` if you need a review of these concepts.
@ -18,7 +18,7 @@ See :doc:`playbooks` if you need a review of these concepts.
Playbooks can also include plays from other playbook files. When that is done, the plays will be inserted into the playbook to form
a longer list of plays.
When you start to think about it -- tasks, handlers, variables, and so -- begin to form larger concepts. You start to think about modelling
When you start to think about it -- tasks, handlers, variables, and so -- begin to form larger concepts. You start to think about modeling
what something is, rather than how to make something look like something. It's no longer "apply this handful of THINGS" to these hosts, you say "these hosts are a dbservers" or "these hosts are webservers". In programming, we might call that 'encapsulating' how things work. For instance,
you can drive a car without knowing how the engine works.
@ -29,7 +29,7 @@ We'll start with understanding includes so roles make more sense, but our ultima
are great and you should use them every time you write playbooks.
See the 'ansible-examples' repository on github for lots of examples of all of this
put together. You may wish to have this open in a seperate tab as you dive in.
put together. You may wish to have this open in a separate tab as you dive in.
Task Include Files And Encouraging Reuse
````````````````````````````````````````
@ -148,7 +148,7 @@ Now that you have learned about vars_files, tasks, and handlers, what is the bes
The short answer is to use roles! Roles are ways of automatically loading certain vars_files, tasks, and
handlers based on a known file structure. Grouping content by roles also allows easy sharing of roles with other users.
Roles are just automation around 'include' directives as redescribed above, and really don't contain much
Roles are just automation around 'include' directives as described above, and really don't contain much
additional magic beyond some improvements to search path handling for referenced files. However, that can be a big thing!
@ -475,7 +475,7 @@ Similarly, the hostname as the system reports it is::
Facts are frequently used in conditionals (see `playbook_conditionals`) and also in templates.
Facts can be also used to create dynamic groups of hosts that match particular critera, see the :doc:`modules` documentation on 'group_by' for details, as well as in generalized conditional statements as discussed in the `playbook_conditionals` chapter.
Facts can be also used to create dynamic groups of hosts that match particular criteria, see the :doc:`modules` documentation on 'group_by' for details, as well as in generalized conditional statements as discussed in the `playbook_conditionals` chapter.
.._disabling_facts:
@ -561,7 +561,7 @@ While it's mentioned elsewhere in that document too, here's a quick syntax examp
when: foo_result.rc == 5
Registered variables are valid on the host the remainder of the playbook run, which is the same as the lifetime of "facts"
in Ansible. Effectively registerd variables are just like facts.
in Ansible. Effectively registered variables are just like facts.
.._accessing_complex_variable_data:
@ -792,7 +792,7 @@ control you might want over values.
First off, group variables are super powerful.
Site wide defaults should be defined as a 'group_vars/all' setting. Group variables are generally placed alongside
your inventory file. They can also be returned by a dynamic inventroy script (see `intro_dynamic_inventory`) or defined
your inventory file. They can also be returned by a dynamic inventory script (see `intro_dynamic_inventory`) or defined
in things like AnsibleWorks AWX from the UI or API::
---
@ -830,7 +830,7 @@ See `intro_roles` for more info about this::
# if not overriden in inventory or as a parameter, this is the value that will be used
http_port: 80
if you are writing a role and want to ensure the value in the role is absolutely used in that role, and is not going to be overriden
if you are writing a role and want to ensure the value in the role is absolutely used in that role, and is not going to be overridden
by inventory, you should but it in roles/x/vars/main.yml like so, and inventory values cannot override it. -e however, still will::
----
@ -849,7 +849,7 @@ If you are using a role and want to override a default, pass it as a parameter t
roles:
- { name: apache, http_port: 8080 }
This makes it clear to the playbook reader that you've made a concious choice to override some default in the role, or pass in some
This makes it clear to the playbook reader that you've made a conscious choice to override some default in the role, or pass in some
configuration that the role can't assume by itself. It also allows you to pass something site-specific that isn't really part of the
role you are sharing with others.
@ -883,7 +883,7 @@ can set variables in there and make use of them in other roles and elsewhere in
So, that's precedence, explained in a more direct way. Don't worry about precedence, just think about if your role is defining a
variable that is a default, or a "live" variable you definitely want to use. Inventory lies in precedence right in the middle, and
if you want to forceably override something, use -e.
if you want to forcibly override something, use -e.
If you found that a little hard to understand, take a look at the "ansible-examples" repo on our github for a bit more about
Michael DeHaan
11 years ago