Stacks

This page describes properties available in stack configuration files.

Here are the available properties:

accountIds

List of allowed AWS accounts where a stack can be deployed.

Sincev1.0.0
Type
string
string[]
Requiredyes
Defaultundefined
Where to defineCan be defined both in stack and stack group configurations
Inheritedyes - the value is inherited from the parent stack group
Overridingreplace - the value completely replaces the inherited value
Requirements
  • Must be valid AWS account ids

Examples

A single AWS account id:

accountIds: "123456789012"

A list of AWS account ids:

accountIds:
- "876272828282"
- "763273627326"

capabilities

Capabilities for the stack.

Sincev1.0.0
Type
string
string[]
Requiredno
Default[CAPABILITY_IAM, CAPABILITY_NAMED_IAM, CAPABILITY_AUTO_EXPAND]
Where to defineCan be defined both in stack and stack group configurations
Inheritedyes - the value is inherited from the parent stack group
Overridingreplace - the value completely replaces the inherited value
Requirements
  • Allowed values: CAPABILITY_IAM, CAPABILITY_NAMED_IAM, CAPABILITY_AUTO_EXPAND

Examples

A single capability:

capabilities: CAPABILITY_IAM

A list of capabilities:

capabilities:
- CAPABILITY_IAM
- CAPABILITY_NAMED_IAM

Disable all capabilities:

capabilities: []

commandRole

An IAM role used to execute commands for the stack. Determines the target AWS account.

Sincev1.0.0
Type
string
Requiredno
Defaultundefined
Where to defineCan be defined both in stack and stack group configurations
Inheritedyes - the value is inherited from the parent stack group
Overridingreplace - the value completely replaces the inherited value
Requirements
  • Must be a valid IAM role ARN

Examples

commandRole: arn:aws:iam::123456789012:role/deployer-role

See also

data

Arbitrary data that can be referred in .hbs CloudFormation template files.

Sincev1.0.0
Type
object
Requiredno
Defaultundefined
Where to defineCan be defined both in stack and stack group configurations
Inheritedyes - the value is inherited from the parent stack group
Overridingmerge - the value is merged with the inherited value
Requirements
  • The value of the object keys must be of type string

Examples

Say, we have the following custom data in a stack config:

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

Then, in an .hbs CloudFormation template file, we can refer to variables it defines like so:

Resources:
Bucket:
Type: AWS::S3::Bucket
Properties:
Tags:
- Key: Environment
Value: {{ stack.data.environment.name }}
- Key: Code
Value: {{ stack.data.environment.code }}

See also

depends

A single stack path or a list of stack paths to stacks within the same Takomo project that the current stack depends on.

Sincev1.0.0
Type
string
string[]
Requiredno
Defaultundefined
Where to defineCan be defined only in stack configurations
Inheritedno - the value is not inherited from the parent stack group
Overridingnot applicable - the value is not inherited from the parent stack
Requirements
  • Must be a valid stack path

Examples

A single dependency:

depends: /dev/vpc.yml

A single dependency with region:

depends: /dev/vpc.yml/eu-west-1

Multiple dependencies:

depends:
- /dev/vpc.yml
- /dev/security-groups.yml

hooks

A list of hooks to be executed at different stages of deploy and undeploy commands. Hooks are executed in the order they are defined. If a hook fails, the stack operation is cancelled and deemed as failure.

Sincev1.0.0
Type
Requiredno
Defaultundefined
Where to defineCan be defined both in stack and stack group configurations
Inheritedyes - the value is inherited from the parent stack group
Overridingmerge - the value is merged with the inherited value
Requirements
none

Hooks defined in a stack or stack group configuration are appended to the list of hooks inherited from the parent stack group configuration.

Hook Configuration Object

Configuration for each hook is given as an object with the properties described below. In addition to these standard properties, different hook types can have properties of their own.

KeyRequiredTypeDescription
nameyesstringName of the hook
typeyesstringType of the hook
operationnostring
string[]
Stack operations during which the hook is executed. Accepts a single value or a list of values. If no operation is defined, the hook is executed on all operations.

Allowed values:
  • create - A new stack is created
  • update - An existing stack is updated
  • delete - An existing stack is deleted
stagenostring
string[]
Stack operation stages during which the hook is executed. Accepts a single value or a list of values. If no stage is defined, the hook is executed on all stages.

Allowed values:
  • before - Hook is executed before the stack operation
  • after - Hook is executed after the stack operation
statusnostring
string[]
Stack operation statuses during which the hook is executed. Accepts a single value or a list of values. If no status is defined, the hook is executed on all statuses.

Allowed values:
  • success - Stack operation was successful
  • failed - Stack operation failed
  • cancelled - Stack operation was cancelled
  • skipped - Stack operation was skipped
Has effect only when the stage is after.

Examples

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

hooks:
- name: executed-after-successful-create
type: cmd
operation: create
stage: after
status: success
command: echo 'success'

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

hooks:
- name: my-hook
type: cmd
operation:
- create
- update
stage: after
command: echo 'hello'

See also

ignore

