System requirements

Sorry to say this, but currently, Takomo doesn't work on Windows, so you need to have Linux or Mac. Takomo is built with Node.js and requires Node.js v14.4.0 or later.

Install as a project dependency

The recommended way to install Takomo is to add it as a development dependency in your project's package.json.

Initialize a new project if needed:

Add Takomo as a development dependency:

Verify installation:

Global installation

You can, of course, use global installation, too.

Verify installation:

This quick start guide will show you how to install and configure Takomo and deploy some basic infrastructure.

AWS credentials

During this tutorial, you'll deploy some stacks, so you need an AWS account where you can safely try things out.

Create an IAM user with administrator permissions.

Next, create access keys for the IAM user and configure them to your ~/.aws/credentials file. Let's name our profile as takomo-quick-start.

Project initialization

We'll start by creating a new directory for your Takomo project:

From now on, we'll call the takomo-quick-start directory as project's root directory.

Change to the root directory and initialize a new NPM project:

Add Takomo as a development dependency:

Initialize a new Takomo project:

From the command output you can see what directories and files were created. You might want to take a look at the files, there isn't much to see =).

Deploy stacks

Now that you have the project initialized, it's time to deploy the stacks. Go ahead and run the following command:

Takomo will present you a deployment plan. Review it and continue when you are ready. Once the deployment completes, you can see a summary of what just happened.

Clean up

You can remove the created stacks by running the following command:

You'll see a plan showing what will happen next. Review the plan and proceed. After the operation you'll see a summary.

Takomo helps you organize, parameterize and deploy CloudFormation stacks across multiple regions and accounts. It works equally well with smaller deployments consisting of just a few stacks and larger multi-account environments.

Takomo was inspired by Cloudreach’s excellent , a CloudFormation wrapper tool built with Python, and created by Hashicorp.

Motivation

is a great tool to manage AWS infrastructure, but as a low-level tool, it's not sufficient alone to manage deployments spanning multiple regions and accounts. Many tools do a good job generating and deploying CloudFormation templates but lack crucial features to handle large-scale deployments.

Each file in the partials directory or its subdirectory can be used as Handlebars partial.

Example

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 }}

You specify the regions where to deploy a stack using the regions property. You can give a single region or a list of regions. Each stack must have at least one region.

Examples

Specifying a single region:

Specifying multiple regions:

When you execute a Takomo command, the AWS credentials present in the current terminal session dictate the target AWS account. We call these credentials the default credentials.

Should you want to target a different account, you can specify an IAM role that Takomo should assume using the default credentials and then use it to execute the commands to the account where the role is bound. We call this role the command role, and you can specify it with the commandRole property, which accepts an IAM role ARN.

Working simultaneously with multiple accounts usually requires switching between many credentials or IAM roles. This poses a real risk of accidentally deploying infrastructure to the wrong account.

You can mitigate this risk with the accountIds property, which lets you define a list of allowed accounts to deploy a stack. It accepts a single account id or a list of account ids.

Examples

By default, the maximum size for a CloudFormation template file is 51,200 bytes. Using larger template files, up to 460,800 bytes, requires that you upload them to an S3 bucket before deployment.

You use the templateBucket property to instruct Takomo to upload template files to a specific S3 bucket before the deployment. The bucket must exist.

The templateBucket property is an object with two properties: name and keyPrefix. The former is required and used to specify the bucket's name, and the latter is optional and specifies the object key prefix under which Takomo uploads the templates files.

Here's a short guide to Handlebars syntax. For more information, consult the official Handlebars .

Variables

You refer to variables like this:

If the variable is an object with properties of its own, you can refer to them like so:

You can exclude stacks from configuration by marking them as obsolete with the obsolete property. Obsolete stacks can be removed with command.

Obsolete stacks can't have dependents that are not obsolete themselves.

Examples

Setting the obsolete

System environment variables are exposed via the env variable.

Example

Here's an example how to print the HOME environment variable:

You can enable termination protection for a stack with the terminationProtection property.

Example

Enabling termination protection:

Questions and assistance

