Add documentation

Update main README.md for the Ansible section. Add new README.md files for subsections as needed.

Signed-off-by: Scott Lowe <scott.lowe@scottlowe.org>

ansible/README.md

@@ -6,4 +6,8 @@ This folder contains tools, resources, and examples to help with learning how to
 
 **ansible-aws**: This set of files shows how to use Ansible to both provision infrastructure on AWS as well as how to decommission (tear down) that same infrastructure.
 
+**bootstrap**: This folder contains files that show how to use Ansible to "bootstrap" an Ubuntu 16.04 node with the necessary Python support in order to be able to run additional Ansible modules/playbooks.
+
+**kubeadm-template**: In this folder is an example Jinja2 template and Ansible playbook that provide an example of how to create a templated Kubeadm configuration file.
+
 **src-dst-list**: This set of files shows how to use complex lists with Ansible's "with_items" construct. This allows you to specify, for example, both source and location for a "copy" task in a single block (when both source and destination vary from item to item).

ansible/bootstrap/README.md

@@ -0,0 +1,45 @@
+# Using Ansible to Bootstrap Ansible
+
+These files provide an example of how to use Ansible to bootstrap systems that don't have the necessary Python dependencies installed for full Ansible support. One example is Ubuntu 16.04, which lacks Python 2 support.
+
+## Contents
+
+* **ansible.cfg**: This file tells Ansible where to find the default inventory information (it leverages a dynamic inventory script for AWS).
+
+* **bootstrap.yml**: This Ansible playbook uses the `raw` module to install Python 2 support, which in turn will enable full Ansible support.
+
+* **compute.tf**: This is a Terraform configuration that launches an Ubuntu 16.04 instance on AWS.
+
+* **datasources.tf**: This Terraform configuration looks up the AMI ID for Ubuntu 16.04 and passes it to `compute.tf`.
+
+* **ec2.ini**: This file is the configuration file for the dynamic inventory script. Edit the `regions=` line in this file to specify the AWS regions where instances may be running.
+
+* **ec2.py**: This is a dynamic inventory script to query AWS APIs and generate an inventory that Ansible can use. No edits are needed to this file.
+
+* **provider.tf**: This file configures the AWS provider for Terraform.
+
+* **README.md**: The file you're currently reading.
+
+* **variables.tf**: This file defines the variables that Terraform is expecting to have provided (either via a `terraform.tfvars` file, or via the `terraform` command line).
+
+## Instructions
+
+These instructions assume that you have an AWS account, that you know your AWS access key ID and secret access key, and that both Ansible and Terraform are installed and working on your system. The instructions also assume that the AWS CLI is working correctly.
+
+1. Place the files from the `ansible/boostrap` directory of this GitHub repository into a directory on your local system. You can clone the entire "learning-tools" repository (using `git clone`) or just download the specific files from the `ansible/bootstrap` folder.
+
+2. Edit `ec2.ini` and make sure the "regions=" line specifies the AWS regions where you will launch instances.
+
+3. Create a `terraform.tfvars` file to contain the values assigned to the variables listed in `variables.tf`.
+
+4. Run `terraform init`, followed by `terraform plan` and `terraform apply` to launch an AWS instance in the region you specified.
+
+5. Run `ansible-playbook bootstrap.yml` to run the Ansible playbook against the AWS instance launched by Terraform.
+
+    The AWS instance should now have the necessary Python dependencies installed to support all Ansible modules and functionality. Enjoy!
+
+6. Run `terraform destroy` to tear down the AWS instance you launched in step 4.
+
+## License
+
+This content is licensed under the MIT License.

ansible/src-dst-list/README.md

@@ -0,0 +1,37 @@
+# Using Complex Lists with Ansible Tasks
+
+These files provide an example of how to use "complex" (multi-value) lists in an Ansible task using the "with_items" construct.
+
+## Contents
+
+* **docker.socket**: This is a systemd unit file defining a socket for the Docker daemon.
+
+* **docker-socket.conf**: This is a systemd drop-in unit to modify the default Docker unit file.
+
+* **docker-tcp.socket**: This systemd unit file defines a TCP socket for the Docker daemon.
+
+* **machines.yml**: This YAML data file is used by Vagrant to determine which VM images to use, how many VMs to create, and what the configuration of those VMs should be.
+
+* **provision.yml**: This Ansible playbook shows the use of the "with_items" construct when items in the list have multiple values/attributes.
+
+* **README.md**: The file you're currently reading.
+
+* **Vagrantfile**: This file is used by Vagrant to spin up VMs. No changes should be needed to this file; all configuration information is provided in `machines.yml`.
+
+## Instructions
+
+These instructions assume that you have both Vagrant and Ansible installed and functioning correctly on your system, and that the virtualization provider used by Vagrant is working as expected. These instructions also assume that you've installed any necessary Vagrant plugins to support the installed virtualization provider.
+
+1. Place the files from the `ansible/src-dst-list` directory of this GitHub repository into a directory on your local system. You can clone the entire "learning-tools" repository (using `git clone`) or just download the specific files from the `ansible/src-dst-list` folder.
+
+2. Install a Vagrant box for CentOS Atomic Host. The `machines.yml` file contains a suggested box for VirtualBox. _This environment does not support other virtualization providers at this time._
+
+3. Run `vagrant up` to spin up the Vagrant VM. Vagrant will automatically invoke Ansible to copy the files into the correct location. This illustrates how Ansible's "with_items" construct can leverage multiple values in a list.
+
+4. Run `vagrant destroy` to tear down the environment.
+
+Enjoy!
+
+## License
+
+This content is licensed under the MIT License.