Kombustion CLI

Usage

$ kombustion [global options] command [command options] [arguments...]

All of these commands should be called from the same directory where kombustion.yaml is location, which is usually the root directory of your project. If no kombustion.yaml can be found, an error is thrown.

Global Options

--verbose

Output with high verbosity.

$ kombustion --verbose

--profile

Use a profile from ~/.aws/credentials

$ kombustion --profile MyProfile

--manifest-file

location of the manifest file, defaults to kombustion.yaml

$ kombustion --manifest-file dir/dir/kombustion.yaml

--load-plugin

Load arbitrary plugin.

This option is only avaiable when Kombustion is built from source, see wirting a plugin for more information.

$ kombustion --load-plugin path/to/plugin.so

--help, -h

Prints help.

$ kombustion --help, -h

--version, -v

Print the version.

$ kombustion --version
> kombustion version v1.0.0

# Or
$ kombustion -v
> kombustion version v1.0.0

Core

update

Update kombustion binary to the latest release.

$ kombustion update

Options

-y

Don’t prompt to update, if there is a release.

Plugins

The following commands manage plugins in your project.

Learn more about how to setup a project.

init

Initialise a new manifest file in the current directory.

$ kombustion init

add

Add a plugin to your project.

  • Takes one positional argument, that must be a Github repository url, with a release.
# Arguments
> kombustion add [url]

# Usage
$ kombustion add github.com/organisation/plugin

install

Install all plugins in kombustion.yaml.

$ kombustion install

Stacks

The following commands manage CloudFormation Stacks.

With most of the following commands the Stack Name can either be supplied directly, or is derived from Title in kombustion.yaml, the file name of the stack, and the environment in the following pattern {Title}-{FileName}-{Environment}.

generate

Generate a CloudFormation template, from a template file

Generate allows you to preview the final template, after plugins. It’s the same output that is generated when calling upsert.

  • Takes one positional argument, that is a relative path to the template file.
# Arguments
$ kombustion generate [template file]

# Usage
$ kombustion generate path/to/cloudformation/stack.yaml

Options

--output-directory, -d

(Optional) Set the directory to write the generated files in.

--region, -r

(Optional)Set the region to deploy into.

--stack-name

(Optional) Set the stack name.

If not provided a stack name is derived from Title in kombustion.yaml, the file name of the stack, and the environment in the following pattern {Title}-{FileName}-{Environment}.

If you do not provide --stack-name you must provide --environment.

--environment, -e

(Optional) The environment to deploy to.

Environment config to use as defined in ./kombustion.yaml.

If AccountIDs are listed under the environment, then you will only be able to deploy into that account.

If Parameters are listed under the environment, they will be added to the stack.

--param, -p

(Optional) Specify CloudFormation parameters.

Parameters are also sourced from kombustion.yaml, but paramteres passed via the cli have precedence. Anything you pass via this option, will be used instead of whats in kombustion.yaml.

$ kombustion upsert \
  --param ParamKeyOne=ParamValueOne, ParamKeyTwo=ParamValueTwo \
  path/to/cloudformation/stack.yaml

--generate-default-outputs, -b

(Optional) Disable generation of outputs for Base AWS types

--read-parameters

(Optional) Read parameters from a CloudFormation parameters file

--write-parameters, -w

(Optional) Write parameters to a CloudFormation paramters file

upsert

Update or insert a cloudformation template.

$ kombustion upsert [options] path/to/cloudformation/stack.yaml

Arguments

  • Takes one positional argument, that is a relative path to the template file.

Options

--region, -r

Set the region to deploy into.

--stack-name

(Optional) Set the stack name.

If not provided a stack name is derived from Title in kombustion.yaml, the file name of the stack, and the environment in the following pattern {Title}-{FileName}-{Environment}.

If you do not provide --stack-name you must provide --environment.

--environment, -e

(Optional) The environment to deploy to.

Environment config to use as defined in ./kombustion.yaml.

If AccountIDs are listed under the environment, then you will only be able to deploy into that account.

If Parameters are listed under the environment, they will be added to the stack.

