ansible/community.general
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2024-09-14 20:13:21 +02:00
Code Releases Activity

Tweaking doc titles.

Browse source
This commit is contained in:
Michael DeHaan 2013-09-29 19:10:28 -04:00
parent ad2736b253
commit 71ddb80524
13 changed files with 27 additions and 550 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
docsite/latest/rst/developing_api.rst
View file

@ -1,5 +1,5 @@
API & Integrations
==================
Python API
==========
There are several interesting ways to use Ansible from an API perspective. You can use
the Ansible python API to control nodes, you can extend Ansible to respond to various python events,

7
docsite/latest/rst/developing_inventory.rst
View file

@ -1,11 +1,12 @@
Inventory Plugins
=================
Developing Dynamic Inventory Sources
====================================
As described in `intro_inventory_dynamic`, ansible can pull inventory information from dynamic sources, including cloud sources.
How do we write a new one?
Simple! We just create a script that can return JSON in the right format when fed the proper arguments.
Simple! We just create a script or program that can return JSON in the right format when fed the proper arguments.
You can do this in any language.
Script Conventions
``````````````````

2
docsite/latest/rst/developing_modules.rst
View file

@ -1,4 +1,4 @@
Module Development
Developing Modules
==================
Ansible modules are reusable units of magic that can be used by the Ansible API,

2
docsite/latest/rst/developing_plugins.rst
View file

@ -1,4 +1,4 @@
Plugin Development
Developing Plugins
==================
Ansible is pluggable in a lot of other ways seperate from inventory scripts and callbacks. Many of these features are there to cover

4
docsite/latest/rst/guide_aws.rst
View file

@ -1,5 +1,5 @@
Amazon Web Services
===================
Amazon Web Services Guide
=========================
.. contents::
:depth: 2

4
docsite/latest/rst/intro_adhoc.rst
View file

@ -1,6 +1,6 @@
An Introduction To Ad-Hoc Commands
==================================
Introduction To Ad-Hoc Commands
===============================
.. highlight:: bash

280
docsite/latest/rst/intro_dynamic_inventory.rst
View file

