This repository provides a starter template for getting started creating AWS infrastructure using Ansible and CloudFormation.
To run this playbook on your local machine, you must install the following prerequisites:
- Ansible 2.4 or higher
- GNU Make 3.82 or higher
- Python PIP package manager
- The following PIP packages:
- awscli
- boto3
- netaddr
- yq
- 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.
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
...
...
- Fork this repository to your own new repository
- Review
roles/requirements.yml
and modify if required - Install roles by running
make roles
- Define environments in the
inventory
file andgroup_vars
folder or alternatively runingmake environment/<new-environment>
- Define a CloudFormation stack name in
group_vars/all/vars.yml
using theStack.Name
variable - Add the ARN of the IAM role to assume in each environment by configuring the
Sts.Role
variable ingroup_vars/<environment>/vars.yml
- Define your CloudFormation template in
templates/stack.yml.j2
. Alternatively you can reference a template included with theaws-cloudformation
role by setting theStack.Template
variable to the path of the template relative to theaws-cloudformation
role folder (e.g.Stack.Template: "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
Stack.Inputs
dictionary ingroup_vars/all/vars.yml
. A common pattern is to then reference environment specific settings for each stack input. - Generate your stack templates by running
make generate/<environment>
- Deploy your stack by running
make deploy/<environment>
The workflow includes various make commands that help simplify day-to-day tasks:
make roles
- installs Ansible Galaxy rolesmake environment/<environment>
- creates a new environment in theinventory
file andgroup_vars
foldermake generate/<environment>
- generates templates for the specified environmentmake deploy/<environment>
- generates and deploys templates for the specified environment
The various make commands also support the following flags:
/disable_rollback
- disables stack rollback when creating a stack and a failure occurs/disable_policy
- temporarily disables the configured stack policy for a deployment/debug
- applies the flagdebug=true
to display debug task output defined in the playbook/verbose
- applies the flag-vvv
to provide verbose Ansible output
You can use any combination of the above flags in combination with the various make commands:
# Deploy to dev environment
$ make deploy/dev /disable_rollback /debug
...
...
# Generate templates for qa environment
$ make generate/qa /verbose
...
...
-
Environment specific settings should always be prefixed with
Stack.Inputs.
, unless you have environment specific settings for variables related to theaws-sts
oraws-cloudformation
roles as defined below -
Variables related to configuring the
aws-sts
role are prefixed withSts.
-
Variables related to configuring the
aws-cloudformation
role are prefixed withStack.
- ENHANCEMENT : Ansible 2.5 support
- ENHANCEMENT : Improve make/environment command
- ENHANCEMENT : Ansible 2.4 support
- ENHANCEMENT : Add Make workflow
- ENHANCEMENT : Disables updates to existing cloudformation resources
- BUG FIX : Use templates/stack.yml.j2 cloudformation template by default
- ENHANCEMENT : Move Stack.Template specification after comments related to stack template
- NEW FEATURE : Use stack overrides, a new syntax to override portions of the stack template
- NEW FEATURE : Use dot notation syntax for STS configurations
- First Release
Copyright (C) 2017. Case Commons, Inc.
This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.