Required if --stack-name is not provided.

--param, -p

(Optional) Specify CloudFormation parameters.

Parameters are also sourced from kombustion.yaml, but paramteres passed via the cli have precedence. Anything you pass via this option, will be used instead of whats in kombustion.yaml.

$ kombustion upsert \
  --param ParamKeyOne=ParamValueOne, ParamKeyTwo=ParamValueTwo \
  path/to/cloudformation/stack.yaml

--generate-default-outputs, -b

(Optional) Disable generation of outputs for Base AWS types

--iam, -i

(Optional) Shorthand for --capability CAPABILITY_IAM

This gives the capability to perform upserts of IAM resources.

CloudFormation requires you to acknowledge when you are modifying a stack with IAM resources.

--capability

(Optional) Set capabilities for the upsert, for example CAPABILITY_IAM

Errors

If the stack is not created successfully for any reason, kombustion returns an exit code of 1 (an error).

No updates to perform

If there are no updates to perform, kombustion will return an exit code of 0 (no error).

delete

Delete a cloudformation stack.

$ kombustion delete [options] path/to/cloudformation/stack.yaml

Arguments

  • Takes one positional argument, that is a relative path to the template file.

Options

--region, -r

Set the region to deploy into.

--stack-name

(Optional) Set the stack name.

If not provided a stack name is derived from Title in kombustion.yaml, the file name of the stack, and the environment in the following pattern {Title}-{FileName}-{Environment}.

If you do not provide --stack-name you must provide --environment.

--environment, -e

(Optional) The environment to deploy to.

Environment config to use as defined in ./kombustion.yaml.

If AccountIDs are listed under the environment, then you will only be able to deploy into that account.

If Parameters are listed under the environment, they will be added to the stack.

Required if --stack-name is not provided.

Errors

If the stack is not deleted for any reason, kombustion returns an exit code of 1 (an error).

events

Print all the events for a stack

$ kombustion events [options] path/to/cloudformation/stack.yaml

Arguments

  • Takes one positional argument, that is a relative path to the template file.

Options

--region, -r

Set the region to deploy into.

--stack-name

(Optional) Set the stack name.

If not provided a stack name is derived from Title in kombustion.yaml, the file name of the stack, and the environment in the following pattern {Title}-{FileName}-{Environment}.

If you do not provide --stack-name you must provide --environment.

--environment, -e

(Optional) The environment to deploy to.

Environment config to use as defined in ./kombustion.yaml.

If AccountIDs are listed under the environment, then you will only be able to deploy into that account.

If Parameters are listed under the environment, they will be added to the stack.

Required if --stack-name is not provided.

Exit Codes

The matrix below describes the exit codes for each CloudFormation status.

In general when calling upsert if the changes requested (be they Create Stack, or Update Stack) are not cleanly applied, an error is returned.

And when calling delete if the stack is not fully deleted, and error is returned.

Legend:

  • 0 - no error
  • 1 - error
  • ~ - Transitional status, kombustion will not exit yet
Status Create Stack Update Stack Delete Stack
CREATE_COMPLETE 0 0 1
CREATE_IN_PROGRESS ~ ~ ~
CREATE_FAILED 1 1 1
DELETE_COMPLETE 1 1 0
DELETE_FAILED 1 1 1
DELETE_IN_PROGRESS ~ ~ ~
REVIEW_IN_PROGRESS 1 1 1
ROLLBACK_COMPLETE 1 1 1
ROLLBACK_FAILED 1 1 1
ROLLBACK_IN_PROGRESS ~ ~ ~
UPDATE_COMPLETE 0 0 1
UPDATE_COMPLETE_CLEANUP_IN_PROGRESS ~ ~ ~
UPDATE_IN_PROGRESS ~ ~ ~
UPDATE_ROLLBACK_COMPLETE 1 1 1
UPDATE_ROLLBACK_COMPLETE_CLEANUP_IN_PROGRESS ~ ~ ~
UPDATE_ROLLBACK_FAILED 1 1 1
UPDATE_ROLLBACK_IN_PROGRESS ~ ~ ~