# Sceptre
[](https://app.circleci.com/pipelines/github/Sceptre)
[](https://hub.docker.com/r/sceptreorg/sceptre)
[](https://pypi.org/project/sceptre/)
[](https://pypi.org/project/sceptre/)
[](https://pypi.org/project/sceptre/)
[](https://pypi.org/project/sceptre/)
[](https://github.com/Sceptre/sceptre/blob/main/LICENSE)
## About
Sceptre is a tool to drive
[AWS CloudFormation](https://aws.amazon.com/cloudformation). It automates the
mundane, repetitive and error-prone tasks, enabling you to concentrate on
building better infrastructure.
## Features
- Code reuse 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
- Stack Group support by bundling related Stacks into logical groups (e.g. dev
and prod)
- Stack Group-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 and regions
- 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
## Benefits
- Utilises cloud-native Infrastructure as Code engines (CloudFormation)
- You do not need to manage state
- Simple templates using popular templating syntax - Yaml & Jinja
- Powerful flexibility using a mature programming language - Python
- Easy to integrate as part of a CI/CD pipeline by using Hooks
- Simple CLI and API
- Unopinionated - Sceptre does not force a specific project structure
## Install
### Using pip
`$ pip install sceptre`
More information on installing sceptre can be found in our
[Installation Guide](https://docs.sceptre-project.org/latest/docs/install.html)
### Using Docker Image
View our [Docker repository](https://hub.docker.com/repositories/sceptreorg).
Images available from version 2.0.0 onward.
To use our Docker image follow these instructions:
1. 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`.
2. 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.
## Example
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, `vpc` and `subnets`, in a Stack Group named `dev`:
```sh
$ 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
VPC.
```sh
$ 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
```
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.
```sh
$ 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:
```sh
$ 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 `dev`
Stack Group. The subnet exists within the vpc, so it must be deleted first.
Sceptre handles this automatically:
```sh
$ 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:
```sh
$ 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 `staging/eu/stack.yaml`,
Sceptre will resolve all of it's dependencies, including `dev/users/iam.yaml`,
before attempting to create the Stack.
## Usage
Sceptre can be used from the CLI, or imported as a Python package.
## CLI
```text
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.
```
## Python
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 `validate()`, `launch()`, `list()` and `delete()`.
```python
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](https://docs.sceptre-project.org/)
## Tutorial and Documentation
- [Get Started](https://docs.sceptre-project.org/latest/docs/get_started.html)
- [Documentation](https://docs.sceptre-project.org/)
## Communication
Sceptre community discussions happen in the #sceptre chanel in the
[og-aws Slack](https://github.com/open-guides/og-aws). To join click
on <http://slackhatesthe.cloud/> to create an account and join the
#sceptre channel.
## Contributing
See our [Contributing Guide](CONTRIBUTING.md)
## Sponsors
[](https://sagebionetworks.org)
[](https://www.godaddy.com)
[](https://www.cloudreach.com)
Raw data
{
"_id": null,
"home_page": "https://github.com/Sceptre/sceptre",
"name": "sceptre",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "aws,cloud,devops,infrastructure,tools,cli",
"author": "Sceptre",
"author_email": "sceptreorg@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/fd/ab/3cc351da1ce48d263e79398ea472c42509c6ab37737c809cf03eb7033d2e/sceptre-4.4.2.tar.gz",
"platform": null,
"description": "# Sceptre\n\n[](https://app.circleci.com/pipelines/github/Sceptre)\n[](https://hub.docker.com/r/sceptreorg/sceptre)\n[](https://pypi.org/project/sceptre/)\n[](https://pypi.org/project/sceptre/)\n[](https://pypi.org/project/sceptre/)\n[](https://pypi.org/project/sceptre/)\n[](https://github.com/Sceptre/sceptre/blob/main/LICENSE)\n\n## About\n\nSceptre is a tool to drive\n[AWS CloudFormation](https://aws.amazon.com/cloudformation). It automates the\nmundane, repetitive and error-prone tasks, enabling you to concentrate on\nbuilding better infrastructure.\n\n## Features\n\n- Code reuse by separating a Stack's template and its configuration\n- Support for templates written in JSON, YAML, Jinja2 or Python DSLs such as\n Troposphere\n- Dependency resolution by passing of Stack outputs to parameters of dependent\n Stacks\n- Stack Group support by bundling related Stacks into logical groups (e.g. dev\n and prod)\n- Stack Group-level commands, such as creating multiple Stacks with a single\n command\n- Fast, highly parallelised builds\n- Built in support for working with Stacks in multiple AWS accounts and regions\n- Infrastructure visibility with meta-operations such as Stack querying\n protection\n- Support for inserting dynamic values in templates via customisable Resolvers\n- Support for running arbitrary code as Hooks before/after Stack builds\n\n## Benefits\n\n- Utilises cloud-native Infrastructure as Code engines (CloudFormation)\n- You do not need to manage state\n- Simple templates using popular templating syntax - Yaml & Jinja\n- Powerful flexibility using a mature programming language - Python\n- Easy to integrate as part of a CI/CD pipeline by using Hooks\n- Simple CLI and API\n- Unopinionated - Sceptre does not force a specific project structure\n\n## Install\n\n### Using pip\n\n`$ pip install sceptre`\n\nMore information on installing sceptre can be found in our\n[Installation Guide](https://docs.sceptre-project.org/latest/docs/install.html)\n\n### Using Docker Image\n\nView our [Docker repository](https://hub.docker.com/repositories/sceptreorg).\nImages available from version 2.0.0 onward.\n\nTo use our Docker image follow these instructions:\n\n1. Pull the image `docker pull sceptreorg/sceptre:[SCEPTRE_VERSION_NUMBER]` e.g.\n `docker pull sceptreorg/sceptre:2.5.0`. Leave out the version number if you\n wish to run `latest` or run `docker pull sceptreorg/sceptre:latest`.\n\n2. Run the image. You will need to mount the working directory where your\n project resides to a directory called `project`. You will also need to mount\n a volume with your AWS config to your docker container. E.g.\n\n`docker run -v $(pwd):/project -v /Users/me/.aws/:/root/.aws/:ro sceptreorg/sceptre:latest --help`\n\nIf you want to use a custom ENTRYPOINT simply amend the Docker command:\n\n`docker run -ti --entrypoint='' sceptreorg/sceptre:latest sh`\n\nThe above command will enter you into the shell of the Docker container where\nyou can execute sceptre commands - useful for development.\n\nIf you have any other environment variables in your non-docker shell you will\nneed to pass these in on the Docker CLI using the `-e` flag. See Docker\ndocumentation on how to achieve this.\n\n## Example\n\nSceptre organises Stacks into \"Stack Groups\". Each Stack is represented by a\nYAML configuration file stored in a directory which represents the Stack Group.\nHere, we have two Stacks, `vpc` and `subnets`, in a Stack Group named `dev`:\n\n```sh\n$ tree\n.\n\u251c\u2500\u2500 config\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 dev\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 config.yaml\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 subnets.yaml\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 vpc.yaml\n\u2514\u2500\u2500 templates\n \u251c\u2500\u2500 subnets.py\n \u2514\u2500\u2500 vpc.py\n```\n\nWe can create a Stack with the `create` command. This `vpc` Stack contains a\nVPC.\n\n```sh\n$ sceptre create dev/vpc.yaml\n\ndev/vpc - Creating stack dev/vpc\nVirtualPrivateCloud AWS::EC2::VPC CREATE_IN_PROGRESS\ndev/vpc VirtualPrivateCloud AWS::EC2::VPC CREATE_COMPLETE\ndev/vpc sceptre-demo-dev-vpc AWS::CloudFormation::Stack CREATE_COMPLETE\n```\n\nThe `subnets` Stack contains a subnet which must be created in the VPC. To do\nthis, we need to pass the VPC ID, which is exposed as a Stack output of the\n`vpc` Stack, to a parameter of the `subnets` Stack. Sceptre automatically\nresolves this dependency for us.\n\n```sh\n$ sceptre create dev/subnets.yaml\ndev/subnets - Creating stack\ndev/subnets Subnet AWS::EC2::Subnet CREATE_IN_PROGRESS\ndev/subnets Subnet AWS::EC2::Subnet CREATE_COMPLETE\ndev/subnets sceptre-demo-dev-subnets AWS::CloudFormation::Stack CREATE_COMPLETE\n```\n\nSceptre implements meta-operations, which allow us to find out information about\nour Stacks:\n\n```sh\n$ sceptre list resources dev/subnets.yaml\n\n- LogicalResourceId: Subnet\n PhysicalResourceId: subnet-445e6e32\n dev/vpc:\n- LogicalResourceId: VirtualPrivateCloud\n PhysicalResourceId: vpc-c4715da0\n```\n\nSceptre provides Stack Group level commands. This one deletes the whole `dev`\nStack Group. The subnet exists within the vpc, so it must be deleted first.\nSceptre handles this automatically:\n\n```sh\n$ sceptre delete dev\n\nDeleting stack\ndev/subnets Subnet AWS::EC2::Subnet DELETE_IN_PROGRESS\ndev/subnets - Stack deleted\ndev/vpc Deleting stack\ndev/vpc VirtualPrivateCloud AWS::EC2::VPC DELETE_IN_PROGRESS\ndev/vpc - Stack deleted\n```\n\n> Note: Deleting Stacks will _only_ delete a given Stack, or the Stacks that are\n> directly in a given StackGroup. By default Stack dependencies that are\n> external to the StackGroup are not deleted.\n\nSceptre can also handle cross Stack Group dependencies, take the following\nexample project:\n\n```sh\n$ tree\n.\n\u251c\u2500\u2500 config\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 dev\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 network\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 vpc.yaml\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 users\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 iam.yaml\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 compute\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 ec2.yaml\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 config.yaml\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 staging\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 eu\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 config.yaml\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 stack.yaml\n\u251c\u2500\u2500 hooks\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 stack.py\n\u251c\u2500\u2500 templates\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 network.json\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 iam.json\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 ec2.json\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 stack.json\n\u2514\u2500\u2500 vars\n \u251c\u2500\u2500 dev.yaml\n \u2514\u2500\u2500 staging.yaml\n```\n\nIn this project `staging/eu/stack.yaml` has a dependency on the output of\n`dev/users/iam.yaml`. If you wanted to create the Stack `staging/eu/stack.yaml`,\nSceptre will resolve all of it's dependencies, including `dev/users/iam.yaml`,\nbefore attempting to create the Stack.\n\n## Usage\n\nSceptre can be used from the CLI, or imported as a Python package.\n\n## CLI\n\n```text\nUsage: sceptre [OPTIONS] COMMAND [ARGS]...\n\n Sceptre is a tool to manage your cloud native infrastructure deployments.\n\nOptions:\n --version Show the version and exit.\n --debug Turn on debug logging.\n --dir TEXT Specify sceptre directory.\n --output [text|yaml|json] The formatting style for command output.\n --no-colour Turn off output colouring.\n --var TEXT A variable to replace the value of an item in\n config file.\n --var-file FILENAME A YAML file of variables to replace the values\n of items in config files.\n --ignore-dependencies Ignore dependencies when executing command.\n --merge-vars Merge variables from successive --vars and var\n files.\n --help Show this message and exit.\n\nCommands:\n create Creates a stack or a change set.\n delete Deletes a stack or a change set.\n describe Commands for describing attributes of stacks.\n estimate-cost Estimates the cost of the template.\n execute Executes a Change Set.\n generate Prints the template.\n launch Launch a Stack or StackGroup.\n list Commands for listing attributes of stacks.\n new Commands for initialising Sceptre projects.\n set-policy Sets Stack policy.\n status Print status of stack or stack_group.\n update Update a stack.\n validate Validates the template.\n```\n\n## Python\n\nUsing Sceptre as a Python module is very straightforward. You need to create a\nSceptreContext, which tells Sceptre where your project path is and which path\nyou want to execute on, we call this the \"command path\".\n\nAfter you have created a SceptreContext you need to pass this into a\nSceptrePlan. On instantiation the SceptrePlan will handle all the required steps\nto make sure the action you wish to take on the command path are resolved.\n\nAfter you have instantiated a SceptrePlan you can access all the actions you can\ntake on a Stack, such as `validate()`, `launch()`, `list()` and `delete()`.\n\n```python\nfrom sceptre.context import SceptreContext\nfrom sceptre.plan.plan import SceptrePlan\n\ncontext = SceptreContext(\"/path/to/project\", \"command_path\")\nplan = SceptrePlan(context)\nplan.launch()\n```\n\nFull API reference documentation can be found in the\n[Documentation](https://docs.sceptre-project.org/)\n\n## Tutorial and Documentation\n\n- [Get Started](https://docs.sceptre-project.org/latest/docs/get_started.html)\n- [Documentation](https://docs.sceptre-project.org/)\n\n## Communication\n\nSceptre community discussions happen in the #sceptre chanel in the\n[og-aws Slack](https://github.com/open-guides/og-aws). To join click\non <http://slackhatesthe.cloud/> to create an account and join the\n#sceptre channel.\n\n## Contributing\n\nSee our [Contributing Guide](CONTRIBUTING.md)\n\n## Sponsors\n\n[![Sage Bionetworks](sponsors/sage_bionetworks_logo.png \"Sage Bionetworks\")](https://sagebionetworks.org)\n\n[![GoDaddy](sponsors/godaddy_logo.png \"GoDaddy\")](https://www.godaddy.com)\n\n[![Cloudreach](sponsors/cloudreach_logo.png \"Cloudreach\")](https://www.cloudreach.com)\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "An AWS Cloud Provisioning Tool",
"version": "4.4.2",
"project_urls": {
"Documentation": "https://docs.sceptre-project.org",
"Homepage": "https://github.com/Sceptre/sceptre",
"Repository": "https://github.com/Sceptre/sceptre"
},
"split_keywords": [
"aws",
"cloud",
"devops",
"infrastructure",
"tools",
"cli"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "181d6ed5549897153aee9d98a6c404aa5dd25e817d89aed0d44d7a118121dfe1",
"md5": "40212cd4be488209c4595485f373aeb7",
"sha256": "b5072ca390640f9966bd0277fa3ef26285f741557d8814ef51a81fa715925c6f"
},
"downloads": -1,
"filename": "sceptre-4.4.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "40212cd4be488209c4595485f373aeb7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 108286,
"upload_time": "2024-01-13T07:58:04",
"upload_time_iso_8601": "2024-01-13T07:58:04.002981Z",
"url": "https://files.pythonhosted.org/packages/18/1d/6ed5549897153aee9d98a6c404aa5dd25e817d89aed0d44d7a118121dfe1/sceptre-4.4.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fdab3cc351da1ce48d263e79398ea472c42509c6ab37737c809cf03eb7033d2e",
"md5": "f7a64774ba784dc8dc31e4a3cfa1ba7f",
"sha256": "5bb5683233346dc9bb7584d817851403f7b1c483d4d3ace805c76ebd09b9a49a"
},
"downloads": -1,
"filename": "sceptre-4.4.2.tar.gz",
"has_sig": false,
"md5_digest": "f7a64774ba784dc8dc31e4a3cfa1ba7f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 86030,
"upload_time": "2024-01-13T07:58:06",
"upload_time_iso_8601": "2024-01-13T07:58:06.764181Z",
"url": "https://files.pythonhosted.org/packages/fd/ab/3cc351da1ce48d263e79398ea472c42509c6ab37737c809cf03eb7033d2e/sceptre-4.4.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-13 07:58:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Sceptre",
"github_project": "sceptre",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"circle": true,
"tox": true,
"lcname": "sceptre"
}
JSON
