# Stack Configuration

Stack configuration contains information Takomo uses to manage the actual CloudFormation stacks deployed to AWS accounts. Most of the configuration can be defined in both stack group and stack configuration files, but some properties can be defined only in stack configuration.

For more detailed information, refer to Stack groups and stacks config reference.

# Project

Usually stacks belong to some project that groups related infrastructure resources together. The project property can be used to indicate this. Takomo uses the project value to generate names for the stacks that don't have explicitly given names.

# Examples

Setting the project:

project: MyProject

# See Also

# Name

Name of a CloudFormation stack is defined with the name property in the stack’s configuration file. The name is not required, and if omitted, is generated from the stack path using the following formula:

  1. Remove the leading forward slash and the region specifier
  2. Replace the remaining forward slashes with hyphens
  3. If the project property is defined, prepend it with a hyphen

TIP

In most cases using Takomo generated stack names is a good choice.

The stack name is used to match CloudFormation stacks in the target AWS account with the stacks found from the local configuration. CloudFormation stacks that already exist in an AWS account can’t be renamed. If such a stack is given a new name in the stack configuration file, and the stack is deployed, then Takomo will just create a new stack to the AWS account with the new name and leave the existing stack with the old name as is.

# Examples

Setting the stack name:

name: rds-database

# See Also

# Regions

Regions where a CloudFormation stack is deployed is defined with the regions property. It accepts a single region or a list of regions.

CloudFormation stacks that already exist in an AWS account can’t be relocated to different regions. If such a stack is given a new region in the stack configuration file, and the stack is deployed, then Takomo will just create a new stack to the new region and leave the existing stack in the old region as is.

# Examples

Setting a single region:

regions: eu-west-1

Setting multiple regions:

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

# See Also

# Template File

The CloudFormation template file, that is used to create or update the stack, is defined with the template property in the stack’s configuration file. The template property accepts a relative file path to the template file in the templates directory. If no template is given, the stack path without the region specifier is used.

Both the standard CloudFormation template file formats. i.e. JSON and YAML, are supported, but the file extension must be .yml, .json or .hbs. The last one is used to tell Takomo to treat the template file as a dynamic Handlebars template.

# Examples

Setting the stack template:

template: rds.yml

Setting the stack template located in a subdirectory:

template: networking/vpc.yml

# See Also

# Larger Template Files

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 they are uploaded to an S3 bucket before deployment. This S3 bucket, where the template files should be uploaded, is configured with the templateBucket property which is an object with two properties: name and keyPrefix. The former is required and used to specify the name of the bucket, and the latter is optional and specifies the object key prefix under which the templates should be uploaded.

# Examples

Setting only the template bucket name:

templateBucket:
  name: my-template-files

Setting template bucket name and keyPrefix:

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

# See Also

# Parameters

Input parameters for a CloudFormation stack are given with the parameters property. It is an object of key-value pairs where the keys are parameter names and the values are configuration for the parameter value. The value configuration can be a single static value, an object or a list of the two aforementioned types. The object form is used when the parameter value is resolved at deployment time using a parameter resolver.

# Examples

A static 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

# Tags

Tags for a CloudFormation stack are defined with the tags property which is an object of key-value pairs. The stack tags are also added to all resources of the stack that support tagging.

# Examples

Multiple tags:

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

# See Also

# Capabilities

Some CloudFormation resources, such as IAM resources, require certain capabilities that need to be explicitly acknowledged on stack deployment. By default, all capabilities are included, but it is also possible to provide a more restricted set of capabilities with the capabilities property which accepts a single capability or a list of capabilities.

# Examples

A single capability:

capabilities: CAPABILITY_IAM

A list of capabilities:

capabilities:
  - CAPABILITY_IAM
  - CAPABILITY_NAMED_IAM

Disable all capabilities:

capabilities: []

# See Also

# Dependencies

It is common that there are dependencies between CloudFormation stacks which requires that the stacks must be created, updated and removed in a certain order. Stack dependencies are defined with the depends property which accepts a single command path or a list of command paths. Dependencies that span multiple AWS accounts and regions are allowed, as long as there are no circular dependencies.

# Examples

A single dependency:

depends: /dev/vpc.yml

A single dependency including the region specifier:

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

Multiple dependencies:

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

# See Also

# Timeouts

Takomo supports setting timeouts for stack create and update operations. Timeouts are given in seconds with the timeout property which accepts either a single number or an object with create and update properties. If a single number is given, the same timeout will be set for both the create and update operations. The object form can be used to specify a different timeout value for the operations, or to specify it only for one of them.

# Examples

Timeout of 3 minutes for both create and update:

timeout: 180

Timeout of 5 minutes for create and no timeout for update:

timeout:
  create: 300

Separate timeouts for create and update:

timeout:
  create: 300
  update: 120

# See Also

# Ignoring Stacks

Sometimes it is useful to be able to exclude a certain stack or an entire stack group from the deployment. This is accomplished with the ignore property which accepts a boolean value. If a stack is marked as ignored, it is left out of the configuration and won’t be deployed. Ignoring a stack group will mark it and everything under it as ignored.

# Examples

Ignore the stack:

ignore: true

# See Also

# Command Role

The commandRole property accepts an IAM role ARN and is used to tell which IAM role Takomo should use to deploy the stack. It can be used to choose a role with restricted permissions that allow modifying only the resource types defined in the stack.

As IAM roles are always linked to some AWS account, the command role can also be used to choose the target AWS account where the stack is deployed.

# Examples

Setting the commandRole:

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

# See Also

# Target Accounts

Working simultaneously with multiple AWS accounts usually requires switching between a number of AWS credentials or IAM roles. This poses a real risk of accidentally deploying infrastructure to a wrong AWS account. This risk can be mitigated with the accountIds property to define a list of AWS accounts where the stack can be deployed. It accepts a single account id or a list of account ids.

# Examples

Setting a single allowed account id:

accountIds: "123456789012"

Setting multiple allowed account ids:

accountIds:
  - "876272828282"
  - "763273627326"

# See Also

# Hooks

Sometimes deploying infrastructure requires that custom scripts or actions are run at certain stages of creating, updating or deleting stacks. These custom actions could be compiling, packaging and uploading lambda code or just sending a notification to some http endpoint whenever the deployment fails. These custom actions can be integrated to the deployment process with hooks.

The hooks property accepts a list of hook objects that contain configuration specifying what action should be run and when to run it.

A hook object has the following properties:

  • name - Name of the hook
  • type - Type of the hook
  • operation - Operations during which the hook is executed
  • stage - Operation stages during which the hook is executed
  • status - Operation results during which the hook is executed

In addition to these standard properties, different hook types can have their own set of required and optional properties.

The hooks are run in the order they are defined. If a hook fails, then all remaining hooks are cancelled and the whole stack operation fails.

# 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

# Secrets

Managing secrets, such as database credentials and various authorization tokens, is a common problem that is quite hard to automate. Takomo offers one way to tackle this problem with stack secrets that are declared locally and persisted to AWS Systems Manager Parameter Store as encrypted parameters. Secret configuration contains only name and description for the secrets, but the actual values are never stored to the local disk.

The secret property is used to declare stack secrets. It's an object whose keys are secret names and values are objects containing descriptions for the corresponding secrets.

The secrets are managed with CLI commands and can be referred from the configuration of the declaring stack or from some other stack.

# How Secrets Are Stored

Secrets are always owned by the declaring stack and when the stack is deleted, so are the secrets it declared. Secrets are stored to the Parameter Store with stack's secrets path which is generated from the stack path using the following formula:

  1. Append a forward slash to the stack path
  2. If the project property is defined, prepend it with a forward slash

For example, if the stack path is /dev/rds.yml/eu-west-1 and project is example, then the secrets path will be /example/dev/rds.yml/eu-west-1/. If the stack declares a secret name myPassword, it will be stored to the Parameter Store with a name /example/dev/rds.yml/eu-west-1/myPassword.

This way, all the stack secrets are found from the Parameter Store under the same path prefix which enables Takomo to detect differences between the local configuration and the secrets stored in Parameter Store.

# 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

# Data Variables

Stack groups and stacks can expose arbitrary variables with the data property. These variables can be referenced from stack group and stack configuration files, and from CloudFormation templates with .hbs file extension.

# Examples

data:
  environment: dev
  urls:
    - https://google.com
    - https://github.com
  applications:
    website:
      id: 12345
      name: My website
    backend:
      id: 4
      name: My API

# See Also

Last Updated: 6/26/2020, 8:25:21 PM