Sceptre is a tool to drive AWS CloudFormation. It automates the mundane, repetitive and error-prone tasks, enabling you to concentrate on building better infrastructure.
$ pip install sceptre
More information on installing sceptre can be found in our Installation Guide
View our Docker repository. Images available from version 2.0.0 onward.
To use our Docker image follow these instructions:
Pull the image
docker pull sceptreorg/sceptre:[SCEPTRE_VERSION_NUMBER] e.g.
docker pull sceptreorg/sceptre:2.5.0. Leave out the version number if you
wish to run
latest or run
docker pull sceptreorg/sceptre:latest.
Run the image. You will need to mount the working directory where your
project resides to a directory called
project. You will also need to mount
a volume with your AWS config to your docker container. E.g.
docker run -v $(pwd):/project -v /Users/me/.aws/:/root/.aws/:ro sceptreorg/sceptre:latest --help
If you want to use a custom ENTRYPOINT simply amend the Docker command:
docker run -ti --entrypoint='' sceptreorg/sceptre:latest sh
The above command will enter you into the shell of the Docker container where you can execute sceptre commands - useful for development.
If you have any other environment variables in your non-docker shell you will
need to pass these in on the Docker CLI using the
-e flag. See Docker
documentation on how to achieve this.
Sceptre organises Stacks into "Stack Groups". Each Stack is represented by a
YAML configuration file stored in a directory which represents the Stack Group.
Here, we have two Stacks,
subnets, in a Stack Group named
$ tree . ├── config │ └── dev │ ├── config.yaml │ ├── subnets.yaml │ └── vpc.yaml └── templates ├── subnets.py └── vpc.py
We can create a Stack with the
create command. This
vpc Stack contains a
$ sceptre create dev/vpc.yaml dev/vpc - Creating stack dev/vpc VirtualPrivateCloud AWS::EC2::VPC CREATE_IN_PROGRESS dev/vpc VirtualPrivateCloud AWS::EC2::VPC CREATE_COMPLETE dev/vpc sceptre-demo-dev-vpc AWS::CloudFormation::Stack CREATE_COMPLETE
subnets Stack contains a subnet which must be created in the VPC. To do
this, we need to pass the VPC ID, which is exposed as a Stack output of the
vpc Stack, to a parameter of the
subnets Stack. Sceptre automatically
resolves this dependency for us.
$ sceptre create dev/subnets.yaml dev/subnets - Creating stack dev/subnets Subnet AWS::EC2::Subnet CREATE_IN_PROGRESS dev/subnets Subnet AWS::EC2::Subnet CREATE_COMPLETE dev/subnets sceptre-demo-dev-subnets AWS::CloudFormation::Stack CREATE_COMPLETE
Sceptre implements meta-operations, which allow us to find out information about our Stacks:
$ sceptre list resources dev/subnets.yaml - LogicalResourceId: Subnet PhysicalResourceId: subnet-445e6e32 dev/vpc: - LogicalResourceId: VirtualPrivateCloud PhysicalResourceId: vpc-c4715da0
Sceptre provides Stack Group level commands. This one deletes the whole
Stack Group. The subnet exists within the vpc, so it must be deleted first.
Sceptre handles this automatically:
$ sceptre delete dev Deleting stack dev/subnets Subnet AWS::EC2::Subnet DELETE_IN_PROGRESS dev/subnets - Stack deleted dev/vpc Deleting stack dev/vpc VirtualPrivateCloud AWS::EC2::VPC DELETE_IN_PROGRESS dev/vpc - Stack deleted
Note: Deleting Stacks will only delete a given Stack, or the Stacks that are directly in a given StackGroup. By default Stack dependencies that are external to the StackGroup are not deleted.
Sceptre can also handle cross Stack Group dependencies, take the following example project:
$ tree . ├── config │ ├── dev │ │ ├── network │ │ │ └── vpc.yaml │ │ ├── users │ │ │ └── iam.yaml │ │ ├── compute │ │ │ └── ec2.yaml │ │ └── config.yaml │ └── staging │ └── eu │ ├── config.yaml │ └── stack.yaml ├── hooks │ └── stack.py ├── templates │ ├── network.json │ ├── iam.json │ ├── ec2.json │ └── stack.json └── vars ├── dev.yaml └── staging.yaml
In this project
staging/eu/stack.yaml has a dependency on the output of
dev/users/iam.yaml. If you wanted to create the Stack
Sceptre will resolve all of it's dependencies, including
before attempting to create the Stack.
Sceptre can be used from the CLI, or imported as a Python package.
Usage: sceptre [OPTIONS] COMMAND [ARGS]... Sceptre is a tool to manage your cloud native infrastructure deployments. Options: --version Show the version and exit. --debug Turn on debug logging. --dir TEXT Specify sceptre directory. --output [text|yaml|json] The formatting style for command output. --no-colour Turn off output colouring. --var TEXT A variable to replace the value of an item in config file. --var-file FILENAME A YAML file of variables to replace the values of items in config files. --ignore-dependencies Ignore dependencies when executing command. --merge-vars Merge variables from successive --vars and var files. --help Show this message and exit. Commands: create Creates a stack or a change set. delete Deletes a stack or a change set. describe Commands for describing attributes of stacks. estimate-cost Estimates the cost of the template. execute Executes a Change Set. generate Prints the template. launch Launch a Stack or StackGroup. list Commands for listing attributes of stacks. new Commands for initialising Sceptre projects. set-policy Sets Stack policy. status Print status of stack or stack_group. update Update a stack. validate Validates the template.
Using Sceptre as a Python module is very straightforward. You need to create a SceptreContext, which tells Sceptre where your project path is and which path you want to execute on, we call this the "command path".
After you have created a SceptreContext you need to pass this into a SceptrePlan. On instantiation the SceptrePlan will handle all the required steps to make sure the action you wish to take on the command path are resolved.
After you have instantiated a SceptrePlan you can access all the actions you can
take on a Stack, such as
from sceptre.context import SceptreContext from sceptre.plan.plan import SceptrePlan context = SceptreContext("/path/to/project", "command_path") plan = SceptrePlan(context) plan.launch()
Full API reference documentation can be found in the Documentation
Follow the SceptreOrg Twitter account to get announcements on the latest releases.
See our Contributing Guide