Command Custom Stack#

Command custom stack is a built-in custom stack implementation that allows you to define shell commands to run at each phase of custom stack lifecycle, i.e. create, update and delete.

Properties#

Here are the properties of the command custom stack.

Command Config#

When configuring a shell command to execute with createCommand, updateCommand, deleteCommand, getCurrentStateCommand, and getChangesCommand, you can use a complex object instead of plain string.

Environment Variables Available in the Shell Commands#

The following environment variables are available in the shell commands:

How Command Custom Stack Works?#

Deploy#

This is what happens when Takomo deploy command is executed:

1. Stack's current state is retrieved by invoking getCurrentStateCommand command.
2. Planned changes to the stack are retrieved by invoking getChangesCommand command.
3. If the stack's current state has status CREATE_COMPLETE or UPDATE_COMPLETE, the stack is updated by invoking updateCommand. Otherwise the stack will be created by invoking createCommand.

Undeploy#

This is what happens when Takomo undeploy command is executed:

1. Stack's current state is retrieved by invoking getCurrentStateCommand command.
2. If the stack's current state has status CREATE_COMPLETE, UPDATE_COMPLETE or UNKNOWN, the stack is delete by invoking deleteCommand. Otherwise the stack delete is skipped.

How to Implement Commands?#

All commands must output valid JSON string. Use capture property to control whether you want to use the whole script output or just the last line.

Get Current State#

This command is used to determine the current state of the custom stack.

The command must output valid JSON string representing CustomStackState.

Note that only status property is required, so the minimum state can look like this:

{ "status": "PENDING" }

The status can be one of the following:

• CREATE_COMPLETE = Stack exists
• UPDATE_COMPLETE = Stack exists
• PENDING = Stack does not exist
• UNKNOWN = Stack status is unknown

Get Changes#

During deploy operation, this command is used to determine what changes the operation would apply to the custom stack.

The command must output valid JSON string representing an array of CustomStackChange objects.

You can return empty array if no changes are expected:

[]

Or if there are changes, you can return:

[{ "description": "some resource will be changed" }]

There are no requirements for descriptions other than they should preferably be something informative.

Create#

During deploy operation, this command is used to create new custom stack resources.

The command must output valid JSON string representing CustomStackState.

Note that only status property is required, so the minimum state can look like this:

{ "status": "CREATE_COMPLETE" }

Update#

During deploy operation, this command is used to update existing custom stack resources.

The command must output valid JSON string representing CustomStackState.

Note that only status property is required, so the minimum state can look like this:

{ "status": "UPDATE_COMPLETE" }

Delete#

During undeploy operation, this command is used to delete existing custom stack resources.

The command output is ignored.

Examples#

Simple usage of Command custom stack. Set customType: cmd to specify that you want to use Command custom stack.

Then, define configuration for the custom stack with customConfig property.

In this example, each command invokes a shell script that implements the actual logic. Properties exposeStackCredentials and exposeStackRegion are set to true, so the shell script can access credentials and region of the current custom stack.

customType: cmd
customConfig:
  getCurrentStateCommand: ./get-current-state.sh
  getChangesCommand: ./get-changes.sh
  createCommand: ./create-stack.sh
  updateCommand: ./update-stack.sh
  deleteCommand: ./delete-stack.sh
  exposeStackCredentials: true
  exposeStackRegion: true