Skip to content

Latest commit

 

History

History
161 lines (116 loc) · 5.74 KB

README.rst

File metadata and controls

161 lines (116 loc) · 5.74 KB
Raw

Sceptre

About

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.

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:

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.

Install

$ pip install sceptre

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

Tutorial and Documentation

Contributions

See our Contributing Guide.