StackGroup Config

StackGroup config stores information related to the StackGroup, such as a particular profile to use, the name of the S3 bucket in which to store templates, and the target region in which to build resources. StackGroup config is stored in various files around the directory structure, all with the name config.yaml.

Structure

An StackGroup config file is a yaml object of key-value pairs configuring Sceptre. The available keys are listed below.

Sceptre will only check for and uses the above keys in StackGroup config files and are directly accessible from Stack(). Any other keys added by the user are made available via stack_group_confg attribute on Stack().

profile

The name of the profile as defined in ~/.aws/config and ~/.aws/credentials. Use the aws configure –profile <profile_id> command form the AWS CLI to add profiles to these files.

Reference: AWS_CLI_Configure

project_code

A string 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.

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>/<region>/<stack_group>/<stack_name>-<timestamp>.<extension>

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.

j2_environment

A dictionary that is combined with the default jinja2 environment. It’s converted to keyword arguments then passed to [jinja2.Environment](https://jinja.palletsprojects.com/en/2.11.x/api/#jinja2.Environment). This will impact Templating of stacks by modifying the behavior of jinja.

j2_environment:
   extensions:
      - jinja2.ext.i18n
      - jinja2.ext.do
   lstrip_blocks: True
   trim_blocks: True
   newline_sequence: \n

http_template_handler

Options passed to the http template handler.

  • retries - The number of retry attempts (default is 5)

  • timeout - The timeout for the session in seconds (default is 5)

http_template_handler:
   retries: 10
   timeout: 20

require_version

A PEP 440 compatible version specifier. If the Sceptre version does not fall within the given version requirement it will abort.

Cascading Config

Using Sceptre, config files are 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 that define configuration settings with conflicting keys, the child configuration file will take precedence.

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.

For example, if you wanted the dev StackGroup 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 StackGroup.

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 command_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:

profile: {{ var.profile }}
region: eu-west-1

This item can be set using either a command line flag:

sceptre --var "profile=<your profile>" <COMMAND>

Or from a YAML variable file:

sceptre --var-file=variables.yaml <COMMAND>

where variables.yaml contains:

profile: <your profile>

Both the --var and --var-file flags can be used multiple times. If multiple --var-file options are supplied, the variables from these files will be merged, with a higher precedence given to options specified later in the command. Values supplied using --var take the highest precedence and will overwrite any value defined in the variable files.

For example if we have the following variable files:

# default.yaml
region: eu-west-1
profile: dev
project_code: api

# prod.yaml
profile: prod

The following sceptre command:

sceptre --var-file=default.yaml --var-file=prod.yaml --var region=us-east-1 <COMMAND>

Will result in the following variables being available to the jinja templating:

region: us-east-1
profile: prod
project_code: api

Note that by default, dictionaries are not merged. If the variable appearing in the last variable file is a dictionary, and the same variable is defined in an earlier variable file, that whole dictionary will be overwritten. For example, this would not work as intended:

# default.yaml
tags: {"Env": "dev", "Project": "Widget"}

# prod.yaml
tags: {"Env": "prod"}

Rather, the final dictionary would only contain the Env key.

By using the --merge-vars option, these tags can be merged as intended:

sceptre --merge-vars --var-file=default.yaml --var-file=prod.yaml --var region=us-east-1 <COMMAND>

This will result in the following:

tags: {"Env": "prod", "Project": "Widget"}

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:

profile: {{ environment_variable.PROFILE }}
region: eu-west-1

Where PROFILE is the name of an environment variable.

Command Path

Config item values can be replaced with parts of the command_path

region: {{ command_path.0 }}
profile: default

Where the value is taken from the first part of the command_path from the invoking sceptre command:

sceptre launch eu-west-1/dev/vpc.yaml

Template Defaults

Any templated value can be supplied with a default value with the syntax:

{{ var.value | default("default_value") }}

Examples

profile: profile
project_code: prj
region: eu-west-1
template_bucket_name: sceptre-artifacts
template_key_prefix: my/prefix

profile: {{ var.profile }}
project_code: {{ var.project_code | default("prj") }}
region: {{ command_path.2 }}
template_bucket_name: {{ environment_variable.TEMPLATE_BUCKET_NAME }}