From a33320d03dee06a3e6cb5b97e89f561753dc6dab Mon Sep 17 00:00:00 2001
From: Michael DeHaan <michael.dehaan@gmail.com>
Date: Tue, 1 May 2012 23:22:23 -0400
Subject: [PATCH] Add some comments to ansible-pull and the example playbook

---
 bin/ansible-pull                    | 11 ++++++++++
 examples/playbooks/ansible_pull.yml | 32 +++++++++++++++++++++++++++--
 2 files changed, 41 insertions(+), 2 deletions(-)

diff --git a/bin/ansible-pull b/bin/ansible-pull
index b75c4631e4d..219bc725f08 100755
--- a/bin/ansible-pull
+++ b/bin/ansible-pull
@@ -1,5 +1,15 @@
 #!/usr/bin/env python
 
+# ansible-pull is a script that runs ansible in local mode
+# after checking out a playbooks directory from git.  There is an
+# example playbook to bootstrap this script in the examples/ dir which
+# installs ansible and sets it up to run on cron.
+#
+# usage: 
+#   ansible-pull -d /var/ansible/local -U http://wherever/content.git -C production
+#
+# the git repo must contain a playbook named 'local.yml'
+
 # (c) 2012, Stephen Fromm <sfromm@gmail.com>
 #
 # Ansible is free software: you can redistribute it and/or modify
@@ -47,6 +57,7 @@ def main(args):
 
     git_opts = "repo=%s dest=%s version=%s" % (options.url, options.dest, options.checkout)
     cmd = 'ansible all -c local -m git -a "%s"' % git_opts
+    print "cmd=%s" % cmd
     rc = _run(cmd)
     if rc != 0:
         return rc
diff --git a/examples/playbooks/ansible_pull.yml b/examples/playbooks/ansible_pull.yml
index 8a7e61daf4d..489fd063963 100644
--- a/examples/playbooks/ansible_pull.yml
+++ b/examples/playbooks/ansible_pull.yml
@@ -1,22 +1,50 @@
+# ansibple-pull setup 
+#
+# on remote hosts, set up ansible to run periodically using the latest code
+# from a particular checkout, in pull based fashion, inverting Ansible's
+# usual push-based operating mode.  
+#
+# This particular pull based mode is ideal for:
+#
+# (A) massive scale out
+# (B) continual system remediation
+#
+# DO NOT RUN THIS AGAINST YOUR HOSTS WITHOUT CHANGING THE repo_url
+
+
+# FIXME: change the host group for safety
+
 ---
 - hosts: all
   user: root
+
   vars:
+
     # schdule is fed directly to cron
     schedule: '*/15 * * * *'
+
     # User to run ansible-pull as from cron
     cron_user: root
+
     # Directory to where repository will be cloned
     workdir: /var/lib/ansible/local
-    # Repository to check out
-    repo_url: git://github.com/sfromm/ansible-playbooks.git
+
+    # Repository to check out -- YOU WANT TO CHANGE THIS
+    #repo_url: git://github.com/sfromm/ansible-playbooks.git
+    repo_url: git://github.com/mdehaan/ansible-examples.git
+
   tasks:
+
     - name: Install ansible
       action: yum pkg=ansible state=installed
+
     - name: Create local directory to work from
       action: file path=$workdir state=directory owner=root group=root mode=0751
+
     - name: Copy ansible inventory file to client
       action: copy src=/etc/ansible/hosts dest=/etc/ansible/hosts
               owner=root group=root mode=0644
+
     - name: Create crontab entry to clone/pull git repository
       action: template src=templates/ansible-pull.j2 dest=/etc/cron.d/ansible-pull owner=root group=root mode=0644
+