@ -1,281 +1,7 @@
.. _patterns:
Inventory & Patterns
====================
Dynamic Inventory
=================
Ansible works against multiple systems in your infrastructure at the
same time. It does this by selecting portions of systems listed in
Ansible's inventory file, which defaults to /etc/ansible/hosts.
.. contents::
:depth: 2
.. _inventoryformat:
Hosts and Groups
++++++++++++++++
The format for /etc/ansible/hosts is an INI format and looks like this::
mail.example.com
[webservers]
foo.example.com
bar.example.com
[dbservers]
one.example.com
two.example.com
three.example.com
The things in brackets are group names. You don't have to have them,
but they are useful.
If you have hosts that run on non-standard SSH ports you can put the port number
after the hostname with a colon. Ports listed in any SSH config file won't be read,
so it is important that you set them if things are not running on the default port::
badwolf.example.com:5309
Suppose you have just static IPs and want to set up some aliases that don't live in your host file, or you are connecting through tunnels. You can do things like this::
jumper ansible_ssh_port=5555 ansible_ssh_host=192.168.1.50
In the above example, trying to ansible against the host alias "jumper" (which may not even be a real hostname) will contact 192.168.1.50 on port 5555.
Adding a lot of hosts? In 0.6 and later, if you have a lot of hosts following similar patterns you can do this rather than listing each hostname::
[webservers]
www[01:50].example.com
In 1.0 and later, you can also do this for alphabetic ranges::
[databases]
db-[a:f].example.com
For numeric patterns, leading zeros can be included or removed, as desired. Ranges are inclusive.
In 1.1 and later, you can also select the connection type and user on a per host basis::
[targets]
localhost ansible_connection=local
other1.example.com ansible_connection=ssh ansible_ssh_user=mpdehaan
other2.example.com ansible_connection=ssh ansible_ssh_user=mdehaan
All of these variables can of course also be set outside of the inventory file, in 'host_vars' if you wish
to keep your inventory file simple.
List of Reserved Inventory Parameters
+++++++++++++++++++++++++++++++++++++
As a summary, you can set these parameters as host inventory variables. (Some we have already
mentioned).
ansible_ssh_host
The name of the host to connect to, if different from the alias you wish to give to it.
ansible_ssh_port
The ssh port number, if not 22
ansible_ssh_user
The default ssh user name to use.
ansible_ssh_pass
The ssh password to use (this is insecure, we strongly recommend using --ask-pass or SSH keys)
ansible_connection
Connection type of the host. Candidates are local, ssh or paramiko. The default is paramiko before Ansible 1.2, and 'smart' afterwards which detects whether usage of 'ssh' would be feasible based on whether ControlPersist is supported.
ansible_ssh_private_key_file
Private key file used by ssh. Useful if using multiple keys and you don't want to use SSH agent.
ansible_syslog_facility
The syslog facility to log to.
ansible_python_interpreter
The target host python path. This is userful for systems with more
than one Python or not located at "/usr/bin/python" such as \*BSD, or where /usr/bin/python
is not a 2.X series Python.
ansible\_\*\_interpreter
Works for anything such as ruby or perl and works just like ansible_python_interpreter.
This replaces shebang of modules which will run on that host.
Examples from a host file::
some_host ansible_ssh_port=2222 ansible_ssh_user=manager
aws_host ansible_ssh_private_key_file=/home/example/.ssh/aws.pem
freebsd_host ansible_python_interpreter=/usr/local/bin/python
ruby_module_host ansible_ruby_interpreter=/usr/bin/ruby.1.9.3
Selecting Targets
+++++++++++++++++
We'll go over how to use the command line in :doc:`examples` section, however, basically it looks like this::
ansible <pattern_goes_here> -m <module_name> -a <arguments>
Such as::
ansible webservers -m service -a "name=httpd state=restarted"
Within :doc:`playbooks`, these patterns can be used for even greater purposes.
Anyway, to use Ansible, you'll first need to know how to tell Ansible which hosts in your inventory file to talk to.
This is done by designating particular host names or groups of hosts.
The following patterns target all hosts in the inventory file::
all
*
Basically 'all' is an alias for '*'. It is also possible to address a specific host or hosts::
one.example.com
one.example.com:two.example.com
192.168.1.50
192.168.1.*
The following patterns address one or more groups, which are denoted
with the aforementioned bracket headers in the inventory file::
webservers
webservers:dbservers
You can exclude groups as well, for instance, all webservers not in Phoenix::
webservers:!phoenix
You can also specify the intersection of two groups::
webservers:&staging
You can do combinations::
webservers:dbservers:!phoenix:&staging
You can also use variables::
webservers:!{{excluded}}:&{{required}}
Individual host names, IPs and groups, can also be referenced using
wildcards::
*.example.com
*.com
It's also ok to mix wildcard patterns and groups at the same time::
one*.com:dbservers
And if the pattern starts with a '~' it is treated as a regular expression::
~(web|db).*\.example\.com
Easy enough. See :doc:`examples` and then :doc:`playbooks` for how to do things to selected hosts.
Host Variables
++++++++++++++
It is easy to assign variables to hosts that will be used later in playbooks::
[atlanta]
host1 http_port=80 maxRequestsPerChild=808
host2 http_port=303 maxRequestsPerChild=909
Group Variables
+++++++++++++++
Variables can also be applied to an entire group at once::
[atlanta]
host1
host2
[atlanta:vars]
ntp_server=ntp.atlanta.example.com
proxy=proxy.atlanta.example.com
Groups of Groups, and Group Variables
+++++++++++++++++++++++++++++++++++++
It is also possible to make groups of groups and assign
variables to groups. These variables can be used by /usr/bin/ansible-playbook, but not
/usr/bin/ansible::
[atlanta]
host1
host2
[raleigh]
host2
host3
[southeast:children]
atlanta
raleigh
[southeast:vars]
some_server=foo.southeast.example.com
halon_system_timeout=30
self_destruct_countdown=60
escape_pods=2
[usa:children]
southeast
northeast
southwest
southeast
If you need to store lists or hash data, or prefer to keep host and group specific variables
separate from the inventory file, see the next section.
Splitting Out Host and Group Specific Data
++++++++++++++++++++++++++++++++++++++++++
.. versionadded:: 0.6
In addition to the storing variables directly in the INI file, host
and group variables can be stored in individual files relative to the
inventory file. These variable files are in YAML format.
Assuming the inventory file path is::
/etc/ansible/hosts
If the host is named 'foosball', and in groups 'raleigh' and 'webservers', variables
in YAML files at the following locations will be made available to the host::
/etc/ansible/group_vars/raleigh
/etc/ansible/group_vars/webservers
/etc/ansible/host_vars/foosball
For instance, suppose you have hosts grouped by datacenter, and each datacenter
uses some different servers. The data in the groupfile '/etc/ansible/group_vars/raleigh' for
the 'raleigh' group might look like::
---
ntp_server: acme.example.org
database_server: storage.example.org
It is ok if these files do not exist, this is an optional feature.
Tip: In Ansible 1.2 or later the group_vars/ and host_vars/ directories can exist in either
the playbook directory OR the inventory directory. If both paths exist, variables in the playbook
directory will be loaded second.
Tip: Keeping your inventory file and variables in a git repo (or other version control)
is an excellent way to track changes to your inventory and host variables.
.. versionadded:: 0.5
If you ever have two python interpreters on a system, or your Python version 2 interpreter is not found
at /usr/bin/python, set an inventory variable called 'ansible_python_interpreter' to the Python
interpreter path you would like to use.
.. seealso::
:doc:`examples`
Examples of basic commands
:doc:`playbooks`
Learning ansible's configuration management language
`Mailing List <http://groups.google.com/group/ansible-project>`_
Questions? Help? Ideas? Stop by the list on Google Groups
`irc.freenode.net <http://irc.freenode.net>`_
#ansible IRC chat channel
FIXME