If you need help or have general questions concerning Takomo, feel free to contact us at or start a .

You can define custom properties by using the data property. The properties specified in a stack group configuration are available in its children's and stack's configuration files and stack templates files.

Example

If you specify data in a stack configuration file like this:

data:
  subnets:
    - subnet-ccbbb18ac981dc554e
    - subnet-969b3de3fa0a275d9b
    - subnet-7609598000b229fcb3
  environment:
    name: dev
    code: 123

Then, you can refer to the properties in the stack template file like so:

Where to define

The data property can be defined in stack and stack group configuration files. If specified in a stack group, the stack group's children and stacks inherit the value. Takomo merges the properties defined by stack groups and stacks to the properties they inherit from their parents.

Requirements

The data property must satisfy these requirements:

• Must be an object

You specify stack tags with the tags property. CloudFormation automatically adds the tags to each resource in the stack that supports tagging.

Examples

Setting tags:

tags:
  foo: bar
  code: 123
  backups: true

Where to define

The tags property can be defined in stack and stack group configuration files. If specified in a stack group, the stack group's children and stacks inherit the value. Stack groups and stacks can add new tags and overwrite individual tags they inherited from their parent by specifying a new value with the same key.

Requirements

The tags property must satisfy these requirements:

• Each tag key must be a string

• Each tag value must be a string, a number or a boolean

By default, stacks and stack groups inherit tags from their parent stack group. You can disable this behaviour by setting inheritTags to false.

Examples

Disable inheriting of tags.

inheritTags: false

Where to define

The inheritTags property can be defined in stack and stack group configuration files. Disabling tag inheritance in a stack group configuration affects only to the stack group itself and not stacks and stack groups that belong under it.

Requirements

The inheritTags property must satisfy these requirements:

• Must be a boolean

You can exclude stacks and stack groups from the configuration with the ignore property.

Examples

Setting the ignore property:

ignore: true

Where to define

The ignore property can be defined in stack and stack group configuration files. If specified in a stack group, the stack group's children and stacks inherit the value. If you set a stack group as ignored, its children or stacks can't set the ignore property back to false.

Requirements

The ignore property must satisfy these requirements:

• Must be a boolean

To do anything with Takomo, you need to have valid AWS credentials configured. Under the hood, Takomo uses AWS JavaScript SDK to acquire the credentials. Take a look at the SDK's documentation to learn the ways you can configure credentials.

Using profile

The easiest way to provide credentials when running Takomo on your local computer is to configure a profile in the ~/.aws/credentials file and then either export the profile name in AWS_PROFILE environment variable or pass it on with the --profile command-line option.

Example

Configure a profile in the ~/.aws/credentials file:

You can then provide the profile in an environment variable:

Or, you can use the --profile command line option:

Assuming roles

If you have an IAM user in one account that you use to assume roles from the same or other accounts, you can configure the access keys for the user in the credentials file and then create separate profiles for each of the roles.

Example

Configure a profile and roles in the credentials file.

Now, when you run a command with account-a-admin profile, AWS SDK uses the access keys you have configured for the manager profile to assume the arn:aws:iam::123456789012:role/admin IAM role referenced by the account-a-admin profile.

Assuming roles that require MFA

You can specify in an IAM role's trust policy that the user must provide an MFA token to assume it. Then, to assume the role, you need to configure your IAM user's MFA device with mfa_serial property in the role's profile like so:

When you run a command, Takomo will ask you the MFA code.

You specify stack capabilities with the capabilities property.

Examples

A single capability:

A list of capabilities

Disable all capabilities:

Default value

By default, all capabilities are enabled.

Where to define

The capabilities property can be defined in stack and stack group configuration files. If specified in a stack group, the stack group's children and stacks inherit the value. Stack groups and stacks can override the value they have inherited from their parent.

Requirements

The capabilities property must satisfy these requirements:

• Must be a string or a list of strings

• Allowed values are:

  • CAPABILITY_IAM

Each CloudFormation stack must have a name that is unique within the stack's region. Takomo uses stack names to match stacks found from the local configuration with the target accounts' stacks.

You can give a name for a stack using the name property.

