AWS CloudFormation Starter Playbook

Introduction

This repository provides a starter template for getting started creating AWS infrastructure using Ansible and CloudFormation.

Prerequisites

To run this playbook on your local machine, you must install the following prerequisites:

Ansible 2.2 or higher
Python PIP package manager
The following PIP packages:
- awscli
- boto
- netaddr
- ndg-httpsclient
jq

You must also configure your local environment with your AWS credentials and you will also need to specify the ARN of the IAM role that your playbook will use to run provisioning tasks. Your credentials must have permissions to assume this role.

macOS Environments

On macOS environments, boto must be installed as follows:

$ sudo -H /usr/bin/python -m easy_install pip
...
...
$ sudo -H /usr/bin/python -m pip install boto
...
...

Getting Started

Fork this repository to your own new repository
Review roles/requirements.yml and modify if required
Install roles by running ansible-galaxy install -r roles/requirements.yml
Define environments in the inventory file and group_vars folder
Define a CloudFormation stack name in group_vars/all/vars.yml using the cf_stack_name variable
Add the ARN of the IAM role to assume in each environment by configuring the sts_role_arn variable in group_vars/<environment>/vars.yml
Define your CloudFormation template in templates/stack.yml.j2. Alternatively you can reference a template included with the aws-cloudformation role by setting the cf_stack_template variable to the path of the template relative to the aws-cloudformation role folder (e.g. cf_stack_name: "templates/network.yml.j2")
Define environment-specific configuration settings as required in group_vars/<environment>/vars.yml
If you have stack inputs, define them in using the cf_stack_inputs dictionary in group_vars/all/vars.yml. A common pattern is to then reference environment specific settings for each stack input.
Deploy your stack by running ansible-playbook site.yml -e env=<environment>

Conventions