Get Started

Install

This tutorial assumes that you have installed Sceptre. Instructions on how to do this can be found in the section on installing Sceptre.

AWS CLI Config

Sceptre uses the same configuration files as the official AWS CLI and can be configured using the aws configure command. This command configures 2 files ~/.aws/config and ~/.aws/credentials to setup the API Keys to access your AWS Account.

Reference: AWS_CLI_Configure

Directory Structure

sceptre new provides a quick and easy way to setup a Sceptre project.

To setup a fresh project run:

$ sceptre new project my-sceptre-project

Please enter a region []:
Please enter a project_code [my-sceptre-project]:

This will produce the following directory structure:

tree
.
my-sceptre-project
    ├── config
    │   └── config.yaml
    └── templates

The config directory is where you will keep the configuration for your Stacks and the templates directory is where you will keep your CloudFormation templates.

Lets add our first template and stack config. We are going to create a StackGroup (directory) called dev and setup a Stack with a single VPC in it.

On *nix systems:

mkdir config/dev
touch config/dev/config.yaml config/dev/vpc.yaml templates/vpc.yaml

templates/vpc.yaml will contain a CloudFormation template, config/dev/vpc.yaml will contain config relevant to that template, and config.yaml will contain environment config.

Our First Template - vpc.yaml

Add the following CloudFormation to templates/vpc.yaml:

Parameters:
  CidrBlock:
    Type: String
Resources:
  VPC:
    Type: 'AWS::EC2::VPC'
    Properties:
      CidrBlock:
        Ref: CidrBlock
Outputs:
  VpcId:
    Value:
      Ref: VPC

For more information on CloudFormation, see the AWS documentation on CloudFormation.

Our First StackGroup config - config.yaml

Add the following configuration to config/dev/config.yaml:

project_code: sceptre-example
region: eu-west-1

Sceptre prefixes stack names with the project_code. All resources in this StackGroup will be built in the AWS region region.

Our First Stack config - vpc.yaml

Add the following configuration to config/dev/vpc.yaml:

template:
  path: vpc.yaml
  type: file
parameters:
  CidrBlock: 10.0.0.0/16

template specifies the relative path to the CloudFormation, Python or Jinja2 template to use to launch the Stack. Sceptre will use the templates directory as the root templates directory to base your path from.

parameters lists the parameters which are supplied to the template vpc.yaml.

You should now have a Sceptre project that looks a bit like:

tree
.
├── config
│   ├── config.yaml
│   └── dev
│       ├── config.yaml
│       └── vpc.yaml
└── templates
    └── vpc.yaml

Note: You do not need to make sure the Template and Stack config names match, since you define the template in your Stack config, but it can be useful to keep track of what is going on.

You will also notice that we have two config.yaml files, one in config/ and the other in config/dev. We will explain this later but Sceptre will eventually merge these two files when generating the overall config file where values from the child configs replace the parent (unless otherwise specified).

Commands

Create stack

We can create the VPC Stack with the following command:

$ sceptre create dev/vpc.yaml

This command must be run from the my-sceptre-project directory.

Meta commands

We can find out information about our running stack:

$ sceptre list resources dev
$ sceptre list resources dev/vpc.yaml
$ sceptre --ignore-dependencies list outputs dev/vpc.yaml

Update stack

If the Stack’s config or Template is changed in vpc.yaml, the Stack can be updated with:

$ sceptre update dev/vpc.yaml

Delete stack

Delete the stack:

$ sceptre delete dev/vpc.yaml

Next Steps

We have created our first Sceptre project, added a Template and Stack config, and used the CLI to create, update and delete the Stack. You can find a full reference to the CLI in our CLI guide