Update credentials.yml documentation and handling

Changes include:

 * Update Makefile to use credentials.yml when it exists
 * Add details on the use of the credentials.yml file to README.md.
 * Update credentials.template comments

test/integration/Makefile

@@ -6,20 +6,28 @@ ifndef CLOUD_RESOURCE_PREFIX
 CLOUD_RESOURCE_PREFIX := $(shell python -c "import string,random; print 'ansible-testing-' + ''.join(random.choice(string.ascii_letters + string.digits) for _ in xrange(8));")
 endif
 
+CREDENTIALS_FILE = credentials.yml
+# If credentials.yml exists, use it
+ifneq ("$(wildcard $(CREDENTIALS_FILE))","")
+CREDENTIALS_ARG = -e @$(CREDENTIALS_FILE)
+else
+CREDENTIALS_ARG =
+endif
+
 all: non_destructive destructive check_mode test_hash
 
 non_destructive:
-	ansible-playbook non_destructive.yml -i $(INVENTORY) -e @$(VARS_FILE) -v $(TEST_FLAGS)
+	ansible-playbook non_destructive.yml -i $(INVENTORY) -e @$(VARS_FILE) $(CREDENTIALS_ARG) -v $(TEST_FLAGS)
 
 destructive:
-	ansible-playbook destructive.yml -i $(INVENTORY) -e @$(VARS_FILE) -v $(TEST_FLAGS)
+	ansible-playbook destructive.yml -i $(INVENTORY) -e @$(VARS_FILE) $(CREDENTIALS_ARG) -v $(TEST_FLAGS)
 
 check_mode:
-	ansible-playbook check_mode.yml -i $(INVENTORY) -e @$(VARS_FILE) -v --check $(TEST_FLAGS)
+	ansible-playbook check_mode.yml -i $(INVENTORY) -e @$(VARS_FILE) $(CREDENTIALS_ARG) -v --check $(TEST_FLAGS)
 
 test_hash:
-	ANSIBLE_HASH_BEHAVIOUR=replace ansible-playbook test_hash.yml -i $(INVENTORY) -v -e '{"test_hash":{"extra_args":"this is an extra arg"}}'
+	ANSIBLE_HASH_BEHAVIOUR=replace ansible-playbook test_hash.yml -i $(INVENTORY) $(CREDENTIALS_ARG) -v -e '{"test_hash":{"extra_args":"this is an extra arg"}}'
-	ANSIBLE_HASH_BEHAVIOUR=merge ansible-playbook test_hash.yml -i $(INVENTORY) -v -e '{"test_hash":{"extra_args":"this is an extra arg"}}'
+	ANSIBLE_HASH_BEHAVIOUR=merge ansible-playbook test_hash.yml -i $(INVENTORY) $(CREDENTIALS_ARG) -v -e '{"test_hash":{"extra_args":"this is an extra arg"}}'
 
 cloud: amazon rackspace
 
@@ -32,18 +40,18 @@ rackspace_cleanup:
 	@echo "FIXME - cleanup_rax.py not yet implemented"
 	@# python cleanup_rax.py -y --match="^$(CLOUD_RESOURCE_PREFIX)"
 
-credentials.yml:
+$(CREDENTIALS_FILE):
-	@echo "No credentials.yml file found.  A file named 'credentials.yml' is needed to provide credentials needed to run cloud tests.  See sample 'credentials.template' file."
+	@echo "No credentials file found.  A file named '$(CREDENTIALS_FILE)' is needed to provide credentials needed to run cloud tests.  See sample 'credentials.template' file."
 	@exit 1
 
-amazon: credentials.yml
+amazon: $(CREDENTIALS_FILE)
-	ansible-playbook amazon.yml -i $(INVENTORY) -e @$(VARS_FILE) -e @credentials.yml -e "resource_prefix=$(CLOUD_RESOURCE_PREFIX)" -v $(TEST_FLAGS) ; \
+	ansible-playbook amazon.yml -i $(INVENTORY) -e @$(VARS_FILE) $(CREDENTIALS_ARG) -e "resource_prefix=$(CLOUD_RESOURCE_PREFIX)" -v $(TEST_FLAGS) ; \
     RC=$$? ; \
     CLOUD_RESOURCE_PREFIX="$(CLOUD_RESOURCE_PREFIX)" make amazon_cleanup ; \
     exit $$RC;
 
-rackspace: credentials.yml
+rackspace: $(CREDENTIALS_FILE)
-	ansible-playbook rackspace.yml -i $(INVENTORY) -e @$(VARS_FILE) -e @credentials.yml -e "resource_prefix=$(CLOUD_RESOURCE_PREFIX)" -v $(TEST_FLAGS) ; \
+	ansible-playbook rackspace.yml -i $(INVENTORY) -e @$(VARS_FILE) $(CREDENTIALS_ARG) -e "resource_prefix=$(CLOUD_RESOURCE_PREFIX)" -v $(TEST_FLAGS) ; \
     RC=$$? ; \
     CLOUD_RESOURCE_PREFIX="$(CLOUD_RESOURCE_PREFIX)" make rackspace_cleanup ; \
     exit $$RC;

test/integration/README.md

@@ -5,15 +5,17 @@ The ansible integration system.
 
 Tests for playbooks, by playbooks.
 
-Some tests may require cloud credentials.
+Some tests may require credentials.  Credentials may be specified with `credentials.yml`.
 
 Tests should be run as root.
 
 Configuration
 =============
 
-Making your own version of integration_config.yml can allow for setting some tunable parameters to help run
+Making your own version of `integration_config.yml` can allow for setting some
-the tests better in your environment.
+tunable parameters to help run the tests better in your environment.  Some
+tests (e.g. cloud) will only run when access credentials are provided.  For
+more information about supported credentials, refer to `credentials.template`.
 
 Prerequisites
 =============
@@ -41,12 +43,30 @@ Destructive Tests
 
 These tests are allowed to install and remove some trivial packages.  You will likely want to devote these
 to a virtual environment.  They won't reformat your filesystem, however :)
-    
+
     make destructive
 
 Cloud Tests
 ===========
 
-Details pending, but these require cloud credentials.  These are not 'tests run in the cloud' so much as tests
+Cloud tests exercise capabilities of cloud modules (e.g. ec2_key).  These are
-that leverage the cloud modules and are organized by cloud provider.
+not 'tests run in the cloud' so much as tests that leverage the cloud modules
+and are organized by cloud provider.
 
+In order to run cloud tests, you must provide access credentials in a file
+named `credentials.yml`.  A sample credentials file named
+`credentials.template` is available for syntax help.
+
+
+Provide cloud credentials:
+    cp credentials.template credentials.yml
+    ${EDITOR:-vi} credentials.yml
+
+Run the tests:
+    make cloud
+
+*WARNING* running cloud integration tests will create and destroy cloud
+resources.  Running these tests may result in additional fees associated with
+your cloud account.  Care is taken to ensure that created resources are
+removed.  However, it is advisable to inspect your AWS console to ensure no
+unexpected resources are running.

test/integration/credentials.template

@@ -1,7 +1,7 @@
 ---
 # AWS Credentials
-ec2_access_key: FIXME
+ec2_access_key:
-ec2_secret_key: FIXME
+ec2_secret_key:
 
-# GITHUB Credentials
+# GITHUB SSH private key - a path to a SSH private key for use with github.com
 github_ssh_private_key: "{{ lookup('env','HOME') }}/.ssh/id_rsa"