=======
Sceptre

.. image:: https://circleci.com/gh/cloudreach/sceptre.png?style=shield
:target: https://circleci.com/gh/cloudreach/sceptre/tree/master

.. image:: https://badge.fury.io/py/sceptre.svg
:target: https://badge.fury.io/py/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>_.