Example

Specifying a name:

Default value

If you omit the name, Takomo will generate the name using the following logic:

1. Take the stack path and remove the leading forward slash

2. Remove the region specifier from the end of the stack path

3. Replace the remaining forward slashes with hyphens

For example, if your stack's path is /dev/eu-west-1/vpc.yml/eu-west-1, its generated name will be dev-eu-west-1-vpc.

Where to define

The name property can be defined only in stack configuration files.

Requirements

The name property must satisfy these requirements:

• Must be a string

• Must match regex ^[a-zA-Z0-9][-a-zA-Z0-9]*$

• Have a minimum length of 1

Renaming stacks

You can't rename stacks. If you change the name of an existing stack, Takomo will use the new name to find a corresponding stack from the target account. As Takomo does not keep track of the stacks it has deployed, it can't know that the stack still exists with the old name.

You can use parameter resolvers to resolve values for stack parameters at deployment time. Takomo has a few built-in parameter resolvers, and you can also implement your own.

In a stack configuration, you choose which resolver to use by providing value to the resolver property. In addition to the resolver property, each resolver may have its own set of additional properties.

Here are the built-in parameter resolvers:

• Stack output resolver

See also

Show stack configuration within the given command path.

Usage

Positional arguments

• command-path

  • Command path to select which stacks to include.

  • Optional, by default, Takomo lists all stacks.

Options

In addition to the , this command has the following options.

• --interactive, -i

  • Choose the command path using autocompleting search.

Examples

Show configuration of all stacks:

Show configuration of stacks within the given command path:

You specify a timeout in seconds for stack create and update operations by using the timeout property. Takomo cancels the operation if it takes longer than what you have specified in the timeout property. You can't set a timeout for the delete operation. Use 0 to disable the timeout.

You set the timeout for both create and update operations by specifying a single integer. You can also set a separate timeout for create and update operations by using an object with create and update properties.

Examples

Timeout of 180 seconds for both create and update:

Timeout of 300 seconds for create and no timeout for update:

Separate timeouts for create and update:

Where to define

The timeout property can be defined in stack and stack group configuration files. If specified in a stack group, the stack group's children and stacks inherit the value. Stack groups and stacks can override the value they have inherited from their parent.

Requirements

The timeout property must satisfy these requirements:

• Must be an integer greater or equal to 0

Here are some tips to help you troubleshoot problems.

Logging level

By setting the logging level to debug or trace, you will see lots of useful information that might help you spot the problem. Logging level is set with --log <level> option which is available for all commands,

Example

This is how you set logging level to trace:

Statistics

To understand how Takomo interacts with AWS APIs you can use --stats option to instruct Takomo to print various statistics after executing a command.

Example

This is how you enable statistics:

You can use custom Joi validation schemas to validate the following parts of stack configuration:

• stack data

• stack tags

Takomo project's directory structure looks like this.

There are two mandatory directories: stacks and templates. The stacks directory will contain all configuration files for your stacks, and the templates directory is where you'll place template files for the stacks.

You can find the purpose of each directory from the table below.

You specify a stack policy with the stackPolicy property. It accepts a string or an object.

Examples

Setting a stack policy as a string:

Setting a stack policy as an object:

The file contents resolver reads a file and uses the file contents as a parameter value.

Properties

Here are the properties of the file contents resolver:

The hook output resolver reads parameter values from hook outputs.

Properties

Here are the properties of the hook output resolver:

Detect drift of stacks within the given command path.

Usage

List stacks within the given command path.

Usage

Positional arguments

Inspect dependencies between stacks within the given command path. Prints the dependency graph in a format which can be rendered using various tools like .

Usage

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 avoid tedious and error-prone manual work, Takomo supports dynamic templating with .

All standard Handlebars features are available, which means you can use loops, if-conditions, partial includes, helpers, and variables to streamline your configuration.

By default, Takomo processes all stack configuration, stack group configuration, and stack template files using Handlebars.

You use the parameter property to define input parameters for a stack. It's an object of key-value pairs where the keys are parameter names, and the values are configuration for the corresponding parameter values.

