Template Handlers¶
Template handlers can be used to resolve a template
config block to a CloudFormation template. This can be used to
fetch templates from S3, for example. Users can create their own template handlers to easily add support for other
template loading mechanisms. See Custom Template Handlers for more information.
Warning
The template_path
key is deprecated in favor of the template
key.
Available Template Handlers¶
file¶
Loads a template from the local file system. This handler supports templates with .json, .yaml, .template, .j2
and .py extensions. This is the default template handler type, specifying the file
type is optional.
For backwards compatability, when a template_path
key is specified in the Stack config, it is wired to
use the file
template handler.
Syntax:
template:
type: file
path: <path>
Example:
template:
path: storage/bucket.yaml
Note
The path
property can contain an absolute or relative path to the template file.
This handler assumes a relative path to be from sceptre_project_dir/templates
s3¶
Downloads a template from an S3 bucket. The bucket is accessed with the same credentials that is used to run sceptre. This handler supports templates with .json, .yaml, .template, .j2 and .py extensions.
Syntax:
template:
type: s3
path: <bucket>/<key>
Example:
template:
type: s3
path: infra-templates/v1/storage/bucket.yaml
http¶
Downloads a template from a url on the web. By default, this handler will attempt to download templates with 5 retries and a download timeout of 5 seconds. The default retry and timeout options can be overridden by setting the http_template_handler key in the stack group config file.
Syntax:
template:
type: http
url: <url>
Example:
template:
type: http
url: https://raw.githubusercontent.com/acme/infra-templates/v1/storage/bucket.yaml
Custom Template Handlers¶
If you need to load templates from a different source, you can write your own template handler.
A template handler is a Python class which inherits from abstract base class TemplateHandler
found in the
sceptre.template_handlers
module.
To have Sceptre validate that the template
block specified in the Stack config is correct, template handlers
should provide a JSON schema with the required and optional properties. The schema()
method should be
implemented and return a Python dictionary with the schema. For examples of JSON schemas in Python, please see
the documentation of the jsonschema library.
Template handlers get access to the template
block parameters, sceptre_user_data
and connection_manager
.
These properties are available on self
. Using connection_manager
, template handlers can call AWS endpoints
to perform actions or fetch templates. These correspond to the AWS Python SDK (see Boto3). For example:
self.connection_manager.call(
service="s3",
command="get_object",
kwargs={
"Bucket": bucket,
"Key": key
}
)
Sceptre uses the sceptre.template_handlers
entry point to load template handlers. They can be written anywhere and
are installed as Python packages.
Example¶
The following Python module template can be copied and used:
custom_template_handler
├── custom_template_handler.py
└── setup.py
The following Python module template can be copied and used:
custom_template_handler.py¶
from sceptre.template_handlers import TemplateHandler
class CustomTemplateHandler(TemplateHandler):
"""
The following instance attributes are inherited from the parent class TemplateHandler.
Parameters
----------
name: str
The name of the template. Corresponds to the name of the Stack this template belongs to.
handler_config: dict
Configuration of the template handler. All properties except for `type` are available.
sceptre_user_data: dict
Sceptre user data defined in the Stack config
connection_manager: sceptre.connection_manager.ConnectionManager
Connection manager that can be used to call AWS APIs
"""
def __init__(self, *args, **kwargs):
super(CustomTemplateHandler, self).__init__(*args, **kwargs)
def schema(self):
"""
Return a JSON schema of the properties that this template handler requires.
For help filling this, see https://github.com/Julian/jsonschema
"""
return {
"type": "object",
"properties": {},
"required": []
}
def handle(self):
"""
`handle` should return a CloudFormation template string or bytes. If the return
value is a byte array, UTF-8 encoding is assumed.
To use instance attribute self.<attribute_name>. See the class-level docs for a
list of attributes that are inherited.
Returns
-------
str|bytes
CloudFormation template
"""
return ""
setup.py¶
from setuptools import setup
setup(
name='<custom_resolver_package_name>',
py_modules=['<custom_resolver_module_name>'],
entry_points={
'sceptre.template_handlers': [
'<custom_template_handler_type> = <custom_template_handler_module_name>:CustomTemplateHandler',
],
}
)
Then install using python setup.py install
or pip install .
commands.
This template handler can be used in a Stack config file with the following syntax. Any properties you put in the
template
block will be passed to the template handler in the self.handler_config
dictionary.
template:
type: <custom_template_handler_type>
<property>: <value>
Calling AWS services in your custom template_handler¶
For details on calling AWS services or invoking AWS-related third party tools in your template handler, see How do I call AWS services or use AWS-based tools in my custom hook/resolver/template handler?