From 5c905fd165752c6ecb99a3814c1e4fc8f3eabaa9 Mon Sep 17 00:00:00 2001 From: Lars Francke Date: Sun, 20 Oct 2013 23:44:19 +0200 Subject: [PATCH 1/7] Fix a few minor issues in the Getting started document --- docsite/rst/intro_getting_started.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docsite/rst/intro_getting_started.rst b/docsite/rst/intro_getting_started.rst index f34ed67756b..f0f7b48cea6 100644 --- a/docsite/rst/intro_getting_started.rst +++ b/docsite/rst/intro_getting_started.rst @@ -65,7 +65,7 @@ do: $ ssh-agent bash $ ssh-add ~/.ssh/id_rsa -(Depending on your setup, you may wish to ansible's --private-key option to specify a pem file instead) +(Depending on your setup, you may wish to use Ansible's --private-key option to specify a pem file instead) Now ping all your nodes: @@ -119,6 +119,8 @@ If you wish to disable this behavior and understand the implications, you can do Alternatively this can be set by an environment variable: +.. code-block:: bash + $ export ANSIBLE_HOST_KEY_CHECKING=False Also note that host key checking in paramiko mode is reasonably slow, therefore switching to 'ssh' is also recommended when using this feature. From afbc2b448dd0924842266d25e253df798cfb9112 Mon Sep 17 00:00:00 2001 From: Lars Francke Date: Mon, 21 Oct 2013 00:17:26 +0200 Subject: [PATCH 2/7] Update intro_dynamic_inventory.rst Minor fixes, style and typos --- docsite/rst/intro_dynamic_inventory.rst | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/docsite/rst/intro_dynamic_inventory.rst b/docsite/rst/intro_dynamic_inventory.rst index f0550a2a323..b97037bc1ee 100644 --- a/docsite/rst/intro_dynamic_inventory.rst +++ b/docsite/rst/intro_dynamic_inventory.rst @@ -33,11 +33,9 @@ been referred to as a 'lightweight CMDB' by some admins. This particular scrip using Cobbler's XMLRPC API. To tie Ansible's inventory to Cobbler (optional), copy `this script `_ to /etc/ansible and `chmod +x` the file. cobblerd will now need -to be running when you are using Ansible. +to be running when you are using Ansible and you'll need to use Ansible's ``-i`` command line option (e.g. ``-i /etc/ansible/cobbler.py``). -When running Ansible, to use this inventory, then path the script with the "-i /etc/ansible/cobbler.py" parameter. - -First test the script by running `./etc/ansible/hosts` directly. You should see some JSON data output, but it may not have +First test the script by running ``/etc/ansible/cobbler.py`` 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:: @@ -87,18 +85,18 @@ Example: AWS EC2 External Inventory Script If you use Amazon Web Services EC2, maintaining an inventory file might not be the best approach, because hosts may come and go over time, be managed by external applications, or you might even be using AWS autoscaling. For this reason, you can use the `EC2 external inventory `_ script. You can use this script in one of two ways. The easiest is to use Ansible's ``-i`` command line option and specify the path to the script after -marking it executable. +marking it executable:: ansible -i ec2.py -u ubuntu us-east-1d -m ping The second option is to copy the script to `/etc/ansible/hosts` and `chmod +x` it. You will also need to copy the `ec2.ini `_ file to `/etc/ansible/ec2.ini`. Then you can run ansible as you would normally. -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 `_ available, but the simplest is just to export two environment variables: +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 `_ 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 +You can test the script by itself to make sure your config is correct:: cd plugins/inventory ./ec2.py --list From 544458e859745aecb187d1ea3b3f047b69171dc0 Mon Sep 17 00:00:00 2001 From: Lars Francke Date: Mon, 21 Oct 2013 00:54:42 +0200 Subject: [PATCH 3/7] Update intro_adhoc.rst Update link texts (hopefully got those correct from Sphinx documentation) and remove section on Limiting hosts as that's covered elsewhere --- docsite/rst/intro_adhoc.rst | 36 +++--------------------------------- 1 file changed, 3 insertions(+), 33 deletions(-) diff --git a/docsite/rst/intro_adhoc.rst b/docsite/rst/intro_adhoc.rst index 88f887e3671..25b38a1583f 100644 --- a/docsite/rst/intro_adhoc.rst +++ b/docsite/rst/intro_adhoc.rst @@ -1,4 +1,3 @@ - Introduction To Ad-Hoc Commands =============================== @@ -100,7 +99,7 @@ Using the :ref:`shell` module looks like this:: $ ansible raleigh -m shell -a 'echo $TERM' When running any command with the Ansible *ad hoc* CLI (as opposed to -:doc:`playbooks`), pay particular attention to shell quoting rules, so +:doc:`Playbooks `), pay particular attention to shell quoting rules, so the local shell doesn't eat a variable before it gets passed to Ansible. For example, using double vs single quotes in the above example would evaluate the variable on the box you were on. @@ -243,7 +242,7 @@ very quickly. After the time limit (in seconds) runs out (``-B``), the process o the remote nodes will be terminated. Typically you'll be only be backgrounding long-running -shell commands or software upgrades only. Backgrounding the copy module does not do a background file transfer. :doc:`playbooks` also support polling, and have a simplified syntax for this. +shell commands or software upgrades only. Backgrounding the copy module does not do a background file transfer. :doc:`Playbooks ` also support polling, and have a simplified syntax for this. .. _checking_facts: @@ -257,36 +256,7 @@ system. These can be used to implement conditional execution of tasks but also Its also possible to filter this output to just export certain facts, see the "setup" module documentation for details. -Read more about facts at :doc:`playbooks_variables` once you're ready to read up on :doc:`playbooks`. - -.. _limiting_hosts: - -Limiting Selected Hosts -``````````````````````` - -What hosts you select to manage can be additionally constrained by using the '--limit' parameter or -by using 'batch' (or 'range') selectors. - -As mentioned above, patterns can be strung together to select hosts in more than one group:: - - $ ansible webservers:dbservers -m command -a "/bin/foo xyz" - -This is an "or" condition. If you want to further constrain the selection, use --limit, which -also works with ``ansible-playbook``:: - - $ ansible webservers:dbservers -m command -a "/bin/foo xyz" --limit region - -Assuming version 0.9 or later, as with other host patterns, values to limit can be separated with ";", ":", or ",". - -Now let's talk about range selection. Suppose you have 1000 servers in group 'datacenter', but only want to target one at a time. This is also easy:: - - $ ansible webservers[0-99] -m command -a "/bin/foo xyz" - $ ansible webservers[100-199] -m command -a "/bin/foo xyz" - -This will select the first 100, then the second 100, host entries in the webservers group. (It does not matter -what their names or IP addresses are). - -Both of these methods can be used at the same time, and ranges can also be passed to the --limit parameter. +Read more about facts at :doc:`playbooks_variables` once you're ready to read up on :doc:`Playbooks `. .. seealso:: From cda707f99e42a7c0fe1332987b2632e1fdc600a3 Mon Sep 17 00:00:00 2001 From: Lars Francke Date: Mon, 21 Oct 2013 00:59:12 +0200 Subject: [PATCH 4/7] Move info on limit from the ad hoc command page to the pattern page --- docsite/rst/intro_patterns.rst | 27 +++++++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/docsite/rst/intro_patterns.rst b/docsite/rst/intro_patterns.rst index f46a5f5a306..dc3485bb934 100644 --- a/docsite/rst/intro_patterns.rst +++ b/docsite/rst/intro_patterns.rst @@ -73,9 +73,32 @@ Most people don't specify patterns as regular expressions, but you can. Just st ~(web|db).*\.example\.com -While we're jumping a bit ahead, additionally, you can add an exclusion criteria just by supplying the "--limit" flag to /usr/bin/ansible or /usr/bin/ansible-playbook:: +Limiting Selected Hosts +``````````````````````` - ansible-playbook site.yml --limit datacenter2 +What hosts you select to manage can be additionally constrained by using the '--limit' parameter or +by using 'batch' (or 'range') selectors. + +As mentioned above, patterns can be strung together to select hosts in more than one group:: + + $ ansible webservers:dbservers -m command -a "/bin/foo xyz" + +This is an "or" condition. If you want to further constrain the selection, use --limit, which +also works with ``ansible-playbook``:: + + $ ansible webservers:dbservers -m command -a "/bin/foo xyz" --limit region + +Assuming version 0.9 or later, as with other host patterns, values to limit can be separated with ";", ":", or ",". + +Now let's talk about range selection. Suppose you have 1000 servers in group 'datacenter', but only want to target one at a time. This is also easy:: + + $ ansible webservers[0-99] -m command -a "/bin/foo xyz" + $ ansible webservers[100-199] -m command -a "/bin/foo xyz" + +This will select the first 100, then the second 100, host entries in the webservers group. (It does not matter +what their names or IP addresses are). + +Both of these methods can be used at the same time, and ranges can also be passed to the --limit parameter. Easy enough. See :doc:`intro_adhoc` and then :doc:`playbooks` for how to apply this knowledge. From d7478e591cfe4ef4fcd34151e3e37fdc077c0e74 Mon Sep 17 00:00:00 2001 From: Lars Francke Date: Tue, 22 Oct 2013 01:05:40 +0200 Subject: [PATCH 5/7] Update intro_configuration.rst Minor RST fixes --- docsite/rst/intro_configuration.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docsite/rst/intro_configuration.rst b/docsite/rst/intro_configuration.rst index 91b5623d2a7..0c1840146a8 100644 --- a/docsite/rst/intro_configuration.rst +++ b/docsite/rst/intro_configuration.rst @@ -1,4 +1,3 @@ - The Ansible Configuration File ++++++++++++++++++++++++++++++ @@ -7,7 +6,7 @@ The Ansible Configuration File Certain things in Ansible are adjustable in a configuration file. In general, the stock configuration is probably right for most users, but that doesn't mean you might not want to change them. -The mechanism for doing this is the "ansible.cfg" file, which is looked for in the following locations: +The mechanism for doing this is the "ansible.cfg" file, which is looked for in the following locations:: * /etc/ansible/ansible.cfg * ~/.ansible.cfg @@ -30,7 +29,7 @@ as a ".rpmnew" file (or other) as appropriate in the case of updates. If you have installed from pip or from source, however, you may want to create this file in order to override default settings in Ansible. -You may wish to consult the `ansible.cfg in source control _` for +You may wish to consult the `ansible.cfg in source control `_ for all of the possible latest values. .. _environmental_configuration: @@ -283,7 +282,7 @@ log_path ======== If present and configured in ansible.cfg, Ansible will log information about executions at the designated location. Be sure -the user running Ansible has permissions on the logfile. +the user running Ansible has permissions on the logfile:: log_path=/var/log/ansible.log From e052251662ec16cd26d39aee2af34852bd16ccb4 Mon Sep 17 00:00:00 2001 From: Lars Francke Date: Tue, 22 Oct 2013 01:10:54 +0200 Subject: [PATCH 6/7] Tiny RST link fix in modules documentation --- docsite/rst/modules.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docsite/rst/modules.rst b/docsite/rst/modules.rst index 20a72a51d4c..38d0cc04665 100644 --- a/docsite/rst/modules.rst +++ b/docsite/rst/modules.rst @@ -11,7 +11,7 @@ Introduction Ansible ships with a number of modules (called the 'module library') -that can be executed directly on remote hosts or through :doc:`playbooks`. +that can be executed directly on remote hosts or through :doc:`Playbooks `. Users can also write their own modules. These modules can control system resources, like services, packages, or files (anything really), or handle executing system commands. From f52b40175538e841d40e75668ffb4f3c2619064f Mon Sep 17 00:00:00 2001 From: Lars Francke Date: Tue, 22 Oct 2013 01:14:24 +0200 Subject: [PATCH 7/7] Delete extra word in index.rst --- docsite/rst/index.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docsite/rst/index.rst b/docsite/rst/index.rst index e292316ab39..96d7ca69b09 100644 --- a/docsite/rst/index.rst +++ b/docsite/rst/index.rst @@ -1,4 +1,3 @@ - Ansible Documentation ===================== @@ -70,7 +69,7 @@ Playbooks Playbooks are Ansible's configuration, deployment, and orchestration language. They can describe a policy you want your remote systems to enforce, or a set of steps in a general IT process. -If Ansible modules are your the tools in your workshop, playbooks are your design plans. +If Ansible modules are the tools in your workshop, playbooks are your design plans. At a basic level, playbooks can be used to manage configurations of and deployments to remote machines. At a more advanced level, they can sequence multi-tier rollouts involving rolling updates, and can delegate actions to other hosts, interacting with monitoring servers and load balancers along the way.