The value configuration can be a single static value, an object, or a list of the two types mentioned above. You must use the object configuration when the parameter requires additional configuration, or you want Takomo to resolve its value at deployment time.

Simple static parameters

The simplest way to specify the value for a parameter is to hard code the value to the stack configuration file.

Examples

A single static value for a parameter named VpcId:

A list of values for a parameter named CidrBlocks:

Static parameters with object notation

You can provide configuration for static parameters using the object notation which allows you to use additional properties in the configuration. When using the object notation you give the parameter value in value property:

Example

A single static parameter using the object notation:

Immutable parameters

You can mark parameters as immutable if you want to make sure their values are not updated. Many CloudFormation resources have properties that don't support updating after creation, and making them immutable in stack configuration helps prevent failures during deployment.

A parameter can't be marked as immutable if it has NoEcho set to true in the CloudFormation template file. There is no way to find out the current value for NoEcho parameters and therefore Takomo can't detect if their value is about to be changed.

Example

A static immutable value for a parameter named VpcId:

Dynamic parameters

In many cases, it's not wise or even possible to hard code all parameter values. When you need to assign parameter values dynamically at deployment time, you can use parameter resolvers. There are a few built-in parameter resolvers, and you can also implement your own.

You use the resolver property to specify which parameter resolver to use to resolve the value for a parameter.

Below, you can find some examples of built-in parameter resolvers. You can read more about parameter resolvers from .

Examples

If you have two stacks configured within the same Takomo project, you can use the stack-output resolver to read the first stack's output value and use it as a parameter value in the second stack.

If the stacks are not configured within the same Takomo project, you need to use the external-stack-output resolver.

Where to define

The parameters property can be defined only in stack configuration files.

Requirements

The parameters property must satisfy these requirements:

• Parameter name must be a string

• Parameter name must match regex ^[a-zA-Z0-9]*$

See also

The SSM parameter resolver reads parameter values from SSM parameter store. The parameter can be encrypted.

Properties

Here are the properties of the SSM parameter resolver:

Examples

Read value from an SSM parameter /database/password that resides in the same region as the current stack:

Read value from an SSM parameter /database/username that resides in eu-north-1 region:

Read value from an SSM parameter using custom IAM role:

Stack output resolver reads the parameter value from a stack output of another stack configured within the same Takomo project. The source stack automatically becomes the target stack's dependency. Takomo reads the output value using the credentials associated with the source stack.

Properties

Here are the properties of the stack output resolver:

Example

Say, we have two stacks: vpc.yml and security-groups.yml. The former creates a VPC and exposes its id in the stack outputs with a name VpcId, and the latter uses the VPC id to create some security groups.

The directory structure looks like this:

In security-groups.yml stack configuration we use the stack-output resolver to read the value for the VpcId parameter like so:

Hooks can expose values to other hooks by returning a hook output object. Takomo stores the returned value with a hook's name in a mutable variables object that it then passes to the subsequent hooks. Takomo discards the mutable variables object after the stack operation completes, which means the exposed data is not visible to hooks executed in other stacks.

Example

This example shows how you can share data between hooks.

Our file structure looks like this:

.
├─ stacks
│  └─ my-stack.yml
├─ hooks
│  ├─ first.js 
│  └─ second.js
└─ templates
   └─ my-stack.yml

There are two custom hooks located in the hooks dir.

The first hook returns a hook output object that contains a greeting to other hooks in the value property.

The second hook reads the greeting from the input argument.

And this is how you glue everything together in a stack configuration file:

The hooks property defines two hooks, one of each type. Takomo executes the hooks in order they are defined.

You put CloudFormation template files for stacks in the templates directory or its subdirectories.

For each stack, you specify the template file to use with the template property. It accepts a relative file path to the template file in the templates directory.

If you don't specify the template, Takomo looks for a template file using the relative file path to the current stack configuration file from the stacks directory.

Example

Say, we have the following project.

In application.yml stack configuration file you can define the template property like so:

If you would omit the template property, Takomo would fallback to the default behaviour and look for a template file by name application.yml from the templates directory.