Ignore a stack group or a stack. If a stack group is ignored, all its stacks and children are also ignored. If a stack is ignored, its configuration is not loaded, effectively making it non-existing. Ignored stacks can't be deployed or referenced elsewhere in configuration, e.g. ignored stack can't be a dependency for other stacks.

Sincev1.0.0
Type
boolean
Requiredno
Defaultfalse
Where to defineCan be defined both in stack and stack group configurations
Inheritedyes - the value is inherited from the parent stack group
Overridingreplace - the value completely replaces the inherited value
Requirements
none

If a stack group sets ignore to true, it's stacks or child stack groups won't be parsed and thus can't set ignore to false.

Examples

ignore: true

name

Name of the stack.

Sincev1.0.0
Type
string
Requiredno
Defaultcomputed (see below)
Where to defineCan be defined only in stack configurations
Inheritedno - the value is not inherited from the parent stack group
Overridingnot applicable - the value is not inherited from the parent stack
Requirements
  • Must match regex ^[a-zA-Z0-9][-a-zA-Z0-9]*$
  • Minimum length 1
  • Maximum length 128

Default value

If the name is not given, it is generated from the stack path and the project as follows:

  1. Remove the starting slash
  2. Remove the .yml file extension and everything after it
  3. Replace remaining slashes with hyphens
  4. If the project is defined, prepend it with a hyphen

For example, if the stack's project is example and stack path is /dev/vpc.yml/eu-west-1, then the generated name is example-dev-vpc.

Changing the stack name

Changing the name will cause Takomo to look for the stack with the new name. As Takomo does not store the state anywhere, it can't know that the stack still exists with the old name.

If you need to change the name of an existing stack, you should first decide if you need to remove the old stack before or after changing the name in stack configuration file. Then use stacks undeploy command to remove the old stack.

Examples

name: rds-database

parameters

Stack input parameters.

Sincev1.0.0
Type
Requiredno
Defaultundefined
Where to defineCan be defined only in stack configurations
Inheritedno - the value is not inherited from the parent stack group
Overridingnot applicable - the value is not inherited from the parent stack
Requirements
  • Parameter name must be of type string
  • Parameter name must match regex ^[a-zA-Z0-9]*$

Parameters Configuration Object

Parameters configuration is an object where keys are names for the parameters and values are configuration for the corresponding parameters. A parameter value can be a string, number, boolean, object or an array of the aforementioned types.

KeyRequiredTypeDescription
{parameter name}yesstring
number
boolean
Parameter Configuration Object
any[]
Value of the parameter whose name is given as the key. An array should be used when the template parameter is accepts a list of values.

Parameter Configuration Object

Parameter value must be given as object when the parameter value is resolved using a parameter resolver. The configuration object has the properties described below.

KeyRequiredTypeDescription
resolveryesstringName of parameter resolver used to resolve the value for the parameter
confidentialnobooleanBoolean determining if the parameter value should be concealed from the logs. Defaults to false.

In addition to the standard properties documented above, different parameter resolvers can have properties of their own.

Examples

A simple parameter:

parameters:
VpcId: vpc-06e4ab6c6c

A list parameter:

parameters:
CidrBlocs:
- 10.0.0.0/26
- 10.0.0.64/26

A parameter whose value is resolved from a stack output of a stack within the same Takomo project using the output resolver:

parameters:
VpcId:
resolver: stack-output
stack: /vpc.yml
output: vpcId

A parameter whose value is resolved from a stack output of a stack outside the Takomo project using the external output resolver:

parameters:
VpcId:
resolver: external-stack-output
stack: vpc-stack
output: vpcId
region: eu-west-1
commandRole: arn:aws:iam::123456789012:role/deployer

A parameter whose value is resolved from a stack secret of a stack within the same Takomo project using the secret resolver:

parameters:
DatabasePassword:
resolver: secret
stack: /rds.yml
secret: password

See also

project

Name of the Takomo project. If a stack has no explicitly defined name, then the project is included in the stack name generated by Takomo.

Sincev1.0.0
Type
string
Requiredno
Defaultundefined
Where to defineCan be defined both in stack and stack group configurations
Inheritedyes - the value is inherited from the parent stack group
Overridingreplace - the value completely replaces the inherited value
Requirements
  • Must match regex ^[a-zA-Z][a-zA-Z0-9-]*$
Changing the project

If a stack does not have explicitly defined name, changing the project will also change its name. If the name of an existing stack changes, Takomo will not be able to find it anymore and assumes that the stack does not exist.

Examples

project: my-takomo-project

regions

Regions where the stack is created. Accepts a single region or a list of regions.

Regions defined in a stack or a stack group configuration completely override the regions inherited from the parent stack group.

Sincev1.0.0
Type
string
string[]
Requiredyes
Defaultundefined
Where to defineCan be defined both in stack and stack group configurations
Inheritedyes - the value is inherited from the parent stack group
Overridingreplace - the value completely replaces the inherited value
Requirements
  • Must be a valid AWS region
Changing the regions

Adding new regions to an existing stack does not require any special actions.

If an existing stack has only one region and that region is changed, then Takomo will start looking for the stack from the new region and forget that it still exists in the old region.

