From 3ecf9cc4f82b76ec1307f92887add21d0f1203eb Mon Sep 17 00:00:00 2001 From: James Routley Date: Mon, 15 May 2017 23:47:33 +0100 Subject: [PATCH] Add rough website outline --- .gitignore | 8 + website/Gemfile | 28 ++ website/Gemfile.lock | 57 ++++ website/_config.yml | 35 ++ website/_includes/docs_navigation.html | 12 + website/_includes/footer.html | 10 + website/_includes/head.html | 5 + website/_includes/navbar.html | 14 + website/_layouts/docs.html | 17 + website/_layouts/home.html | 11 + website/_layouts/page.html | 14 + website/assets/css/sceptre.css | 40 +++ website/docs/advanced_patterns.md | 0 website/docs/cli.md | 83 +++++ website/docs/environment_config.md | 181 +++++++++++ website/docs/faq.md | 0 website/docs/index.md | 9 + website/docs/install.md | 27 ++ website/docs/stack_config.md | 429 +++++++++++++++++++++++++ website/docs/templates.md | 0 website/docs/terminology.md | 33 ++ website/guide.md | 143 +++++++++ website/index.md | 9 + website/intro.md | 31 ++ 24 files changed, 1196 insertions(+) create mode 100644 website/Gemfile create mode 100644 website/Gemfile.lock create mode 100644 website/_config.yml create mode 100644 website/_includes/docs_navigation.html create mode 100644 website/_includes/footer.html create mode 100644 website/_includes/head.html create mode 100644 website/_includes/navbar.html create mode 100644 website/_layouts/docs.html create mode 100644 website/_layouts/home.html create mode 100644 website/_layouts/page.html create mode 100644 website/assets/css/sceptre.css create mode 100644 website/docs/advanced_patterns.md create mode 100644 website/docs/cli.md create mode 100644 website/docs/environment_config.md create mode 100644 website/docs/faq.md create mode 100644 website/docs/index.md create mode 100644 website/docs/install.md create mode 100644 website/docs/stack_config.md create mode 100644 website/docs/templates.md create mode 100644 website/docs/terminology.md create mode 100644 website/guide.md create mode 100644 website/index.md create mode 100644 website/intro.md diff --git a/.gitignore b/.gitignore index b78f5bba7..372cc2690 100644 --- a/.gitignore +++ b/.gitignore @@ -100,3 +100,11 @@ Temporary Items ## File-based project format: *.iws + +# Jekyll settings + +.bundle/ +website/vendor/* +_site/ +.sass-cache/ +.jekyll-metadata diff --git a/website/Gemfile b/website/Gemfile new file mode 100644 index 000000000..8af267397 --- /dev/null +++ b/website/Gemfile @@ -0,0 +1,28 @@ +source "https://rubygems.org" +ruby RUBY_VERSION + +# Hello! This is where you manage which Jekyll version is used to run. +# When you want to use a different version, change it below, save the +# file and run `bundle install`. Run Jekyll with `bundle exec`, like so: +# +# bundle exec jekyll serve +# +# This will help ensure the proper Jekyll version is running. +# Happy Jekylling! +gem "jekyll", "3.4.3" + +# This is the default theme for new Jekyll sites. You may change this to anything you like. +gem "minima", "~> 2.0" + +# If you want to use GitHub Pages, remove the "gem "jekyll"" above and +# uncomment the line below. To upgrade, run `bundle update github-pages`. +# gem "github-pages", group: :jekyll_plugins + +# If you have any plugins, put them here! +group :jekyll_plugins do + gem "jekyll-feed", "~> 0.6" +end + +# Windows does not include zoneinfo files, so bundle the tzinfo-data gem +gem 'tzinfo-data', platforms: [:mingw, :mswin, :x64_mingw, :jruby] + diff --git a/website/Gemfile.lock b/website/Gemfile.lock new file mode 100644 index 000000000..f9a0b4657 --- /dev/null +++ b/website/Gemfile.lock @@ -0,0 +1,57 @@ +GEM + remote: https://rubygems.org/ + specs: + addressable (2.5.1) + public_suffix (~> 2.0, >= 2.0.2) + colorator (1.1.0) + ffi (1.9.18) + forwardable-extended (2.6.0) + jekyll (3.4.3) + addressable (~> 2.4) + colorator (~> 1.0) + jekyll-sass-converter (~> 1.0) + jekyll-watch (~> 1.1) + kramdown (~> 1.3) + liquid (~> 3.0) + mercenary (~> 0.3.3) + pathutil (~> 0.9) + rouge (~> 1.7) + safe_yaml (~> 1.0) + jekyll-feed (0.9.2) + jekyll (~> 3.3) + jekyll-sass-converter (1.5.0) + sass (~> 3.4) + jekyll-watch (1.5.0) + listen (~> 3.0, < 3.1) + kramdown (1.13.2) + liquid (3.0.6) + listen (3.0.8) + rb-fsevent (~> 0.9, >= 0.9.4) + rb-inotify (~> 0.9, >= 0.9.7) + mercenary (0.3.6) + minima (2.1.1) + jekyll (~> 3.3) + pathutil (0.14.0) + forwardable-extended (~> 2.6) + public_suffix (2.0.5) + rb-fsevent (0.9.8) + rb-inotify (0.9.8) + ffi (>= 0.5.0) + rouge (1.11.1) + safe_yaml (1.0.4) + sass (3.4.23) + +PLATFORMS + ruby + +DEPENDENCIES + jekyll (= 3.4.3) + jekyll-feed (~> 0.6) + minima (~> 2.0) + tzinfo-data + +RUBY VERSION + ruby 2.4.1p111 + +BUNDLED WITH + 1.14.6 diff --git a/website/_config.yml b/website/_config.yml new file mode 100644 index 000000000..eb6d097da --- /dev/null +++ b/website/_config.yml @@ -0,0 +1,35 @@ +# Welcome to Jekyll! +# +# This config file is meant for settings that affect your whole blog, values +# which you are expected to set up once and rarely edit after that. If you find +# yourself editing this file very often, consider using Jekyll's data files +# feature for the data you need to update frequently. +# +# For technical reasons, this file is *NOT* reloaded automatically when you use +# 'bundle exec jekyll serve'. If you change this file, please restart the server process. + +# Site settings +# These are used to personalize your new site. If you look in the HTML files, +# you will see them accessed via {{ site.title }}, {{ site.email }}, and so on. +# You can create any custom variable you would like, and they will be accessible +# in the templates via {{ site.myvariable }}. +title: Your awesome title +email: your-email@domain.com +description: > # this means to ignore newlines until "baseurl:" + Write an awesome description for your new site here. You can edit this + line in _config.yml. It will appear in your document head meta (for + Google search results) and in your feed.xml site description. +baseurl: "" # the subpath of your site, e.g. /blog +url: "" # the base hostname & protocol for your site, e.g. http://example.com +twitter_username: jekyllrb +github_username: jekyll + +# Build settings +markdown: kramdown +# theme: minima +gems: + - jekyll-feed +exclude: + - Gemfile + - Gemfile.lock + - vendor diff --git a/website/_includes/docs_navigation.html b/website/_includes/docs_navigation.html new file mode 100644 index 000000000..cb09fcb13 --- /dev/null +++ b/website/_includes/docs_navigation.html @@ -0,0 +1,12 @@ +
+ +
diff --git a/website/_includes/footer.html b/website/_includes/footer.html new file mode 100644 index 000000000..2d2acc91b --- /dev/null +++ b/website/_includes/footer.html @@ -0,0 +1,10 @@ + + + diff --git a/website/_includes/head.html b/website/_includes/head.html new file mode 100644 index 000000000..1746eee9b --- /dev/null +++ b/website/_includes/head.html @@ -0,0 +1,5 @@ + + + + + diff --git a/website/_includes/navbar.html b/website/_includes/navbar.html new file mode 100644 index 000000000..492447c75 --- /dev/null +++ b/website/_includes/navbar.html @@ -0,0 +1,14 @@ + diff --git a/website/_layouts/docs.html b/website/_layouts/docs.html new file mode 100644 index 000000000..8b8db3502 --- /dev/null +++ b/website/_layouts/docs.html @@ -0,0 +1,17 @@ + + +{% include head.html %} + + {% include navbar.html %} +
+
+ {% include docs_navigation.html %} +
+
+ {{ content }} +
+
+ {% include footer.html %} + + + diff --git a/website/_layouts/home.html b/website/_layouts/home.html new file mode 100644 index 000000000..95e33ac2a --- /dev/null +++ b/website/_layouts/home.html @@ -0,0 +1,11 @@ + + +{% include head.html %} + + {% include navbar.html %} +
+ {{ content }} +
+ + + diff --git a/website/_layouts/page.html b/website/_layouts/page.html new file mode 100644 index 000000000..7d67ec78b --- /dev/null +++ b/website/_layouts/page.html @@ -0,0 +1,14 @@ + + + + {% include head.html %} + + + {% include navbar.html %} +
+ {{ content }} +
+ {% include footer.html %} + + + diff --git a/website/assets/css/sceptre.css b/website/assets/css/sceptre.css new file mode 100644 index 000000000..2c76f1c96 --- /dev/null +++ b/website/assets/css/sceptre.css @@ -0,0 +1,40 @@ +@import url('https://fonts.googleapis.com/css?family=Slabo'); + +h1, +h2, +h3, +h4, +h5, +h6 { + /*font-family: slabo;*/ +} + +.navbar { + background-color: #fff; + border-bottom-color: #000; + padding: 25px; +} + +.navbar-default .navbar-brand { + color: #000; +} + +.navbar-default .navbar-nav>li>a { + color: #000; +} + +.navbar-default .navbar-nav>li>a:hover { + color: #00600f; +} + +.spt-docs-nav { + margin-top: 70px; +} + +footer { + border-top-width: 2px; + border-top-color: #000; + /*background-color: #e0e0e0;*/ + margin-top: 70px; + padding: 50px; +} diff --git a/website/docs/advanced_patterns.md b/website/docs/advanced_patterns.md new file mode 100644 index 000000000..e69de29bb diff --git a/website/docs/cli.md b/website/docs/cli.md new file mode 100644 index 000000000..c4c994270 --- /dev/null +++ b/website/docs/cli.md @@ -0,0 +1,83 @@ +--- +layout: docs +--- + +## Command Line Interface + +Sceptre can be used as a command line tool. Sceptre commands take the format: + +``` +$ sceptre [GLOBAL_OPTIONS] COMMAND [ARGS] [COMMAND_OPTIONS] +``` + +Running sceptre without a subcommand will display help, showing a list of the available commands. + +## Global Options + +`--debug`: Turn on debug logging. + +`--dir`: Specify the sceptre directory with an absolute or relative path. + +`--no-colour`: Disable coloured output. + +`--output`: Specify the output format. Available formats: `[yaml, json]`. + +`--var`: Overwrite an arbitrary config item. For more information, see the section on :ref:`templating`. + +`--var-file`: Overwrite arbitrary config item(s) with data from a variables file. For more information, see the section on :ref:`templating`. + + +## Commands + +The available commands are: + +``` +$ sceptre continue-update-rollback +$ sceptre create-change-set +$ sceptre create-stack +$ sceptre delete-change-set +$ sceptre delete-env +$ sceptre delete-stack +$ sceptre describe-change-set +$ sceptre describe-env +$ sceptre describe-env-resources +$ sceptre describe-stack-outputs +$ sceptre describe-stack-resources +$ sceptre execute-change-set +$ sceptre generate-template +$ sceptre get-stack-policy +$ sceptre launch-env +$ sceptre launch-stack +$ sceptre list-change-sets +$ sceptre lock-stack +$ sceptre set-stack-policy +$ sceptre unlock-stack +$ sceptre update-stack +$ sceptre update-stack-cs +$ sceptre validate-template +``` + + +## Command Options + +Command options differ depending on the command, and can be found by running: + +``` +$ sceptre COMMAND --help +``` + + +## Export Stack Outputs to Environment Variables + +Stack outputs can be exported as environment variables with the command: + +```shell +$ eval $(sceptre describe-stack-outputs ENVIRONMENT STACK --export=envvar) +``` + +Note that Sceptre prepends the string `SCEPTRE_` to the name of the environment variable: + +```shell +$ env | grep SCEPTRE +SCEPTRE_= +``` diff --git a/website/docs/environment_config.md b/website/docs/environment_config.md new file mode 100644 index 000000000..11c869dc6 --- /dev/null +++ b/website/docs/environment_config.md @@ -0,0 +1,181 @@ +--- +layout: docs +--- + +# Environment Config + +Environment config stores information related to the environment, such as a particular IAM role to assume, the name of the S3 bucket in which to store templates, and the target region in which to build resources. Environment config is stored in various files around the directory structure, all with the name `config.yaml`. + +## Structure + +An environment config file is a yaml object of key-value pairs configuring Sceptre. The available keys are listed below. + +- [iam_role](#iam_role) *(optional)* +- [project_code](#project_code) *(required)* +- [region](region) *(required)* +- [template_bucket_name](#template_bucket_name) *(optional)* +- [template_key_prefix](#template_key_prefix) *(optional)* +- [require_version](#require_version) *(optional)* + +Sceptre only checks for and uses the above keys in environment config files, but any others added by the user are read in and are made available to the user via the `sceptre.environment.Environment().config` attribute. + + +### iam_role + +The ARN of a role for Sceptre to assume before interacting with the environment. If not supplied, Sceptre uses the user's AWS CLI credentials. + + +### project_code + +A code which is prepended to the stack names of all stacks built by Sceptre. + + +### region + +The AWS region to build stacks in. Sceptre should work in any [region which supports CloudFormation](http://docs.aws.amazon.com/general/latest/gr/rande.html#cfn_region). + + +### template\_bucket\_name + +The name of an S3 bucket to upload CloudFormation Templates to. Note that S3 bucket names must be globally unique. If the bucket does not exist, Sceptre creates one using the given name, in the AWS region specified by `region`. + +If this parameter is not added, Sceptre does not upload the template to S3, but supplies the template to Boto3 via the `TemplateBody` argument. Templates supplied in this way have a lower maximum length, so using the `template_bucket_name` parameter is recommended. + + +### template\_key\_prefix + +A string which is prefixed onto the key used to store templates uploaded to S3. Templates are stored using the key: + +``` +///-. +``` + +Template key prefix can contain slashes ("/"), which are displayed as directories in the S3 console. + +Extension can be `json` or `yaml`. + +Note that if `template_bucket_name` is not supplied, this parameter is ignored. + + +### require_version + +A [PEP 440](https://www.python.org/dev/peps/pep-0440/#version-specifiers) compatible version specifier. If the Sceptre version does not fall within the given version requirement it will abort. + + +## Cascading Config + +Using Sceptre, config files can be cascaded. Given the following sceptre directory structure: + +``` +. +└── config +├── account-1 +│   ├── config.yaml +│   └── dev +│   └── config.yaml +└── config.yaml +``` + +General configurations should be defined at a high level, and more specific configurations should be defined at a lower directory level. YAML files which define configuration settings with names which overlap will take precedence if they are deeper in the directory structure. For example, if you wanted the dev environment to build to a different region, this setting could be specified in the config/dev/config.yaml file, and would only be applied to builds in the dev environment. + +In the above directory structure, `config/config.yaml` will be read in first, followed by `config/account-1/config.yaml`, followed by `config/account-1/dev/config.yaml`. Config files read in later overwrite any key-value pairs shared by those previously read in. Thus general config can be defined at a high level, and more specific config can be defined at a lower directory level. + + +## Templating + +Sceptre supports the use of templating in config files. Templating allows config files to be further configured using values from the command line, environment variables, files or parts of the environment path. + +Internally, Sceptre uses Jinja2 for templating, so any valid Jinja2 syntax should work with Sceptre templating. + +Templating can be used for any values in the config files, not just those that are used by Sceptre. + + +### Var + +User variables are used to replace the value of any item in a config file with a value defined by a cli flag or in a YAML variable file: + +```yaml +iam_role: {% raw %}{{ var.iam_role }}{% endraw %} +region: eu-west-1 +``` + +This item can be set using either a command line flag: + +```shell +$ sceptre --var "iam_role=" +``` + +Or from a YAML variable file: + +```shell +$ sceptre --var-file=variables.yaml +``` + +where `variables.yaml` contains:: + +```yaml +iam_role: +``` + +The `--var` flag can be used multiple times to supply multiple variables. If both `--var` and `--var-file` are supplied, `--var` overwrites any common values in `--var-file`. + +For command line flags, Sceptre splits the string on the first equals sign "=", and sets the key to be the first substring, and the value to be the second. Due to the large number of possible user inputs, no error checking is performed on the value of the --var flag, and it is the user's responsibility to make sure that the value is correctly formatted. + +All user variables are supplied to all config files, so users must be careful to make sure that user variable names do not unintentionally clash. + + +### Environment Variables + +Config item values can be replaced with environment variables: + +```yaml +iam_role: {% raw %}{{ environment_variable.IAM_ROLE }}{% endraw %} +region: eu-west-1 +``` + +Where `IAM_ROLE` is the name of an environment variable. + + +### Environment Path + +Config item values can be replaced with parts of the environment path: + +```yaml +region: {% raw %}{{ environment_path.0 }}{% endraw %} +iam_role: role +``` + +Where the value is taken from the first part of the environment path from the invoking sceptre command: + +```shell +$ sceptre launch-stack eu-west-1/dev vpc +``` + + +### Template Defaults + +Any templated value can be supplied with a default value with the syntax: + +``` +{% raw %}{{ var.value | default("default_value") }}{% endraw %} +``` + + +## Examples + +```yaml +iam_role: arn:aws:iam::123456789012:role/sceptrerole +project_code: prj +region: eu-west-1 +template_bucket_name: sceptre-artifacts +template_key_prefix: my/prefix +``` + +```yaml +{% raw %} +iam_role: {{ var.iam_role }} +project_code: {{ var.project_code | default("prj") }} +region: {{ environment_path.2 }} +template_bucket_name: {{ environment_variable.TEMPLATE_BUCKET_NAME }} +{% endraw %} +``` diff --git a/website/docs/faq.md b/website/docs/faq.md new file mode 100644 index 000000000..e69de29bb diff --git a/website/docs/index.md b/website/docs/index.md new file mode 100644 index 000000000..b3e874433 --- /dev/null +++ b/website/docs/index.md @@ -0,0 +1,9 @@ +--- +layout: docs +--- + +# Documentation + +This documentation acts as an in-depth reference for all of Sceptre's features. + +Beginners should consider reading our [getting started guide]({{ site.url }}/guide.html), which provides a walk-through tutorial. diff --git a/website/docs/install.md b/website/docs/install.md new file mode 100644 index 000000000..f5da1c3ff --- /dev/null +++ b/website/docs/install.md @@ -0,0 +1,27 @@ +--- +layout: docs +--- + +# Installation + +This assumes that you have Python installed. A thorough guide on installing Python can be found [here](http://docs.python-guide.org/en/latest/starting/installation/). We highly recommend using Scetpre from within a `virtualenv`. Notes on installing and setting up `virtualenv` can be found [here](http://docs.python-guide.org/en/latest/dev/virtualenvs/). + +Install Sceptre: + +```shell +$ pip install sceptre +``` + +Validate installation by printing out Sceptre's version number: + +```shell +$ sceptre --version +Sceptre, version +``` + +Update Sceptre: + +```shell +$ pip install sceptre -U +``` + diff --git a/website/docs/stack_config.md b/website/docs/stack_config.md new file mode 100644 index 000000000..ecb0f4821 --- /dev/null +++ b/website/docs/stack_config.md @@ -0,0 +1,429 @@ +--- +layout: docs +--- + +# Stack Config + +Stack config stores config related to a particular stack, such as the path to that stack's template, and any parameters that stack may require. + +## Structure + +A stack config file is a yaml object of key-value pairs configuring a particular stack. The available keys are listed below. + +- [dependencies](#dependencies) *(optional)* +- [hooks](#hooks) *(optional)* +- [parameters](#parameters) *(optional)* +- [protect](#protect) *(optional)* +- [sceptre_user_data](#sceptre_user_data) *(optional)* +- [stack_name](#stack_name) *(optional)* +- [stack_tags](#stack_tags) *(optional)* +- [role_arn](#role_arn) *(optional)* +- [template_path](#template_path) *(required)* + + +### dependencies + +A list of other stacks in the environment that this stack depends on. Note that if a stack fetches an output value from another stack using the `stack_output` resolver, that stack is automatically added as a dependency, and that stack need not be added as an explicit dependency here. + +### hooks + +A list of arbitrary shell or python commands or scripts to run. Find out more in the [Hook](#hook) section. + +### parameters + +
+Warning: Sensitive data such as passwords or secret keys should not be stored in plaintext in stack config files. Instead, they should be passed in from the CLI using :ref:`templating`, or set via an environment variable with the environment variable resolver. +
+ +A dictionary of key-value pairs to be supplied to a CloudFormation or Troposphere template as parameters. The keys must match up with the name of the parameter, and the value must be of the type as defined in the template. Note that Boto3 throws an exception if parameters are supplied to a template that are not required by that template. Resolvers can be used to add functionality to this key. Find out more in the [Resolvers](#resolvers) section. + +A parameter can be specified either as a single value/resolver or a list of values/resolvers. Lists of values/resolvers will be formatted into an AWS compatible comma separated string e.g. `value1,value2,value3`. Lists can contain a mixture of values and resolvers. + +Syntax: + +```yaml +parameters: + : "value" + : ! + : + - "value1" + - "value2" + : + - ! + - ! + : + - ! + - "value1" +``` + +Example: + +```yaml +parameters: + database_username: "mydbuser" + database_password: !environment_variable DATABASE_PASSWORD + subnet_ids: + - "subnet-12345678" + - "subnet-87654321" + security_group_ids: + - "sg-12345678" + - !stack_output security-groups::BaseSecurityGroupId + - !file_contents /file/with/security_group_id.txt +``` + +### protect + +Stack protection against execution of the following commands: + +- `launch-stack` +- `create-stack` +- `update-stack` +- `delete-stack` +- `execute-change-set` + +If a user tries to run one of these commands on a protected stack, Sceptre will throw an error. + +### sceptre\_user\_data + +A dictionary of arbitrary key-value pairs to be passed to the `sceptre_handler(sceptre_user_data)` function in Troposphere templates. + +### stack_name + +A custom name name to use instead of the Sceptre default. + +
+Warning: Outputs from stacks with custom names can't be resolved using the standard stack output resolver. Outputs should be resolved using the stack output external resolver. An explicit dependency should be added, using the dependencies parameter, to make sure the stacks are launched in the correct order. +
+ + e.g:: + + parameters: + VpcID: !stack_output_external ::VpcID + dependencies: + - / + +### stack_tags + +A dictionary of [CloudFormation Tags](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_Tag.html) to be applied to the stack. + +### role_arn + +The ARN of a [CloudFormation Service Role](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-iam-servicerole.html) that is assumed by CloudFormation to create, update or delete resources. + +### template_path + +The path to the CloudFormation or Troposphere template to build the stack from. The path can either be absolute or relative to the Sceptre Directory. Whether Sceptre treats the template as CloudFormation or Troposphere depends on the template's file extension. Templates with `.json` or `.yaml` extensions will be treated as CloudFormation templates whereas files with `.py` extension will be treated as Troposphere. Note that the template filename may be different from the stack config filename. + + +## Cascading Config + +Stack config can be cascaded in the same way Environment config can be, as described in the section in Environment Config on :ref:`cascading_config`. + + +## Templating + +Stack config supports templating in the same way Environment config can be, as described in the section in Environment Config on :ref:`templating`. + + +## Resolvers + +Sceptre implements resolvers, which can be used to resolve a value of a CloudFormation `parameter` or `sceptre_user_data` value at runtime. This is most commonly used to chain the outputs of one stack to the inputs of another. + +If required, users can create their own resolvers, as described in the section :ref:`custom_resolvers`. + +### Syntax + +```yaml +parameters: + : ! +sceptre_user_data: + : ! +``` + + +### Available Resolvers + +#### environment_variable + +Fetches the value from an environment variable. + +Syntax: + +```yaml +parameter|sceptre_user_data: + : !environment_variable ENVIRONMENT_VARIABLE_NAME +``` + +Example: + +``` +parameters: + database_password: !environment_variable DATABASE_PASSWORD +``` + + +#### file_contents + +Reads in the contents of a file. + +Syntax: + +```yaml +parameters|sceptre_user_data: + : !file_contents /path/to/file.txt +``` + +Example: + +```yaml +sceptre_user_data: + iam_policy: !file_contents /path/to/policy.json +``` + +#### stack_output + +Fetches the value of an output from a different stack controlled by Sceptre. + +Syntax: + +```yaml +parameters | sceptre_user_data: + : !stack_output :: +``` + +Example: + +``` +parameters: + VpcIdParameter: !stack_output shared/vpc::VpcIdOutput +``` + + +Sceptre infers that the stack to fetch the output value from is a dependency, and builds that stack before the current one. +This resolver will add a dependency for the stack in which needs the output from. + +#### stack\_output\_external + +Fetches the value of an output from a different stack in the same account and region. + +If the stack whose output is being fetched is in the same environment, the basename of that stack can be used. + +Syntax: + +```yaml +parameters/sceptre_user_data: + : !stack_output_external :: +``` + +Example: + +```yaml +parameters: + VpcIdParameter: !stack_output_external prj-network-vpc::VpcIdOutput +``` + + +#### project_variables + +Keys through the YAML object stored at `/path/to/file.yaml` with the segments of the stack name. + +Syntax: + +```yaml +parameters | sceptre_user_data: + : !project_variables /path/to/file.yaml +``` + +For example, given the stack `dev/vpc`, and the following file (`/my_config_file.yaml`): + +``` +dev: + vpc: + Name: my_vpc +``` + +The resolver will return the dictionary `{"Name": "my_vpc"}`. + +Example (`config/dev/vpc.yaml`): + +```yaml +parameters: + Tag: !project_variables /my_config_file.yaml +``` + + +Environment Variables +--------------------- + +It is possible to replace values in stack config files with environment variables in two ways. For an explanation on why this is the case, see the FAQ on :ref:`two_envvars` + +## Sceptre User Data + +Troposphere templates can contain data which should be parameterised, but can't be parameterised using CloudFormation parameters. An example of this is if a Troposphere template which creates an IAM Role reads in the policy from a JSON file. The file path must be hardcoded in the Troposphere template. + +Sceptre user data allows users to store arbitrary key-value pairs in their `.yaml` file. This data is then passed as a Python `dict` to the `sceptre_handler(sceptre_user_data)` function in Troposphere templates. + +### Syntax + +```yaml +sceptre_user_data: + iam_policy_file_path: /path/to/policy.json +``` + +When compiled, `sceptre_user_data` would be the dictionary `{"iam_policy_file": "/path/to/policy.json"}`. + + +## Hook + +Hooks allows the ability for custom commands to be run when Sceptre actions occur. + +A hook is executed at a particular hook point when Sceptre is run. + +If required, users can create their own `hooks`, as described in the section :ref:`custom_hooks`. + + +### Hook points + +`before_create` or `after_create` - run hook before or after stack creation. + +`before_update` or `after_update` - run hook before or after stack update. + +`before_delete` or `after_delete` - run hook before or after stack deletion. + + +### Syntax + +Hooks are specified in a stack's config file, using the following syntax:: + +```yaml +hooks: + hook_point: + - !command_type command 1 + - !command_type command 2 +``` + + +### Available Hooks + +#### bash + +Executes string as a bash command. + +Syntax: + +```yaml +: + - !bash +``` + +Example: + +```yaml +before_create: + - !bash "echo hello" +``` + + +#### asg\_scheduled\_actions + +Pauses or resumes autoscaling scheduled actions. + +Syntax: + +```yaml +: + - !asg_scheduled_actions "resume" | "suspend" +``` + +Example: + +```yaml +before_update: + - !asg_scheduled_actions "suspend" +``` + + +#### asg\_scaling_processes + +Suspends or resumes autoscaling scaling processes. + +Syntax: + +```yaml +: + - !asg_scaling_processes :: +``` + +Example: + +```yaml +before_update: + - !asg_scaling_processes suspend::ScheduledActions +``` + +More information on suspend and resume processes can be found in the AWS [documentation](http://docs.aws.amazon.com/autoscaling/latest/userguide/as-suspend-resume-processes.html). + + +#### Hook Examples + +A stack's `config.yml` where multiple hooks with multiple commands are specified: + +```yaml +template_path: templates/example.py +parameters: + ExampleParameter: example_value +hooks: + before_create: + - !bash "echo creating..." + after_create: + - !bash "echo created" + - !bash "echo done" + before_update: + - !asg_scheduled_actions suspend + after_update: + - !bash "mkdir example" + - !bash "touch example.txt" + - !asg_scheduled_actions resume +``` + + +## Examples + +```yaml +template_path: templates/example.py +parameters: + param_1: value_1 + param_2: value_2 +``` + +```yaml +template_path: templates/example.json +dependencies: + - vpc +hooks: + before_create: + - !bash "echo creating..." + after_create: + - !bash "echo created" + - !bash "echo done" + after_update: + - !bash "mkdir example" + - !bash "touch example.txt" +parameters: + param_1: !stack_output stack_name::output_name + param_2: !stack_output_external full_stack_name::output_name + param_3: !environment_variable VALUE_3 + param_4: + {{ var.value4 }} + param_5: + {{ environment_path.3 }} + param_6: + {{ environment_variable.VALUE_6 }} +sceptre_user_data: + thing_1: value_1 + thing_2: !file_contents path/to/file.txt +stack_tags: + tag_1: value_1 + tag_2: value_2 +``` + diff --git a/website/docs/templates.md b/website/docs/templates.md new file mode 100644 index 000000000..e69de29bb diff --git a/website/docs/terminology.md b/website/docs/terminology.md new file mode 100644 index 000000000..a4e300efc --- /dev/null +++ b/website/docs/terminology.md @@ -0,0 +1,33 @@ +--- +layout: docs +--- + +# Terminology + +The following terms will be used though the rest of the Sceptre documentation: + +- Environment Path: A slash ('/') separated list of directory names which details how to move from the top level config directory to an environment directory. For example, with the following directory structure, the environment path would simply be `dev`: + + ```yaml + . + └── config + └── dev + ├── config.yaml + └── vpc.yaml + ``` + + + In the following directory structure, the environment path would be `account-1/dev/eu-west-1`: + + ```yaml + . + └── config + └── account-1 + └── dev + └── eu-west-1 + ├── config.yaml + └── vpc.yaml + ``` + +- Launch: In the context of Sceptre commands, `launch` means to try to `create` a stack. If the stack has already been created, Sceptre tries to `update` the stack. If there are no updates to be performed, `launch` returns a zero exit code. +- Sceptre Directory: The directory which stores the top level config directory. diff --git a/website/guide.md b/website/guide.md new file mode 100644 index 000000000..476342964 --- /dev/null +++ b/website/guide.md @@ -0,0 +1,143 @@ +--- +layout: page +--- + +# Get Started + +## Install + +This tutorial assumes that you have installed Sceptre. Instructions on how to do this are found in the section on [installation]({{ site.url }}/docs/install.html). + +## Directory Structure + +Create the following directory structure in a clean directory named `sceptre-example`: + +``` +. +├── config +│   └── dev +│   ├── config.yaml +│   └── vpc.yaml +└── templates + └── vpc.json +``` + +On Unix systems, this can be done with the following commands: + +``` +$ mkdir config config/dev templates +$ touch config/dev/config.yaml config/dev/vpc.yaml templates/vpc.json +``` + +`vpc.json` will contain a CloudFormation template, `vpc.yaml` will contain config relevant to that template, and `config.yaml` will contain environment config. + + +### vpc.json + +Add the following CloudFormation to `vpc.json`: + +```json +{ + "Parameters": { + "CidrBlock": { + "Type": "String" + } + }, + "Resources": { + "VPC": { + "Type": "AWS::EC2::VPC", + "Properties": { + "CidrBlock": { + "Ref": "CidrBlock" + } + } + } + }, + "Outputs": { + "VpcId": { + "Value": { + "Ref": "VPC" + } + } + } +} +``` + +For more information on CloudFormation, see the AWS documentation on [CloudFormation](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html). + + +### config.yaml + +Add the following config to `config.yaml`: + +```yaml +project_code: sceptre-example +region: eu-west-1 +``` + +Sceptre prefixes stack names with the `project_code`. Resources will be built in the AWS region `region`. + + +### vpc.yaml + +Add the following config to `vpc.yaml`: + +```yaml +template_path: templates/vpc.json +parameters: + CidrBlock: 10.0.0.0/16 +``` + + +`template_path` specifies the relative path to the CloudFormation or Troposphere template to use to launch the stack. + +`parameters` lists the parameters which should be supplied by Sceptre to the CloudFormation or Troposphere template. + + +## Commands + + +### Create stack + +We can create the VPC stack with the following command: + +``` +$ sceptre create-stack dev vpc +``` + +This command must be run from the `sceptre-examples` directory. + + +### Meta commands + +We can find out information about our running stack: + +``` +$ sceptre describe-env-resources dev +$ sceptre describe-stack-resources dev vpc +$ sceptre describe-stack-outputs dev vpc +``` + + +### Update stack + +If the stack's config or template is changed in vpc.yaml, the stack can be updated with: + +``` +$ sceptre update-stack dev vpc +``` + + +### Delete stack + +Delete the stack: + +``` +$ sceptre delete-stack dev vpc +``` + + +## Next Steps + +Further details can be found in the full [documentation]({{ site.url }}/docs). + diff --git a/website/index.md b/website/index.md new file mode 100644 index 000000000..dba777ad6 --- /dev/null +++ b/website/index.md @@ -0,0 +1,9 @@ +--- +layout: home +--- + +# Sceptre + +Automate cloud deployments + +[Find out more >](/intro.html) diff --git a/website/intro.md b/website/intro.md new file mode 100644 index 000000000..46507f3d2 --- /dev/null +++ b/website/intro.md @@ -0,0 +1,31 @@ +--- +layout: page +--- + +# Introduction + +## About + +Sceptre is a tool to drive Cloudformation. Sceptre manages the creating, updating and deletion of stacks, and provides meta commands to allow users to get information about their stacks. Sceptre is unopinionated, enterprise ready and designed to be run as part of CI/CD pipelines. Sceptre is accessible as a CLI tool, or as a Python module. + + +## Motivation + +CloudFormation lacks a robust tool to deploy and manage stacks. The AWS CLI and Boto3 both provide some functionality, but neither offer the chaining of one stack's outputs to another's parameters or easy support for working with role assumes or in multiple accounts, all of which are common tasks when deploying infrastructure. + +Sceptre was developed to produce a single tool which can be used to deploy any and all CloudFormation. It is intended to replace boilerplate scripts currently used. + + +## Overview + +Sceptre is used by defining CloudFormation or Troposphere templates, and corresponding YAML config files. The config files include which account and region to use, and the parameters to be supplied to the templates. + +For a tutorial on using Sceptre, see [Get Started](/guide), or find out more information about Sceptre below. + + +## Code + +Sceptre's source code can be found on [Github](https://github.com/cloudreach/sceptre/). + +Bugs and feature requests should be raised via our [Issues](https://github.com/cloudreach/sceptre/issues) page. +