4
docsite/latest/rst/intro_inventory.rst
View file

@ -1,7 +1,7 @@
.. _patterns:
Inventory & Patterns
====================
Inventory
=========
Ansible works against multiple systems in your infrastructure at the
same time. It does this by selecting portions of systems listed in

234
docsite/latest/rst/intro_inventory_dynamic.rst
View file

@ -1,234 +0,0 @@
.. _patterns:
Dynamic Inventory Sources
=========================
Often a user of a configuration management system will want to keep inventory
in a different system.
Ansible can talk with remote APIs and servers, or other custom code, to pull in what
hosts should be in certain groups, what hosts have certain variables, and so on.
Frequent examples of things folks wish to communicate with include 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 in github contains some of these already -- including options for EC2/Eucalyptus and OpenStack, which will be detailed below.
It's possible to write an external inventory script in any language. If you are familiar with Puppet terminology, this concept is basically the same as 'external nodes', with the slight difference that it also defines which hosts are managed.
Using Existing Scripts
``````````````````````
Looking at `the Ansible inventory plugins directory on github <https://github.com/ansible/ansible/tree/devel/plugins/inventory>_`, you will find inventory sources already available for:
Amazon Ec2
BSD Jails
Cobbler
Digital Ocean
OpenStack Nova
Linode
RackSpace Cloud
Spacewalk
Vagrant
Zabbix
Read the comments in each file for usage notes as some require configuration or credentials files.
It is recommended you copy the script you are using to /etc/ansible and chmod +x the file. Specifying the file with "-i" will use the
script as a dynamic inventory file in Ansible. Also in ansible, if your inventory location given to "-i" is a directory, you can use
a mixture of inventory scripts and static files at the same time.
Example: The Cobbler External Inventory Script
``````````````````````````````````````````````
Cobbler is a neat datacenter management tool that assists with PXE, DHCP/DNS management, packaging mirroring, and other things.
Cobbler was one of Michael's earlier projects, and is now maintained by James Cammarata, who also works on Ansible for AnsibleWorks.
It is expected that many Ansible may also be `Cobbler <http://cobbler.github.com>`_ users, and those users might like to use their
Cobbler inventory to define what hosts Ansible should talk to.
How does this work?
Cobbler has a generic layer that allows it to represent data for multiple configuration management systems (even at the same time), and has
been referred to as a 'lightweight CMDB' by some admins. This particular script will communicate with Cobbler
lists of hosts in Cobbler to define groups in Ansible -- though this is neither required or suggested, we're just showing you how!
The example script will talk to Cobbler using Cobbler's XMLRPC API.
To tie Ansible's inventory to Cobbler (optional), copy `this script <https://raw.github.com/ansible/ansible/devel/plugins/inventory/cobbler.py>`_ to /etc/ansible/cobbler and `chmod +x` the file. cobblerd will now nee to be running when you are using Ansible.
Test the file by running `./etc/ansible/cobbler` directly. You should see some JSON data output, but it may not have
anything in it just yet.
Let's explore what this does. In cobbler, assume a scenario somewhat like the following::
cobbler profile add --name=webserver --distro=CentOS6-x86_64
cobbler profile edit --name=webserver --mgmt-classes="webserver" --ksmeta="a=2 b=3"
cobbler system edit --name=foo --dns-name="foo.example.com" --mgmt-classes="atlanta" --ksmeta="c=4"
cobbler system edit --name=bar --dns-name="bar.example.com" --mgmt-classes="atlanta" --ksmeta="c=5"
In the example above, the system 'foo.example.com' will be addressable by ansible directly, but will also be addressable when using the group names 'webserver' or 'atlanta'. Since Ansible uses SSH, we'll try to contract system foo over 'foo.example.com', only, never just 'foo'. Similarly, if you try "ansible foo" it wouldn't find the system... but "ansible 'foo*'" would, because the system DNS name starts with 'foo'.
The script doesn't just provide host and group info. In addition, as a bonus, when the 'setup' module is run (which happens automatically when using playbooks), the variables 'a', 'b', and 'c' will all be auto-populated in the templates::
# file: /srv/motd.j2
Welcome, I am templated with a value of a={{ a }}, b={{ b }}, and c={{ c }}
Which could be executed just like this::
ansible webserver -m setup
ansible webserver -m template -a "src=/tmp/motd.j2 dest=/etc/motd"
.. note::
The name 'webserver' came from cobbler, as did the variables for
the config file. You can still pass in your own variables like
normal in Ansible, but variables from the external inventory script
will override any that have the same name.
So, with the template above (motd.j2), this would result in the following data being written to /etc/motd for system 'foo'::
Welcome, I am templated with a value of a=2, b=3, and c=4
And on system 'bar' (bar.example.com)::
Welcome, I am templated with a value of a=2, b=3, and c=5
And technically, though there is no major good reason to do it, this also works too::
ansible webserver -m shell -a "echo {{ a }}"
So in other words, you can use those variables in arguments/actions as well. You might use this to name
a conf.d file appropriately or something similar. Who knows?
Example: AWS EC2 External Inventory Script
``````````````````````````````````````````
If you use Amazon Web Services EC2, maintaining an inventory file staticlaly may not be the best approach as you'll likely want to make
cloud instances come and go frequently, or might even be taking advantage of AWS autoscaling.
For this reason, you can use the `EC2 external inventory <https://raw.github.com/ansible/ansible/devel/plugins/inventory/ec2.py>`_ script.
As with other inventroy scripts, you'll want to specify the path with the "-i" parameter, and will also need to need to copy the `ec2.ini <https://raw.github.com/ansible/ansible/devel/plugins/inventory/ec2.ini>`_ file alongside the ec2 inventory script. Then you can run ansible as you would normally.
ansible -i ec2.py -u ubuntu us-east-1d -m ping
Note that to successfully make an API call to AWS, you will need to configure Boto (the Python interface to AWS). There are a `variety of methods <http://docs.pythonboto.org/en/latest/boto_config_tut.html>`_ available, but the simplest is just to export two environment variables:
export AWS_ACCESS_KEY_ID='AK123'
export AWS_SECRET_ACCESS_KEY='abc123'
You can test the script by itself to make sure your config is correct
cd plugins/inventory
./ec2.py --list
After a few moments, you should see your entire EC2 inventory across all regions in JSON.
Since each region requires its own API call, if you are only using a small set of regions, feel free to edit ``ec2.ini`` and list only the regions you are interested in. There are other config options in ``ec2.ini`` including cache control, and destination variables.
At their heart, inventory files are simply a mapping from some name to a destination address. The default ``ec2.ini`` settings are configured for running Ansible from outside EC2 (from your laptop for example). If you are running Ansible from within EC2 (which will be faster), internal DNS names and IP addresses may make more sense than public DNS names. In this case, you should modify the ``destination_variable`` in ``ec2.ini`` to be the private DNS name of an instance. This is particularly important when running Ansible within a private subnet inside a VPC, where the only way to access an instance is via its private IP address. For VPC instances, `vpc_destination_variable` in ``ec2.ini`` provides a means of using which ever `boto.ec2.instance variable <http://docs.pythonboto.org/en/latest/ref/ec2.html#module-boto.ec2.instance>`_ makes the most sense for your use case.
The EC2 external inventory provides mappings to instances from several groups:
Instance ID
These are groups of one since instance IDs are unique, and therefore function as aliases to the hostnames.
e.g.
``i-00112233``
``i-a1b1c1d1``
Region
A group of all instances in an AWS region.
e.g.
``us-east-1``
``us-west-2``
Availability Zone
A group of all instances in an availability zone.
e.g.
``us-east-1a``
``us-east-1b``
Security Group
Instances belong to one or more security groups. A group is created for each security group, with all characters except alphanumerics, dashes (-) converted to underscores (_). Each group is prefixed by ``security_group_``
e.g.
``security_group_default``
``security_group_webservers``
``security_group_Pete_s_Fancy_Group``
Tags
Each instance can have a variety of key/value pairs associated with it called Tags. The most common tag key is 'Name', though anything is possible. Each key/value pair is its own group of instances, again with special characters converted to underscores, in the format ``tag_KEY_VALUE``
e.g.
``tag_Name_Web``
``tag_Name_redis-master-001``
``tag_aws_cloudformation_logical-id_WebServerGroup``
When the Ansible is interacting with a specific server, the EC2 inventory script is called again with the ``--host HOST`` option. This looks up the HOST in the index cache to get the instance ID, and then makes an API call to AWS to get information about that specific instance. It then makes information about that instance available as variables to your playbooks. Each variable is prefixed by ``ec2_``. Here are some of the variables available:
- ec2_architecture
- ec2_description
- ec2_dns_name
- ec2_id
- ec2_image_id
- ec2_instance_type
- ec2_ip_address
- ec2_kernel
- ec2_key_name
- ec2_launch_time
- ec2_monitored
- ec2_ownerId
- ec2_placement
- ec2_platform
- ec2_previous_state
- ec2_private_dns_name
- ec2_private_ip_address
- ec2_public_dns_name
- ec2_ramdisk
- ec2_region
- ec2_root_device_name
- ec2_root_device_type
- ec2_security_group_ids
- ec2_security_group_names
- ec2_spot_instance_request_id
- ec2_state
- ec2_state_code
- ec2_state_reason
- ec2_status
- ec2_subnet_id
- ec2_tag_Name
- ec2_tenancy
- ec2_virtualization_type
- ec2_vpc_id
Both ``ec2_security_group_ids`` and ``ec2_security_group_names`` are comma-separated lists of all security groups. Each EC2 tag is a variable in the format ``ec2_tag_KEY``.
To see the complete list of variables available for an instance, run the script by itself::
cd plugins/inventory
./ec2.py --host ec2-12-12-12-12.compute-1.amazonaws.com
The EC2 inventory script caches information to avoid repeated calls. To clear this cache, run the ec2 inventory script with the '--refresh-cache' parameter. The maximum age for the cache is set in the ec2.ini file.
Further Examples
````````````````
Examples of using the inventory scripts for other cloud providers (such as Rackspace Cloud or OpenStack Nova) will be added to this documentation over time, though you should be able to easily tell how to get them operational by reading the scripts in github. Feel free to browse them for details about how they function.
Writing Your Own
````````````````
To learn how to write your own inventory script, for example, to interface with our own custom database or web service implementation,
see the `developing_inventory` page.
.. seealso::
:doc:`intro_inventory`
Basic (non-dynamic) inventory information
:doc:`developers_inventory`
How to write your own inventory script
:doc:`modules`
List of built-in modules
`Mailing List <http://groups.google.com/group/ansible-project>`_
Questions? Help? Ideas? Stop by the list on Google Groups
`irc.freenode.net <http://irc.freenode.net>`_
#ansible IRC chat channel

