Skip to main content
This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (pypi.python.org).
Help us improve Python packaging - Donate today!

Cloud Provisioning Tool

Project Description
=======
Sceptre
=======


About
-----

Sceptre is a tool to drive AWS `CloudFormation <https://aws.amazon.com/cloudformation/>`_. It automates away some of the more mundane, repetitive and error-prone tasks, allowing you to concentrate on building better infrastructure.

Features:

- 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


Example
-------

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
├── subnets.py
└── vpc.py


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
dev/subnets:
- LogicalResourceId: Subnet
PhysicalResourceId: subnet-445e6e32
dev/vpc:
- 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


Usage
-----

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

CLI::

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

Options:
--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
files.
--help Show this message and exit.

Commands:
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.


Python:

.. code-block:: python

from sceptre.environment import Environment

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

A full API description of the sceptre package can be found in the `Documentation <https://sceptre.cloudreach.com/latest/docs/index.html>`__.


Install
-------

::

$ pip install sceptre

More information on installing sceptre can be found in our `Installation Guide <https://sceptre.cloudreach.com/latest/docs/install.html>`_.


Tutorial and Documentation
--------------------------

- `Get Started <https://sceptre.cloudreach.com/latest/docs/get_started.html>`_
- `Documentation <https://sceptre.cloudreach.com/latest/docs/index.html>`__


Contributions
-------------

See our `Contributing Guide <CONTRIBUTING.rst>`_.


=======
History
=======

1.3.0 (2017.10.16)
-----------------

* Re-adding the ability to specify credential profile in the environment config.
* Adding init project command to help initialize a new Sceptre project.
* Adding init env command to help initialize a new Environment config.
* Adding diff command to display differences between the local and deployed stack template.
* Fixed error message displayed for empty environments.
* Adding ``environment_config`` to config template rendering.
* Adding ``on_failure`` parameter to stack config.
* Adding automatic renewal of expired credentials when assuming IAM Roles.
* Deprecating use of ``bash`` hook in favour of ``cmd`` hook.
* Deprecating use of ``asg_scheduled_actions`` hook in favour of ``asg_scaling_processes`` hook.
* Adding status colouring for output of describe-env command.
* Fix spelling mistakes in documentation.

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 http://sceptre-dev.ce-tools.cloudreach.com/.

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 hook.py.

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 hook.py.

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 template.py.

0.21.0 (2016.06.14)
-------------------

* Adding sceptre describe-stack-outputs command.

0.20.0 (2016.06.14)
-------------------

* Switching from TROPOSPHERE_DATA to SCEPTRE_USER_DATA.
* 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, ``exceptions.py``.

0.15.0 (2016.04.14)
-------------------

* Support for automatic reading in of arbitrary files.

0.14.1 (2016.04.14)
-------------------

* Refactor ``workplan.py``.

0.14.0 (2016.04.11)
-------------------

* Adding change set support.

0.13.3 (2016.04.11)
-------------------

* Moving dependency resolver code from ``workplan.py`` to ``stack.py``.

0.13.2 (2016.04.7)
------------------

* Refactoring ``stack.py``.

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.
Release History

Release History

This version
History Node

1.3.0

History Node

1.2.1

History Node

1.2.0

History Node

1.1.2

History Node

1.1.1

History Node

1.1.0

History Node

1.0.0

Download Files

Download Files

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

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
sceptre-1.3.0.tar.gz (82.3 kB) Copy SHA256 Checksum SHA256 Source Oct 16, 2017

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting