From 8a3eb9403dd6dcc214850f1883dac3dd2ea23e4f Mon Sep 17 00:00:00 2001 From: Khai Do <3697686+zaro0508@users.noreply.github.com> Date: Fri, 15 Oct 2021 20:14:51 -0700 Subject: [PATCH] Document deprecation of the template_path key (#1112) We now have template handlers (PR https://github.com/Sceptre/sceptre/pull/1088) with a new `template` key in sceptre cconfig. This means we can deprecate the `template_path` key. --- docs/_source/docs/faq.rst | 8 ++++++-- docs/_source/docs/get_started.rst | 10 ++++++---- docs/_source/docs/hooks.rst | 12 +++++++++--- docs/_source/docs/resolvers.rst | 8 ++++++-- docs/_source/docs/stack_config.rst | 12 ++++++++++-- docs/_source/docs/template_handlers.rst | 22 +++++++++++----------- docs/_source/docs/templates.rst | 4 +++- 7 files changed, 51 insertions(+), 25 deletions(-) diff --git a/docs/_source/docs/faq.rst b/docs/_source/docs/faq.rst index f240a2650..3dc461f7b 100644 --- a/docs/_source/docs/faq.rst +++ b/docs/_source/docs/faq.rst @@ -102,7 +102,9 @@ CloudFormation Example: .. code-block:: yaml - template_path: generated/lambda-packaged.json + template: + path: generated/lambda-packaged.json + type: file stack_name: cfn-lambda-example hooks: before_launch: @@ -117,7 +119,9 @@ SAM Example: .. code-block:: yaml - template_path: generated/sam-packaged.yaml + template: + path: generated/sam-packaged.yaml + type: file stack_name: sam-example hooks: before_launch: diff --git a/docs/_source/docs/get_started.rst b/docs/_source/docs/get_started.rst index 052fc6bfe..8523cbe84 100644 --- a/docs/_source/docs/get_started.rst +++ b/docs/_source/docs/get_started.rst @@ -106,13 +106,15 @@ Add the following configuration to ``config/dev/vpc.yaml``: .. code-block:: yaml - template_path: vpc.yaml + template: + path: templates/vpc.yaml + type: file parameters: CidrBlock: 10.0.0.0/16 -``template_path`` specifies the relative path to the CloudFormation, Python or +``template`` specifies the relative path to the CloudFormation, Python or Jinja2 template to use to launch the Stack. Sceptre will use the ``templates`` -directory as the root templates directory to base your ``template_path`` from. +directory as the root templates directory to base your ``path`` from. ``parameters`` lists the parameters which are supplied to the template ``vpc.yaml``. @@ -134,7 +136,7 @@ You should now have a Sceptre project that looks a bit like: .. Note: You do not need to make sure the Template and Stack config names - match, since you define the ``template_path`` in your Stack config, but it + match, since you define the ``template`` in your Stack config, but it can be useful to keep track of what is going on. You will also notice that we have two ``config.yaml`` files, one in ``config/`` diff --git a/docs/_source/docs/hooks.rst b/docs/_source/docs/hooks.rst index c00bc9ad0..ac4bb16c1 100644 --- a/docs/_source/docs/hooks.rst +++ b/docs/_source/docs/hooks.rst @@ -91,7 +91,9 @@ specified: .. code-block:: yaml - template_path: templates/example.py + template: + path: templates/example.py + type: file parameters: ExampleParameter: example_value hooks: @@ -196,7 +198,9 @@ This hook can be used in a Stack config file with the following syntax: .. code-block:: yaml - template_path: <...> + template: + path: <...> + type: <...> hooks: before_create: - !custom_hook_command_name # The argument is accessible via self.argument @@ -208,7 +212,9 @@ Assume a Sceptre `copy` hook that calls the `cp command`_: .. code-block:: yaml - template_path: <...> + template: + path: <...> + type: <...> hooks: before_create: - !copy "-r from_dir to_dir" diff --git a/docs/_source/docs/resolvers.rst b/docs/_source/docs/resolvers.rst index 822ad1598..9405156ef 100644 --- a/docs/_source/docs/resolvers.rst +++ b/docs/_source/docs/resolvers.rst @@ -210,7 +210,9 @@ This resolver can be used in a Stack config file with the following syntax: .. code-block:: yaml - template_path: <...> + template: + path: <...> + type: <...> parameters: param1: ! @@ -221,7 +223,9 @@ Resolver arguments can be a simple string or a complex data structure. .. code-block:: yaml - template_path: <...> + template: + path: <...> + type: <...> parameters: Param1: !ssm "/dev/DbPassword" Param2: !ssm {"name": "/dev/DbPassword"} diff --git a/docs/_source/docs/stack_config.rst b/docs/_source/docs/stack_config.rst index 7dc54384f..cbe9e8c78 100644 --- a/docs/_source/docs/stack_config.rst +++ b/docs/_source/docs/stack_config.rst @@ -38,6 +38,10 @@ 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. +.. warning:: + + This key is deprecated in favor of the `template`_ key. + template ~~~~~~~~ @@ -316,14 +320,18 @@ Examples .. code-block:: yaml - template_path: templates/example.py + template: + path: templates/example.py + type: file parameters: param_1: value_1 param_2: value_2 .. code-block:: yaml - template_path: example.yaml + template + path: templates/example.yaml + type: file dependencies: - dev/vpc.yaml hooks: diff --git a/docs/_source/docs/template_handlers.rst b/docs/_source/docs/template_handlers.rst index d7192614c..9845a78a5 100644 --- a/docs/_source/docs/template_handlers.rst +++ b/docs/_source/docs/template_handlers.rst @@ -7,17 +7,10 @@ template loading mechanisms. See `Custom Template Handlers`_ for more informatio When a ``template_path`` property is specified in the Stack config, it is wired into a ``file`` template handler by default. This saves you from having to specify a full ``template`` block if you just want to load a file from disk. -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. -Syntax: +.. warning:: -.. code-block:: yaml - - template: - type: s3 - path: / + The ``template_path`` key is deprecated in favor of the ``template`` key. Available Template Handlers --------------------------- @@ -28,7 +21,7 @@ file Loads a template from disk. Supports JSON, YAML, Jinja2 and Python files. Will be used if the ``template_path`` Stack config property is set, for backwards compatibility reasons. -This is the default template handler type, setting the ``file`` type is option. +This is the default template handler type, setting the ``file`` type is optional. Syntax: @@ -45,10 +38,17 @@ Example: template: path: storage/bucket.yaml +.. note:: + + The path for the ``template_path`` property is relative to the sceptre_dir/templates directory while the path for + this template ``path`` property is relative to the current working directory. + + 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. +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: diff --git a/docs/_source/docs/templates.rst b/docs/_source/docs/templates.rst index 45bb483d5..f1b417c45 100644 --- a/docs/_source/docs/templates.rst +++ b/docs/_source/docs/templates.rst @@ -45,7 +45,9 @@ Stack: .. code-block:: yaml - template_path: dns-extras.j2 + template + path: templates/dns-extras.j2 + type: file dependencies: - prod/route53/domain-zone.yaml parameters: