Permalink
Browse files

Update documentation to reference Jinja2 templates correctly

  • Loading branch information...
1 parent 155bd3e commit 7dbfd82dd01db08486a01ea14d6a1b88f0951542 @theseanything theseanything committed Jul 21, 2017
View
@@ -11,7 +11,7 @@ Sceptre is a tool to drive AWS `CloudFormation <https://aws.amazon.com/cloudform
Features:
- Code reusability by separating a stack's template and its configuration
-- Support for templates written in JSON, YAML or Python DSLs such as Troposphere
+- 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
View
@@ -16,7 +16,7 @@ Sceptre was developed to produce a single tool which can be used to deploy any a
## 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.
+Sceptre is used by defining CloudFormation, Jinja2 or Python 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]({{ site.baseurl }}/docs/get_started.html), or find out more information about Sceptre below.
View
@@ -27,14 +27,13 @@ $ sceptre --var "region=<your region name>" COMMAND
Parameters are the standard way of passing environment-specific configuration to a CloudFormation template. They offer:
- Native support from CloudFormation
-- Availability to templates written in both Troposphere and pure CloudFormation
- A high degree of customisability, as described in the [AWS documentation](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/parameters-section-structure.html)
However, parameters suffer from the following limitation:
- They cannot alter the template based on the parameter value
-Sceptre user data was added to fix this limitation. It is configuration that is passed directly to a Troposphere template, and so can be used to change the template based on the configuration item's value.
+Sceptre user data was added to fix this limitation. It is configuration that is passed directly to a template, and so can be used to change the template based on the configuration item's value.
For example, if the Sceptre user data item `number_of_azs` is passed to a subnet tier template, the value could be used to create different numbers of subnets. This cannot be done with native parameters.
View
@@ -89,9 +89,9 @@ parameters:
```
-`template_path` specifies the relative path to the CloudFormation or Troposphere template to use to launch the stack.
+`template_path` specifies the relative path to the CloudFormation, Python or Jinja2 template to use to launch the stack.
-`parameters` lists the parameters which should be supplied by Sceptre to the CloudFormation or Troposphere template.
+`parameters` lists the parameters which should be supplied by Sceptre to the template.
## Commands
@@ -140,4 +140,3 @@ $ sceptre delete-stack dev vpc
## Next Steps
Further details can be found in the full [documentation]({{ site.url }}{{ site.baseurl }}/docs).
-
View
@@ -35,7 +35,7 @@ A list of arbitrary shell or python commands or scripts to run. Find out more in
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 with <a href="{{ site.baseurl }}/docs/environment_config.html#var">User Variables</a>, or set via an environment variable with the <a href="#environment_variable">environment variable resolver</a>.
</div>
-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]({{ site.baseurl }}/docs/resolvers.html) section.
+A dictionary of key-value pairs to be supplied to a 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]({{ site.baseurl }}/docs/resolvers.html) 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.
@@ -85,7 +85,7 @@ If a user tries to run one of these commands on a protected stack, Sceptre will
### sceptre\_user\_data
-A dictionary of arbitrary key-value pairs to be passed to the `sceptre_handler(sceptre_user_data)` function in Troposphere templates.
+Represents data to be passed to the `sceptre_handler(sceptre_user_data)` function in Python templates or accessible under `sceptre_user_data` variable key within Jinja2 templates.
### stack_name
@@ -114,7 +114,7 @@ The ARN of a [CloudFormation Service Role](http://docs.aws.amazon.com/AWSCloudFo
### 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.
+The path to the CloudFormation, Jinja2 or Python template to build the stack from. The path can either be absolute or relative to the Sceptre Directory. Sceptre treats the template as CloudFormation, Jinja2 or Python depending on the template's file extension. Note that the template filename may be different from the stack config filename.
## Cascading Config
@@ -137,9 +137,9 @@ It is possible to replace values in stack config files with environment variable
## 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.
+Python or Jinja templates can contain data which should be parameterised, but can't be parameterised using CloudFormation parameters. An example of this is if a Python template which creates an IAM Role reads in the policy from a JSON file. The file path must be hardcoded in the Python template.
-Sceptre user data allows users to store arbitrary key-value pairs in their `<stack-name>.yaml` file. This data is then passed as a Python `dict` to the `sceptre_handler(sceptre_user_data)` function in Troposphere templates.
+Sceptre user data allows users to store arbitrary key-value pairs in their `<stack-name>.yaml` file. This data is then passed as a Python `dict` to the `sceptre_handler(sceptre_user_data)` function in Python templates.
Syntax:
@@ -191,4 +191,3 @@ stack_tags:
tag_2: value_2
{% endraw %}
```
-
View
@@ -4,7 +4,7 @@ layout: docs
# Templates
-Sceptre uses CloudFormation or Troposphere templates to launch AWS Stacks. Conventionally, templates are stored in a directory named templates, in the same directory as the config directory:
+Sceptre uses CloudFormation templates to launch AWS Stacks. Conventionally, templates are stored in a directory named templates, in the same directory as the config directory:
```
.
@@ -16,17 +16,22 @@ Sceptre uses CloudFormation or Troposphere templates to launch AWS Stacks. Conve
└── vpc.py
```
-Note that as a path to the template is supplied in a stack's Stack Config file, templates may be stored at any arbitrary location on disk.
+Note that as a path to the template is supplied in a Stack Config file, templates may be stored at any arbitrary location on disk.
## CloudFormation
-Templates with `.json` or `.yaml` extensions are treated as CloudFormation templates. They are read in and launched without modification.
+Templates with `.json` or `.yaml` extensions are treated as CloudFormation templates. They are read in and used without modification.
-## Troposphere
+## Jinja
-Templates with a `.py` extension are treated as Troposphere templates. They should implement a function named `sceptre_handler(sceptre_user_data)` which returns the CloudFormation template as a `string`. Sceptre User Data is passed to this function as an argument. If Sceptre User Data is not defined in the Stack Config file, Sceptre passes an empty `dict`.
+Templates with `.j2` extensions are treated as Jinja2 templates. Sceptre User Data is accessible within templates as `sceptre_user_data`. For example `{{ sceptre_user_data.some_variable }}`.
+
+
+## Python
+
+Templates with a `.py` extension are treated as Python templates. They should implement a function named `sceptre_handler(sceptre_user_data)` which returns the CloudFormation template as a `string`. Sceptre User Data is passed to this function as an argument. If Sceptre User Data is not defined in the Stack Config file, Sceptre passes an empty `dict`.
### Example
@@ -51,6 +51,6 @@ Feature: Generate template
Then a "<exception>" is raised
Examples: Render Errors
- | filename | exception |
+ | filename | exception |
| jinja/invalid_template_missing_key.j2 | UndefinedError |
| jinja/invalid_template_missing_attr.j2 | UndefinedError |

0 comments on commit 7dbfd82

Please sign in to comment.