# Variables and Templating

Sometimes static configuration files and templates are not enough to solve the real-life problems we might face. To help overcome those trickier challenges, and to avoid tedious and error-prone repeating of configuration, Takomo supports Handlebars templating. All standard Handlebars features are available, so you can use loops, if-conditions, partial includes, helpers, variables etc. to streamline your configuration.

Stack and stack group configuration files are always processed as dynamic Handlebars templates. To enable the same dynamic processing of CloudFormation template files in the templates directory, the .hbs file extension is needed.

# Partials

Each file in the partials directory or its sub directories can be used as a Handlebars partial.

# Examples

If the partials directory contains a file named my-partial.hbs, you can include it as a partial in a configuration file like so:

{{> my-partial.hbs }}

# Helpers

Custom Handlebars helpers can be registered by adding .js files to the helpers directory. These files must be valid JavaScript files and export two properties: name and fn. The former is the name for the helper, and the latter is the actual helper function.

# Examples

If the helpers directory contains a file named to-upper-case.js with following contents:

module.exports = {
  name: "to-upper-case",
  fn: (str) => str.toUpperCase(),
};

Then, it could be used in a template file like so:

Resources:
  User:
    Type: AWS::IAM:::User
    Properties:
      UserName: { { to-upper-case 'Roger Moore' } }

And the final template would look like this:

Resources:
  User:
    Type: AWS::IAM:::User
    Properties:
      UserName: ROGER MOORE

# Command Variables

Command variables are exposed via the var variable and are passed from the command line using --var and --var-file options. The former is used to pass a single named variable, and the latter to load variables from a file. If the file extension is .json or .yml, the file is first parsed into an object which is then stored to a variable. If the variable file's extension is something else, the file contents are just read into a variable. Variables from files are loaded first in the order they are defined, and then the other variables also in the definition order. Complex variables are merged recursively.

# Examples

Provide a single variable named myVariable with value hello:

--var myVariable=hello

Read contents of commit.txt file to a variable named commitHash:

--var-file commitHash=commit.txt

Read and deserialize contents of /home/variables.yml file into a variable named myVariable

--var-file myVariable=/home/variables.yml

The variable name can be omitted for .yml and .json files as long as the file content can be deserialized to an object. The deserialized object is then stored to the top-level of variables.

--var-file properties.json

# Environment Variables

All system environment variables are exposed via the env variable.

# Examples

Printing the HOME environment variable somewhere in the configuration:

Home dir is {{ env.HOME }}

# Variables in Stack Group Configuration Files

The following variables are available in stack group configuration files.

  • var - Command variables, e.g. from command line options
  • env - Environment variables
  • context - Current context variables
    • projectDir - Current project directory

# Variables in Stack Configuration Files

The following variables are available in stack configuration files.

  • var - Command variables, e.g. from command line options
  • env - Environment variables
  • context - Current context variables
    • projectDir - Current project directory
  • stackGroup - The stack group where the stack belongs to
    • path - The stack group path
    • name - The stack name
    • project - The project property
    • regions - The regions property
    • commandRole - The commandRole property
    • capabilities - The capabilities property
    • isRoot - Is the stack group the root
    • templateBucket - The templateBucket property
      • name - Template bucket name
      • keyPrefix - Template bucket key prefix
    • timeout - The timeout property
      • create - Timeout in minutes for create stack operations
      • update - Timeout in minutes for update stack operations
    • data - The data property
    • tags - The tags property
    • accountIds - The accountIds property

# Variables in CloudFormation Template Files

The following variables are available in CloudFormation template files with .hbs file extension.

  • var - Command variables, e.g. from command line options
  • env - Environment variables
  • context - Current context variables
    • projectDir - Current project directory
  • hooks - Hook return values
  • stack - Current stack
    • path - The stack path
    • project - The project property
    • name - The name property
    • region - The region property
    • commandRole - The commandRole property
    • template - The template property
    • templateBucket - The templateBucket property
      • name - Template bucket name
      • keyPrefix - Template bucket key prefix
    • timeout - The timeout property
      • create - Timeout in minutes for create stack operations
      • update - Timeout in minutes for update stack operations
    • data - The data property
    • depends - The depends property
    • tags - The tags property
Last Updated: 5/18/2020, 8:29:17 PM