Skip to main content

Cloud Provisioning Tool

Project description



Sceptre is a tool to drive AWS CloudFormation. It automates away some of the more mundane, repetitive and error-prone tasks, allowing you to concentrate on building better infrastructure.


  • Code reusability by separating a stack’s template and its configuration

  • Support for templates written in JSON, YAML, Jinja2 or Python DSLs such as Troposphere

  • Dependency resolution by passing of stack outputs to parameters of dependent stacks

  • Environment support by bundling related stacks into logical groups (e.g. dev and prod)

  • Environment-level commands, such as creating multiple stacks with a single command

  • Fast, highly parallelised builds

  • Built in support for working with stacks in multiple AWS accounts

  • Infrastructure visibility with meta-operations such as stack querying protection

  • Support for inserting dynamic values in templates via customisable resolvers

  • Support for running arbitrary code as hooks before/after stack builds


Sceptre organises stacks into environments. Each stack is represented by a YAML configuration file stored in a directory which represents the environment. Here, we have two stacks, vpc and subnets, in an environment named dev:

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

We can create a stack with the create-stack command. This vpc stack contains a VPC:

$ sceptre create-stack dev vpc
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

The 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-stack dev subnets
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 describe-env-resources dev
- LogicalResourceId: Subnet
  PhysicalResourceId: subnet-445e6e32
- LogicalResourceId: VirtualPrivateCloud
  PhysicalResourceId: vpc-c4715da0

Sceptre provides environment-level commands. This one deletes the whole dev environment. The subnet exists within the vpc, so it must be deleted first. Sceptre handles this automatically:

$ sceptre delete-env dev
dev/subnets - 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


Sceptre can be used from the CLI, or imported as a Python package.


Usage: sceptre [OPTIONS] COMMAND [ARGS]...

--version             Show the version and exit.
--debug               Turn on debug logging.
--dir TEXT            Specify sceptre directory.
--output [yaml|json]  The formatting style for command output.
--no-colour           Turn off output colouring.
--var TEXT            A variable to template into config files.
--var-file FILENAME   A YAML file of variables to template into config
--help                Show this message and exit.

continue-update-rollback  Roll stack back to working state.
create-change-set         Creates a change set.
create-stack              Creates the stack.
delete-change-set         Delete the change set.
delete-env                Delete all stacks.
delete-stack              Delete the stack.
describe-change-set       Describe the change set.
describe-env              Describe the stack statuses.
describe-env-resources    Describe the env's resources.
describe-stack-outputs    Describe stack outputs.
describe-stack-resources  Describe the stack's resources.
execute-change-set        Execute the change set.
generate-template         Display the template used.
get-stack-policy          Display the stack policy used.
launch-env                Creates or updates all stacks.
launch-stack              Create or launch the stack.
list-change-sets          List change sets.
lock-stack                Prevent stack updates.
set-stack-policy          Set stack policy.
unlock-stack              Allow stack updates.
update-stack              Update the stack.
update-stack-cs           Update the stack via change set.
validate-template         Validate the template.


from sceptre.environment import Environment

env = Environment("/path/to/sceptre_dir", "environment_name")
stack = env.stacks["stack_name"]

A full API description of the sceptre package can be found in the Documentation.


$ pip install sceptre

More information on installing sceptre can be found in our Installation Guide.

Tutorial and Documentation


See our Contributing Guide.


1.2.1 (2017.7.21)

  • Changing Jinja rendering for templates only with ‘.j2’ extension.

  • Fixing broken links in documentation website.

  • Updating references to Python templates instead of Troposphere templates.

1.2.0 (2017.7.14)

  • Increasing maximum number of boto call retires from 5 to 30.

  • Adding support Jinja rendering for stack templates.

  • Adding stricter requirements for existing stack state when launch environments.

  • Adding cmd hook for better cross platform support.

  • Adding documentation around architecture of Sceptre projects.

  • Adding versioned documentation.

  • Improving documentation formatting.

  • Fixing path error bug when using environment level commands on Windows.

  • Fixing bug to correctly throw an AtrributeError in a Python stack template.

