Merge pull request #87 from AlanCoding/release23

Prepare for release, and example script simplification

HISTORY.rst

@@ -1,21 +1,29 @@
 Release History
 ===============
 
-2.0.0 (2014-07-15)
+2.3.0 (2015-10-20)
 ------------------
 
--  Pluggable resource architecture built around click
-
-2.0.1 (2014-07-18)
-------------------
-
--  Updated README and error text
+-  Fixed an issue where the settings file could be world readable
+-  Added the ability to associate a project with an organization
+-  Added setting "verify\_ssl" to disallow insecure connections
+-  Added support for additional cloud credentials
+-  Exposed additional options for a cloud inventory source
+-  Combined " launch-time extra\_vars" with " job\_template extra\_vars"
+   for older Tower versions
+-  Changed the extra\_vars parameters to align with Ansible parameter
+   handling
+-  Added the ability to run ad hoc commands
+-  Included more detail when displaying job information
+-  Added an example bash script to demonstrate tower-cli usage
 
-2.0.2 (2014-10-02)
+2.1.1 (2015-01-27)
 ------------------
 
--  Added ability to set local scope for config file
--  Expanded credential resource to allow options for cloud credentials
+-  Added tests for Python versions 2.6 through 3.4
+-  Added shields for github README
+-  Added job\_tags on job launches
+-  Added option for project local path
 
 2.1.0 (2015-01-21)
 ------------------
@@ -26,26 +34,18 @@ Release History
    sources
 -  Added support for new job\_template job launch endpoint
 
-2.1.1 (2015-01-27)
+2.0.2 (2014-10-02)
 ------------------
 
--  Added tests for Python versions 2.6 through 3.4
--  Added shields for github README
--  Added job\_tags on job launches
--  Added option for project local path
+-  Added ability to set local scope for config file
+-  Expanded credential resource to allow options for cloud credentials
 
-2.3.0 (2015-10-xx)
+2.0.1 (2014-07-18)
 ------------------
 
--  Fixed an issue where the settings file could be world readable
--  Added the ability to associate a project with an organization
--  Added setting "verify\_ssl" to disallow insecure connections
--  Added support for additional cloud credentials
--  Exposed additional options for a cloud inventory source
--  Combined " launch-time extra\_vars" with " job\_template extra\_vars"
-   for older Tower versions
--  Changed the extra\_vars parameters to align with Ansible parameter
-   handling
--  Added the ability to run ad hoc commands
--  Included more detail when displaying job information
--  Added an example bash script to demonstrate tower-cli usage
+-  Updated README and error text
+
+2.0.0 (2014-07-15)
+------------------
+
+-  Pluggable resource architecture built around click

README.rst

@@ -82,7 +82,8 @@ Write to the config files directly.
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The configuration file can also be edited directly. A configuration file
-is a simple file with keys and values, separated by ``:`` or ``=``:
+is a simple file with keys and values, separated by a colon (``:``) or by
+the equality sign (``=``):
 
 .. code:: yaml
 
@@ -115,7 +116,7 @@ CLI invocation generally follows this format:
 
 The "resource" is a type of object within Tower (a noun), such as
 ``user``, ``organization``, ``job_template``, etc.; resource names are