Inline template body

You can also inline the template body in a stack configuration file.

Example

Disabling dynamic template

By default, Takomo processes each template file with templating engine. You can turn off this dynamic template processing by providing the template configuration with an object with two properties: filename and dynamic. The former specifies the relative file path to the template file in the templates directory., and the latter is an optional boolean to enable or disable dynamic processing.

Example

Use the object notation to disable dynamic template:

Where to define

The template property can be defined only in stack configuration files.

Requirements

The template property must satisfy these requirements:

• Must be a string or an object

You create a configuration file in the stacks directory for each stack you want to manage with Takomo. Configuration files are in YAML format and should contain the configuration needed to deploy the corresponding stacks.

The command resolver executes a specified shell command and uses the command output as a parameter value.

Properties

Here are the properties of the command resolver:

You can pass variables from command line using --var and --var-file options. Both options can be used multiple times. Variables are exposed via var variable.

Named variables

Use --var

Undeploy (remove) stacks within the given command path.

Takomo also removes stacks that depend on the stacks within the command path, even if they are outside the given command path. Takomo arranges the stacks in removal order by stack dependencies, ensuring that it removes the stacks in the correct order and in parallel when possible.

Usage

The secret parameter resolver reads parameter values from secrets stored in Secrets Manager.

Properties

Here are the properties of the secret parameter resolver:

You can configure project-wide settings in a takomo.yml file that you place in the project root directory.

Required Takomo version

You specify the required Takomo version with the requiredVersion property. It accepts a NPM compatible version range.

Here are the options available for all commands (unless stated otherwise).

• Assume yes to all questions

• Display help

Assume yes to all questions

Pass --yes or -y option to answer yes to all questions.

Display help

Pass --help option to display help. Command specific helps include also the minimum IAM permissions needed to run the command.

Display Takomo version

Pass --version option to print version information.

Enable confidential information logging

By default, environment variables and confidential parameter values are concealed from logs. Override this default by passing --log-confidential-info.

Enable statistics

Use --stats option to print statistics information of the executed command.

Feature flags

You can use --feature <feature>=<boolean value> option to enable and disable certain Takomo features.

Available feature flags:

• deploymentTargetsUndeploy - Set false to disable command

• deploymentTargetsTearDown - Set false to disable command

Load AWS SDK config

Use --load-aws-sdk-config to prefer loading credentials from configuration file over the credentials file. Passing this option will enable loading the profile from ~/.aws/config file.

Load environment variables from a file

Use --env-file <path-to-environment-variables-file> to load environment variables from a file. The loaded variables override existing variables with the same name. This option can be used multiple times.

The environment variables must be defined in a format accepted by , like so:

Set logging level

Use --log <level> option to choose the logging level.

Supported values are:

• trace

• debug

• info (default)

Set project dir

Use --dir <directory> or -d <directory> option to define the directory from where Takomo loads configuration.

Set variables

Pass --var and --var-file options to provide variables that can be used in stack group and stack configuration files and stack templates. Both options can be used multiple times.

For more information, see .

Show command to generate IAM policies

Use --show-generate-iam-policies option to print instructions how to generate IAM policies needed to run the command.

Suppress all but the final output

Use --quiet or -q to suppress all logging and all but the final output. Useful when you want to write the command output to a file.

Use AWS profile

Use --profile <profile> option to choose which AWS profile to use.

For more information, see .

You use the hooks property to specify actions Takomo should execute at different stages of deploy and undeploy commands. The hooks property accepts a list of hook configuration objects. A hook configuration object has the following properties:

• name - Name of the hook

• type - Type of the hook

• operation - Operations during which the hook should be executed

  • Supported operations are:

    • create
• stage - Stages during which the hook should be executed

  • Supported values are:

    • before
• status - Statuses during which the hook should be executed

  • Available on when stage is after

  • Supported values are:

Takomo executes hooks in the order that you have defined them in the configuration files. If one hook fails, the whole stack operation with any remaining hooks is aborted and deemed a failure.

Examples

A cmd hook that is executed after a successful stack creation:

A cmd hook that is executed after all create and update operations:

Where to define

The hooks property can be defined in stack and stack group configuration files. If specified in a stack group, the stack group's children and stacks inherit the value. The hooks defined by stack groups and stacks are appended to the list of hooks they inherit from their parent.

Requirements

The hooks property must satisfy these requirements:

• Must be a list of objects

See also

Undeploy (remove) stacks marked as obsolete within the given command path.

Takomo also removes obsolete stacks that depend on the obsolete stacks within the command path, even if they are outside the given command path. Takomo arranges the stacks in removal order by stack dependencies, ensuring that it removes the stacks in the correct order and in parallel when possible.

Obsolete stacks can't have dependent stacks that are not obsolete themselves.

Usage

Positional arguments

• command-path

  • Command path to select which stacks to prune.

  • Optional, by default, Takomo prunes all stacks.

Options

In addition to the , this command has the following options.

• --ignore-dependencies

  • Ignore stack dependencies. By default, when a stack is removed, its dependants are removed first, and then the stack itself. In some exceptional cases, you might want to remove just one stack and skip its dependants.

  • Bear in mind that this option is supported only when exactly one stack is removed. Ignoring dependants may lead into unexpected results, so you should use this option only in exceptional circumstances.

IAM permissions

These are the minimum IAM permissions required to run this command.

Examples

Prune all stacks:

Prune stacks within the given command path:

Prune only /dev/vpc.yml stack and its dependants:

The region part must be specified if the stack has more than one region and you want to prune it from only one region.

Prune exactly one stack and skip its dependants:

You can use custom Joi validation schemas to validate your configuration.

You provide custom validation schemas by placing plain JavaScript files, with .js file extension, into the schemas directory or its subdirectories. Each file must export a schema provider object. Takomo uses the provider to initialize the actual schema.

Schema provider

Schema provider initializes a Joi validation schema. It has the following properties:

• name

  • Name of the resolver used to refer to the schema from configuration files. It can be either a string or a function that returns a string. The function must not be asynchronous.

  • Required.

You can find more information from the .

Examples

Here are a few examples of custom schemas.

Validation schema for stack tags

You can use the property to specify validation schemas for stack tag configuration. Tag configuration is an object whose keys are tag keys and values are value for the corresponding tags. Therefore you need to use Joi's object schema to validate your tag configurations.

First, you need to implement a schema provider. We name our tag schema as my-tags and specify two required properties: environment and costCenter. In other words, we require that every stack must always have these two tags.

In stack configuration we specify that we want to validate stack tags using our custom schema like so:

It’s a good practice to split the infrastructure into multiple stacks that group related resources together. Naturally, there will be dependencies between the stacks.

For example, one stack creates a VPC with subnets, and another stack creates some resources into those subnets. The stacks need to be created and updated in a certain order to ensure that the dependencies can be satisfied. For example, you need to have the subnets ready before you can create other resources into them.

You specify the stacks that a stack depends on by using the depends property which accepts a single stack path or a list of stack paths.

Examples

A single dependency:

A single dependency with region:

Multiple dependencies:

Using a relative stack path:

Where to define

The depends property can be defined only in stack configuration files.

Requirements

The depends property must satisfy these requirements:

• Must be a string or a list of strings

• Must contain valid stack paths

Generate IAM policies based on CloudTrail events occurred between the given start and end time, in the given regions, by the given identities.

The external stack output resolver reads the parameter value from a stack output of a stack. The source stack does not have to belong to the same Takomo project as the target stack.

Properties

Here are the properties of the external stack output resolver:

Example

Say, we have two accounts: 123456789012 and 888888888888.

The account 123456789012 has one stack: src-bucket. It is located in the us-east-1 region and exposes the name of an application source bucket in a stack output named SrcBucketName. The 123456789012 account also has a read-only role that the 888888888888 account can assume.

The 888888888888 account has two stacks: assets-bucket and build-infra. The stacks are located in the us-east-1 and eu-west-1 regions, respectively. The assets-bucket stack exposes the name of an assets bucket in a stack output named AssetsBucket.