1.1.2 (2017.5.26)

  • Fixing bug for protect in stack config.

1.1.1 (2017.2.29)

  • Respect –dir when loading custom resolvers and hooks.

1.1.0 (2017.3.3)

  • Include Scope in update-stack-cs output.

  • Updates to documentation.

1.0.0 (2017.1.31)

  • Removing deprecation notices.

  • Updating documentation.

0.50.0 (2017.1.24)

  • Changing syntax used for resolvers and hooks in config files.

  • Deprecating use of sceptre_get_template function in Troposphere templates.

  • Deprecating the accessing of Troposphere templates returned from sceptre_get_template.

  • Deprecating the accessing of Troposphere templates from the global variable t.

  • Deprecating the global variable SCEPTRE_USER_DATA.

  • Adding support for sceptre_handler function in Troposphere templates.

  • Adding support for pure CloudFormation JSON strings returned by sceptre_handler.

  • Adding support for sceptre_user_data passed to sceptre_handler.

  • Fixing bug in update-stack-cs.

  • Adding project-variables resolver.

0.49.1 (2017.1.6)

  • Adding documentation for CloudFormation Service Role.

0.49.0 (2017.1.6)

  • Updating documentation on hooks.

  • Adding support for CloudFormation Service Role.

  • Adding support for custom stack names.

  • Removing (before|after)_launch hook.

  • Changing documentation styling.

  • Adding Python 3 support.

  • Adding –verbose argument to describe-change-set.

  • Adding support for launching stacks without uploading the template to S3.

  • Adding a FAQ section on parameters vs sceptre_user_data.

  • Adding support for CloudFormation template written in YAML.

  • Bumping boto3 requirement.

  • Adding more intuitive delete stack message.

  • Removing profile.

  • Fixing a multithreading bug.

  • Improve CLI UX by printing only an exception’s message, not the whole stack trace.

  • Adding environment path check.

  • Refactoring out code that fetches stack status.

0.48.0 (2016.12.5)

  • Fixing StackStatusColourer: UPDATE_FAILED wan’t coloured.

  • Fixing bug from uploading templates to S3 from Windows.

  • Improving exception thrown when a user tries to use the stack output resolve on a stack with no outputs.

0.47.0 (2016.12.1)

  • Launch now deletes stacks in the CREATE_FAILED or ROLLBACK_COMPLETE states before re-creating them.

  • Adding support for Troposphere<1.10.0.

0.46.0 (2016.11.11)

  • Adding support for multiple environments.

  • Speeding up integration tests.

  • Switching to CircleCI for continuous integration and deployment of documentation.

  • Changing template S3 key to use a UTC timestamp rather than seconds since epoch.

  • Changing update-stack-cs to delete the change set by default.

  • Stopping appending region to template bucket name.

  • Refactoring logger.

  • Changing exception names from <Name>Exception to <Name>Error.

  • Publishing development docs to

0.45.0 (2016.08.25)

  • Adding support for Troposphere 1.8.

  • Adding stack protection support.

  • Adding support for allowing Troposphere templates to import modules from parent directories.

  • Adding documentation section for IAM role setup.

  • Fixing bug in update-wth-cs command.

0.44.0 (2016.08.5)

  • Adding require_version.

  • Renaming –machine-readable to –output.

  • Refactoring

0.43.4 (2016.08.2)

  • Improving logging.

0.43.3 (2016.08.2)

  • Updating CONTRIBUTING.rst.

0.43.2 (2016.08.1)

  • Fixing multithreaded S3 bucket create bug.

0.43.1 (2016.08.1)

  • Deprecating the CLI flags –iam-role, –profile, –region.

0.43.0 (2016.08.1)

  • Adding machine readable output support.

0.42.0 (2016.08.1)

  • Adding support for CAPABILITY_NAMED_IAM.

0.41.0 (2016.07.28)

  • Adding Resolver support for sceptre_user_data.