8
docsite/latest/rst/playbooks.rst
View file

@ -1,11 +1,11 @@
Playbooks
=========
Intro to Playbooks
==================
.. contents::
:depth: 2
Introduction
````````````
About Playbooks
```````````````
Playbooks are a completely different way to use ansible than in task execution mode, and are
particularly powerful. Simply put, playbooks are the basis for a really simple

2
docsite/latest/rst/playbooks_async.rst
View file

@ -1,5 +1,3 @@
Asynchronous Actions and Polling
================================

22
docsite/latest/rst/playbooks_error_handling.rst
View file

@ -1,5 +1,5 @@
Error Handling
==============
Error Handling In Playbooks
===========================
Sometimes a command that returns 0 isn't an error. Sometimes a command might not always
need to report that it 'changed' the remote system. This section describes how to change
@ -19,22 +19,8 @@ write a task that looks like this::
command: /bin/false
ignore_errors: yes
Creates and Removes
```````````````````
The creates= and removes= flag on commands can say a command does not need to be run again
when a file exists (or does not exist). This can bring "idempotence" to commands that
normally might produce errors when run a second time unneccessarily, or to avoid redundant
command execution.
- name: install the foo
command: /usr/bin/install-the-foo.sh creates=/opt/foo
In the above example, when /opt/foo exists, the command would not be executed. See the
documentation for the command module in `modules` for more information.
Overriding Changed Result
`````````````````````````
Overriding The Changed Result
`````````````````````````````
.. versionadded:: 1.3

4
docsite/latest/rst/playbooks_lookups.rst
View file

@ -1,5 +1,5 @@
Lookup Plugins
==============
Using Lookups
=============
Lookup plugins allow access of data in Ansible from outside sources. This can include the filesystem
but also external datastores. These values are then made available using the standard templating system