If one or more regions need to be removed from a stack, use stacks undeploy command to remove the stack from the regions in question, and then update corresponding stack or stack group configuration files.

Examples

A single region:

regions: eu-west-1

Multiple regions:

regions:
- eu-central-1
- eu-north-1
- us-east-1

secrets

Confidential information, such as passwords and access tokens, that can be used in the stack parameters.

Sincev1.0.0
Type
Requiredno
Defaultundefined
Where to defineCan be defined only in stack configurations
Inheritedno - the value is not inherited from the parent stack group
Overridingnot applicable - the value is not inherited from the parent stack
Requirements
  • Secret name must match regex ^[a-zA-Z0-9][-a-zA-Z0-9]*$
  • Secret name minimum length 1
  • Secret name maximum length 30
  • Secret description maximum length 1024

Secrets Configuration Object

Secrets configuration is an object where keys are names for the secrets and values are configuration for the corresponding secrets.

KeyRequiredTypeDescription
{secret name}yesSecret Configuration ObjectValue of the secret whose name is given as the key

Secret Configuration Object

Properties of a secret configuration object.

KeyRequiredTypeDescription
descriptionyesstringDescription for the secret

Examples

A single secret named 'password':

secrets:
password:
description: Password for RDS database

Multiple secrets:

secrets:
privateKey:
description: Some private key
accessKey:
description: Access key

See also

tags

Tags to be associated with the stack and its resources that support tagging.

Tags defined in the stack configuration are merged with the tags inherited from the stack group, i.e. tags with the same name are overridden but other tags are retained as is.

Sincev1.0.0
Type
Requiredno
Defaultundefined
Where to defineCan be defined both in stack and stack group configurations
Inheritedyes - the value is inherited from the parent stack group
Overridingmerge - the value is merged with the inherited value
Requirements
  • Tag key must be a valid tag key
  • Tag value must be a valid tag value

Tags Configuration Object

Tags configuration is an object where keys are names for the tags and values are values for the corresponding tags.

KeyRequiredTypeDescription
{tag name}yesstringValue of the tag whose name is given as the key

Examples

Multiple tags:

tags:
Name: MySQL database
Environment: dev
CostCenter: 123

template

Path to a CloudFormation template file used to create or update the stack, located in the templates directory.

Sincev1.0.0
Type
string
Requiredno
Defaultcomputed (see below)
Where to defineCan be defined only in stack configurations
Inheritedno - the value is not inherited from the parent stack group
Overridingnot applicable - the value is not inherited from the parent stack
Requirements
  • File extensions must be .json, .yml or .hbs

Default value

By default, the stack configuration file path relative to the stacks directory is used. For example, if the stack configuration file is networks/vpc.yml and the template is not explicitly defined, then the template gets value networks/vpc.yml.

Examples

Use template rds.yml:

template: rds.yml

Use template from networking subdir:

template: networking/vpc.yml

templateBucket

An S3 bucket where the stack's CloudFormation template is uploaded prior the deployment. Using a template bucket allows bigger CloudFormation template files (max size of 460,800 bytes instead of the default of 51,200 bytes). The template bucket is managed and accessed using the same credentials as are used for the current stack.

Sincev1.0.0
Type
Requiredno
Defaultundefined
Where to defineCan be defined both in stack and stack group configurations
Inheritedyes - the value is inherited from the parent stack group
Overridingreplace - the value completely replaces the inherited value
Requirements
  • Name must be a valid S3 bucket name
  • Key prefix must be a valid S3 object key prefix

Template Bucket Configuration Object

Template bucket configuration is an object with following keys:

KeyRequiredTypeDescription
nameyesstringName of the S3 bucket
keyPrefixnostringKey prefix where templates are uploaded inside the bucket

Examples

Provide only the bucket name:

templateBucket:
name: my-template-files

With key prefix:

templateBucket:
name: my-template-files
keyPrefix: my-templates/project-x/

timeout

Time in seconds the stack create or update operation can take before it is considered as failure and rolled back. Delete operations do not support timeout. Use 0 to disable timeout.

Sincev1.0.0
Type
number
Requiredno
Defaultundefined
Where to defineCan be defined both in stack and stack group configurations
Inheritedyes - the value is inherited from the parent stack group
Overridingreplace - the value completely replaces the inherited value
Requirements
  • Timeout must be an integer greater or equal to 0

Timeout Configuration Object

Use object configuration to provide separate timeouts for stack create and update operations. You can provide the timeout for the both, or just one of the operations.

KeyRequiredTypeDescription
createnonumberTimeout in seconds for create stack operations
updatenonumberTimeout in seconds for update stack operations

Examples

Timeout of 180 seconds for both create and update:

timeout: 180

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

timeout:
create: 300

Separate timeouts for create and update:

timeout:
create: 300
update: 120

terminationProtection

Enable stack termination protection.

Sincev2.7.0
Type
boolean
Requiredno
Defaultfalse
Where to defineCan be defined both in stack and stack group configurations
Inheritedyes - the value is inherited from the parent stack group
Overridingreplace - the value completely replaces the inherited value
Requirements
none

Examples

Enabled stack termination protection.

terminationProtection: true

See Also