Getting Sarted Guide¶
Use this Getting Started Guide to get you up and running as quickly as possible with your first deployment.
The goal of this guide is to create a given number of S3 buckets. The quickstart assumes you’re familiar with YAML syntax, comfortable with Linux command line and have a working Python 3.x installation.
Create an AWS account¶
Warning
We are not responsible for any charges that may incur. However, this guide does not create AWS resources which are outside of free tier.
If you don’t already have an AWS account, you can sign up for a free trial:
- Go to https://aws.amazon.com/free
- Follow the instructions to sign up for the free trial.
- Go to IAM and create a user with
AdministratorAccess
policy attached and generate access keys.
Install stacks¶
$ pip install cfstacks
Export aws access keys and default region to shell environment, replacing
AWS_ACCESS_KEY_ID
and AWS_SECRET_ACCESS_KEY
with your own keys.
export AWS_ACCESS_KEY_ID=AKIAIERE3KJY2EJB8U2Q
export AWS_SECRET_ACCESS_KEY=BAA3Vpu3X2X493WG63sVRDovoXB8lxgKi3qU9YYl
export AWS_DEFAULT_REGION=us-east-1
Define a template¶
A template describes all the resources for a single CloudFormation stack. A template is written in YAML syntax and is made of two documents: stack metadata document, followed by resources document.
- Metadata document defines stack-specific properties, like stack name, tags, rollback policy, etc.
- Resources document defines AWS resources and it is a standard CloudFormation template, only in YAML.
Create a template file named buckets.yaml
:
---
name: s3-buckets
---
AWSTemplateFormatVersion: '2010-09-09'
Description: S3 buckets
Resources:
{% for n in range(buckets_count|int) %}
S3Bucket{{ loop.index0 }}:
Type: AWS::S3::Bucket
Properties:
BucketName: {{ env }}-{{ bucket_name_prefix }}{{ loop.index0 }}-{{ region }}
{% endfor -%}
In summary, the template describes, that s3-buckets
stack contains
a number of AWS::S3::Bucket
type resources. The number of buckets is
defined via buckets_count
property.
Deploy your template¶
Create our first stack:
$ stacks create --template buckets.yaml --env dev
Required properties not set: buckets_count,bucket_name_prefix
We get an error about missing properties. To fix that, we must specify the
missing properties. Add the --follow
flag, to follow stack events:
$ stacks create --template buckets.yaml --env dev --follow \
--property bucket_name_prefix=my-awesome-bucket \
--property buckets_count=3
2018-09-10 18:30:08.428000+01:00 CREATE_IN_PROGRESS AWS::CloudFormation::Stack s3-buckets User Initiated
2018-09-10 18:30:10.883000+01:00 CREATE_IN_PROGRESS AWS::S3::Bucket S3Bucket0
2018-09-10 18:30:10.963000+01:00 CREATE_IN_PROGRESS AWS::S3::Bucket S3Bucket2
2018-09-10 18:30:10.966000+01:00 CREATE_IN_PROGRESS AWS::S3::Bucket S3Bucket1
2018-09-10 18:30:11.732000+01:00 CREATE_IN_PROGRESS AWS::S3::Bucket S3Bucket2 Resource creation Initiated
2018-09-10 18:30:11.837000+01:00 CREATE_IN_PROGRESS AWS::S3::Bucket S3Bucket0 Resource creation Initiated
2018-09-10 18:30:11.923000+01:00 CREATE_IN_PROGRESS AWS::S3::Bucket S3Bucket1 Resource creation Initiated
2018-09-10 18:30:32.608000+01:00 CREATE_COMPLETE AWS::S3::Bucket S3Bucket2
2018-09-10 18:30:32.615000+01:00 CREATE_COMPLETE AWS::S3::Bucket S3Bucket0
2018-09-10 18:30:32.782000+01:00 CREATE_COMPLETE AWS::S3::Bucket S3Bucket1
2018-09-10 18:30:34.229000+01:00 CREATE_COMPLETE AWS::CloudFormation::Stack s3-buckets
Use of --env
is optional, however it’s a good practice to separate resources by environment.
See your new deployment¶
See the status of your new stack by running:
$ stacks list
s3-buckets CREATE_COMPLETE
If you want to see what resources have been created by the stack, you can do that by running:
$ stacks resources s3-buckets
S3Bucket0 dev-my-awesome-bucket0-us-east-1 AWS::S3::Bucket CREATE_COMPLETE
S3Bucket1 dev-my-awesome-bucket1-us-east-1 AWS::S3::Bucket CREATE_COMPLETE
S3Bucket2 dev-my-awesome-bucket2-us-east-1 AWS::S3::Bucket CREATE_COMPLETE
Clean up¶
Once you are done with your deployment, make sure to delete it to avoid being charged for resources by AWS.
To delete the deployment, run:
$ stacks delete s3-buckets -y
Next steps¶
Now that you have an idea of how stacks enhances CloudFormation, we recommend going through Step-by-Step Walkthrough for more comprehensive walkthrough.