0.40.0 (2016.07.28)

  • Adding plugin support for Parameter Resolvers and Hooks.

0.39.2 (2016.07.21)

  • Fixing exit status bug.

0.39.1 (2016.07.15)

  • Updating requirements.

0.39.0 (2016.07.15)

  • Add sceptre_hooks.

  • Add builtin suspend and resume asg scaling actions.

0.38.4 (2016.07.14)

  • Adding deprecation warning for –profile, –region, –iam_role.

0.38.3 (2016.07.14)

  • Combining account_id and iam_role into a single parameter, iam_role, which is now the ARN of the IAM Role to assume.

  • Fixing bug in integration tests.

0.38.2 (2016.07.14)

  • Updating docs.

0.38.1 (2016.07.14)

  • Updating docstrings.

0.38.0 (2016.07.14)

  • Removing autocomplete as it broke integration tests.

  • Fixing integration tests.

0.37.0 (2016.07.13)

  • Adding the ability to tag stacks created by Sceptre.

0.36.0 (2016.07.12)

  • Adding templating support to config files.

0.35.1 (2016.07.12)

  • Fixing permissions on autocomplete files.

0.35.0 (2016.07.12)

  • Sceptre now encrypts templates uploaded to S3 using AES256 by default.

0.34.0 (2016.07.12)

  • Adding autocomplete support for bash and zsh.

0.33.0 (2016.07.11)

  • Specify sceptre directory via –dir flag.

0.32.0 (2016.07.11)

  • Refactoring how parameters are handled internally.

  • Adding stack_output_external resolver.

  • Adding the ability to explicitly specify dependencies.

0.31.0 (2016.07.11)

  • Adding sceptre-update-cs.

0.30.0 (2016.07.08)

  • Tail stack events for sceptre execute-change-set.

  • Added formatted output for sceptre describe-change-set.

0.29.1 (2016.07.08)

  • Fixing CI bug in 0.29.0.

0.29.0 (2016.07.08)

  • Adding automatic support for no-colour’ed output.

0.28.0 (2016.07.07)

  • Adding –no-colour flag.

0.27.2 (2016.07.07)

  • Updating docs to add get-stack-policy and set-stack-policy.

0.27.1 (2016.07.07)

  • Patching unittests and lint from previous release.

0.27.0 (2016.07.07)

  • Adding get-stack-policy and set-stack-policy.

0.26.1 (2016.07.06)

  • Changing ConfigReader object to Config object.

0.26.0 (2016.07.06)

  • Adding more integration tests.

0.25.1 (2016.07.05)

  • Fixing UnrecognisedHookTaskTypeException import in

0.25.0 (2016.07.05)

  • Adding describe-env command.

0.24.1 (2016.07.05)

  • Updating documentation.

0.24.0 (2016.07.04)

  • Ability to specify the region via the cli.

  • Ability to specify a profile via the cli or config.yml.

  • Ability to specify a role via the cli.

  • Skip role assume when no role is specified in config.yaml or via the cli.

0.23.1 (2016.06.30)

  • Moving upload_template_to_s3 into the Template object.

0.23.0 (2016.06.30)

  • Adding support for the cascading of <stack_name>.yaml files.

  • Moved –debug flag to be after sceptre keyword ($ sceptre –debug <command>).

  • Refactor how config is handled internally.

  • Lazy load stack config and templates.

0.22.1 (2016.06.28)

  • Adding dependency resolving to create-change-set.

0.22.0 (2016.06.27)

  • Adding hooks.

0.21.2 (2016.06.24)

  • Refactoring connection_manager.

0.21.1 (2016.06.14)

  • Fixing bug in

0.21.0 (2016.06.14)

  • Adding sceptre describe-stack-outputs command.

0.20.0 (2016.06.14)


  • Switching from configure to PyYaml.

  • Fixing a print stack events error.

0.19.0 (2016.06.8)

  • Adding Boto3 call retries when request limits are hit.