-always singular in Tower CLI (so: it's ``tower-cli user``, never
+always singular in Tower CLI (so it is ``tower-cli user``, never
 ``tower-cli users``).
 
 The "action" is the thing you want to do (a verb). Most Tower CLI
@@ -192,7 +193,7 @@ to the Tower server.
 .. code:: bash
 
     # Launch a job with extra variables from filename.yml, and also a=5
-    $ tower-cli job launch --job-template=1 --extra-vars="a=5 b=3" \   
+    $ tower-cli job launch --job-template=1 --extra-vars="a=5 b=3" \
                                             --extra-vars="@filename.yml"
 
     # Create a job template with that same set of extra variables
@@ -241,7 +242,7 @@ source project, and contributions are highly encouraged. Specifically,
 this CLI project is licensed under the Apache 2.0 license. Pull requests
 and tickets filed in GitHub are welcome.
 
-(C) 2015, Michael DeHaan, and others, Ansible, Inc.
+\(C) 2015, Michael DeHaan, and others, Ansible, Inc.
 
 .. |Build Status| image:: https://img.shields.io/travis/ansible/tower-cli.svg
    :target: https://travis-ci.org/ansible/tower-cli

VERSION

@@ -1 +1 @@
-2.2.0-devel
+2.3.0

docs/examples/README.md

@@ -4,12 +4,13 @@ Examples here are intended to give concrete examples of how the CLI
 can be used in an automated way. It can also help with testing or the defining of
 feature requests.
 
-Expect the setup script to take up to 2 minutes to run. Most of this is due to the project source control downloading the examples
+Expect the setup script to take up to 2 minutes to run. Most of this time is
+waiting for the project source control to sync the examples
 from github to the tower server.
 
 ### Setup
 
-You should have a testing version of tower running and configured in the CLI
+You should have a version of tower running and configured in the CLI
 in order to run any scripts or commands here. With your specific data, that
 can done by the following commands:
 
@@ -19,11 +20,15 @@ $ tower-cli config username leeroyjenkins
 $ tower-cli config password myPassw0rd
 ```
 
+Jobs demonstrated in the script do not connect to another machine, and do
+not require valid machine credentials, so tower-cli config information
+should be all the unique information necessary.
+
 ### Create Fake Data
 
 You may want to reference the
 [fake data creator](/docs/examples/fake_data_creator.sh) for
-examples on how to do things.
+examples on how to create different types of resources.
 
 If you want to run the script, which auto-populates your Tower server
 with a small set of fake data, run the following:
@@ -48,9 +53,10 @@ $ source fake_data_teardown.sh
 ### Warnings
 
 It is strongly suggested that you only run these scripts on testing versions
-of an Ansible Tower host.
+of an Ansible Tower host in order to avoid unintended naming conflicts.
 
-### Module Use Example
+### Python Module Use Example
 
-This bash script example borrows fake data elements from the [tower populator script](https://github.com/jsmartin/tower_populator). The tower_populator script provides an example of how to use the tower-cli python modules.
-
+This bash script example borrows fake data elements from the
+[tower populator script](https://github.com/jsmartin/tower_populator).
+The tower_populator script provides an example of how to use the tower-cli python modules.

docs/examples/fake_data_creator.sh

@@ -26,7 +26,7 @@ hostval=$(tower-cli config host)
 userval=$(tower-cli config username)
 passwordval=$(tower-cli config password)
 
-if [[ $hostval == "host: 127.0.0.1" ]] || [[ $userval == "username: " ]] || [[ $passwordval == "password: " ]]
+if [[ $userval == "username: " ]] || [[ $passwordval == "password: " ]]
 then
   echo "WARNING: Configuration has not been fully set";
   echo "   You will want to run the $ tower-cli config ";
@@ -106,8 +106,8 @@ tower-cli credential create --name=user2 --username=user2 --password=pass1 --tea
 
 echo "Tower-CLI DATA FAKER: creating inventories and groups"
 # Basic localhost examples
-tower-cli inventory create --name=localhost --description="local machine" --organization=Default
-tower-cli host create --name="127.0.0.1" --description="the host in localhost" --inventory="localhost"
+tower-cli inventory create --name=localhost --description="local machine" --organization=Default --variables="variables.yml"
+tower-cli host create --name="127.0.0.1" --description="the host in localhost" --inventory="localhost" --variables="variables.yml"
 # Corporate example uses localhost with special vars for testing
 tower-cli inventory create --name=Production --description="Production Machines" --organization="Hyrule Ventures" --variables="variables.yml"
 tower-cli group create --name=EC2 --credential="AWS creds" --source=ec2 --description="EC2 hosts" --inventory=Production
@@ -135,28 +135,26 @@ tower-cli host associate --host="server.example2.com" --group="web servers"
 
 
 echo "Tower-CLI DATA FAKER: create job templates"
-# Hello world and privledge escalation demonstration
-# Assumes you have on your computer
-#  username     password
-#   user1       password
-#   user2       pass1
-tower-cli job_template create --name="hello_world" --description="needs no privileges" --inventory=localhost --machine-credential=user1 --project=sample_playbooks --playbook=helloworld.yml
-tower-cli job_template create --name="ls_1_to_2" --description="user2 file ls" --inventory=localhost --machine-credential=user1 --become-enabled=true --project=sample_playbooks --playbook=lsuser2.yml
-tower-cli job_template create --name="ls_2_to_1" --description="user1 file ls" --inventory=localhost --machine-credential=user2 --become-enabled=true --project=sample_playbooks --playbook=lsuser1.yml
-# Example from Hyrule
+# Hello world example, including different credentials
+#  note that since we have set "connection: local", the credentials do not matter.
+tower-cli job_template create --name="Hello World Debug" --description="debug statement" --inventory=localhost --machine-credential=user1 --project=sample_playbooks --playbook=debug.yml
+tower-cli job_template create --name="Hello World" --description="echo statement" --inventory=localhost --machine-credential=user1 --project=sample_playbooks --playbook=helloworld.yml
+tower-cli job_template create --name="Hello World as user2" --description="echo statement with user2 credentials" --inventory=localhost --machine-credential=user2 --project=sample_playbooks --playbook=helloworld.yml
+# Example from Hyrule data set
 tower-cli job_template create --name=Apache --description="Confgure Apache servers" --inventory=Testing --project="Hyrulian Playbooks" --playbook="site.yml" --machine-credential="Local SSH" --job-type=run --verbosity=verbose --forks=5
 
-echo "Tower-CLI DATA FAKER: run jobs and ad hoc commands"
-tower-cli ad_hoc launch --inventory=localhost --machine-credential=user1 --module-args="echo 'hi, world!!1'" --monitor
+echo "Tower-CLI DATA FAKER: run a job, check status, cancel, and run with monitoring"
 # Launch job without monitoring
-tower-cli job launch --job-template=hello_world
+tower-cli job launch --job-template="Hello World Debug" --job-explanation="launched by example script"
 # Note that these only work because there are no other completed jobs from that template
 # If that is not true, you need to run "job list" and then cancel with the ID
-tower-cli job status --job-template=hello_world
-tower-cli job cancel --job-template=hello_world
-# privledge escalation example
-tower-cli job launch --job-template=ls_1_to_2 --monitor
-# run an ad hoc command to echo
-tower-cli ad_hoc launch --inventory=localhost --machine-credential=user1 --module-args="echo 'hello world as an ad hoc command!'" --monitor
-# run an ad hoc commant with privledge escalation
-tower-cli ad_hoc launch --inventory=localhost --machine-credential=user1 --module-args="ls /home/user2/" --become --monitor
+tower-cli job status --job-template="Hello World Debug"
+tower-cli job cancel --job-template="Hello World Debug"
+# Note that delete is different from cancel.
+# With delete, we remove the record of this job's run. For instance:
+# tower-cli job delete {pk}
+# launch a job with monitoring turned on
+tower-cli job launch --job-template="Hello World Debug" --monitor --job-explanation="launched by example script"
+
+echo "Tower-CLI DATA FAKER: displaying jobs that have run via the fake data script"
+tower-cli job list --job-template="Hello World Debug"

docs/examples/teardown_script.sh

@@ -2,14 +2,10 @@
 # runs and ad hoc commands because there is no "name" identifier that
 # we can use to automatically look them up.
 
-echo "Tower-CLI DATA FAKER: displaying jobs that must be deleted manually using ID"
-tower-cli job list --job-template=hello_world
-
 echo "Tower-CLI DATA FAKER: deleting job templates"
-tower-cli job_template delete --name="hello_world"
-tower-cli job_template delete --name="ls_1_to_2"
-tower-cli job_template delete --name="ls_2_to_1"
-
+tower-cli job_template delete --name="Hello World"
+tower-cli job_template delete --name="Hello World Debug"
+tower-cli job_template delete --name="Hello World as user2"
 tower-cli job_template delete --name="Apache"
 
 echo "Tower-CLI DATA FAKER: deleting inventories"

docs/examples/variables.yml

@@ -1,2 +1,3 @@
 ---
-ansible_ssh_host: localhost
+connection: local
+ansible_ssh_host: 127.0.0.1