0.18.2 (2016.06.2)

  • Removing a potential race condition when storing templates in S3.

0.18.1 (2016.05.27)

  • Tidying up method names in the Stack() object.

0.18.0 (2016.05.26)

  • Moving to using threading to launch/delete environments.

  • Create/update/launch/delete commands now return non-zero if the command fails.

0.17.0 (2016.05.10)

  • Adding basic integration tests.

0.16.1 (2016.05.9)

  • Bumping to Troposphere 1.6.0.

0.16.0 (2016.05.4)

  • Switching from Docopt to Click, improving support for use as a Python module.

0.15.3 (2016.04.21)

  • Bumping boto3 dependency version to 1.3.1.

0.15.2 (2016.04.21)

  • Defend against troposphere_data being a string in yaml.

0.15.1 (2016.04.14)

  • Moving exceptions into their own file,

0.15.0 (2016.04.14)

  • Support for automatic reading in of arbitrary files.

0.14.1 (2016.04.14)

  • Refactor

0.14.0 (2016.04.11)

  • Adding change set support.

0.13.3 (2016.04.11)

  • Moving dependency resolver code from to

0.13.2 (2016.04.7)

  • Refactoring

0.13.1 (2016.04.7)

  • Improving troposphere template not found exception.

0.13.0 (2016.04.6)

  • Adding $ sceptre --version.

0.12.1 (2016.04.6)

  • Hiding internal class names.

0.12.0 (2016.04.6)

  • Adding support for reading in environment variables for use as CloudFormation parameters.

0.11.0 (2016.03.31)

  • Adding continue-update-rollback command.

0.10.2 (2016.03.31)

  • Refactoring ConfigReader.

0.10.1 (2016.03.31)

  • Updating documentation.

0.10.0 (2016.03.31)

  • Adding Troposphere data injection support.

0.9.1 (2016.03.21)

  • Minor refactor.

0.9.0 (2016.03.21)

  • Adding –debug option.

0.8.2 (2016.03.21)

  • Adding date time to printed out stack events.

0.8.1 (2016.03.21)

  • Fixing bug in generate-template.

0.8.0 (2016.03.21)

  • Sceptre now prints out stack events as stacks are being launched or deleted.

0.7.1 (2016.03.18)

  • Refactoring interactor commands.

0.7.0 (2016.03.17)

  • Adding lock-stack and unlock-stack commands.

0.6.3 (2016.03.16)

  • Adding improved error handling for when users enter incorrect stack names.

0.6.2 (2016.03.16)

  • Adding improved error handling for when users enter incorrect environment paths.

  • Refactoring config_reader

0.6.1 (2016.03.15)

  • Updating documentation.

0.6.0 (2016.03.15)

  • Adding support for user-defined config directory structure.

0.5.1 (2016.03.10)

  • Sceptre waits after checking a stack’s status. This update drops the wait time from 3s to 1s.

0.5.0 (2016.03.10)

  • Adds sceptre validate-template <env> <stack_name> command.

0.4.0 (2016.03.10)

  • Sceptre now creates, updates and launches stacks from a template it uploads to s3.

0.3.2 (2016.03.10)

  • Fixing create_bucket for region us-east-1.

0.3.1 (2016.03.10)

  • Sceptre removes trailing slash from template_bucket_name.

0.3.0 (2016.03.09)

  • Sceptre now appends time since epoch to uploaded JSON template names.

0.2.0 (2016.03.09)

  • Sceptre now appends region to supplied bucket name.

0.1.3 (2016.03.08)

  • Adding support for subdirectories in the template_bucket_name param.

0.1.2 (2016.03.08)

  • Updating Troposphere to version 1.5.0.

0.1.1 (2016.03.08)

  • Updating tox to only support Python 2.6 versions > 2.6.9.

0.1.0 (2016-03-07)

  • Changing how parameter chaining is stated in yaml files.

0.0.1 (2015-12-13)

  • First release.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sceptre-1.2.1.tar.gz (75.0 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page