Extend CloudFormation with plugins
Kombustion uses plugins to preprocess and extend your CloudFormation templates.
In addition to generating templates, Kombustion can also create, update and delete your CloudFormation stacks.
Kombustion has automatic support for new CloudFormation types as they are released.
See the Quick start for more details.
Kombustion is built for Linux, FreeBSD, MacOS and Windows.
Get the latest release from the release page.
After downloading for MacOS or Linux, you will need to move the kombustion
binary into your $PATH, and make it executable.
sudo chmod +x kombustion
sudo cp kombustion /usr/local/bin/kombustionInitialise a kombustion.yaml file with the following:
$ kombustion initThis is an example of kombustion.yaml, it should be committed to version
control.
# Name of this project. This is used with `--environment` to create a stack name, which can
# be overridden with `--stack-name`
Name: KombustionExample
# Region is the default region stacks will be deployed into. Can be overridden with `--region us-east-2`
Region: us-east-1
# Plugins can be installed by running `kombustion add github.com/KablamoOSS/kombustion-plugin-serverless`
Plugins:
github.com/KablamoOSS/kombustion-plugin-serverless@0.1.0:
Name: github.com/KablamoOSS/kombustion-plugin-serverless
Version: 0.1.0
Environments:
Development:
# Optionally allowlist the accounts for the environment `development`, this will
# ensure CloudFormation actions are only performed in this account
AccountIDs:
- "1234567890"
# Parameters are added to the CloudFormation Stack during upsert
Parameters:
Environment: development
# Kombustion can generate default outputs for your resources to use as references in other
# stacks.
GenerateDefaultOutputs: falseUpsert a CloudFormation template:
$ kombustion upsert examples/stacks/test.yaml --stackName test-stackDelete a CloudFormation stack:
$ kombustion delete examples/stacks/test.yamlPrint all the events for a stack:
$ kombustion events examples/stacks/test.yamlYou don't need to specify --stack-name, instead when you pass an environment
--environment it gets merged in with the project name from kombustion.yaml
and the filename as {ProjectName}-{FileName}-{Environment}.
This applies to upsert,delete, and events.
A stack template is written in the same way as standard CloudFormation. Kombustion allows plugins to extend the syntax, but the end result is always standard CloudFormation.
The following example shows how a small definition for a bastion host, can be processed into a bigger template. This lets your plugin maintain safe, sane defaults, and ensure you don't miss any required fields.
# In this example we're going to create a bastion host.
# This is a small EC2 instance, configured with a public IP
# and a security group to allow us to SSH into our AWS cloud.
AWSTemplateFormatVersion: 2010-09-09
Description: Example EC2 Instance
Parameters: {}
Mappings: {}
Resources:
BastionHost:
Type: Kombustion::Examples::BastionHost
Properties:
# In this example, this key would have been uploaded to AWS
KeyName: my-ssh-key
Size: t2.micro
# Using a filter, find the most recent AMI of Amazon Linux 2
AmiFilter:
VirtualizationType: "hvm"
Name: "amzn2-ami-*",
RootDeviceType: "ebs"
owners: ["amazon"],
Latest: trueThe Plugin Kombustion::Examples::BastionHost is used to generate the following
template. It uses the AmiFilter to find the correct AMI, and creates two
parameters for the KeyName and SSHLocation. The latter being the IP address
allowed through the security group.
AWSTemplateFormatVersion: 2010-09-09
Description: Example EC2 Instance
Parameters:
KombustionExampleBastionHostKeyName:
Description: Name of an existing EC2 KeyPair to enable SSH access to the instances
Type: 'AWS::EC2::KeyPair::KeyName'
Default: 'my-ssh-key'
ConstraintDescription: must be the name of an existing EC2 KeyPair.
KombustionExampleBastionHostSSHLocation:
Description: The IP address range that can be used to SSH to the EC2 instances
Type: String
MinLength: '9'
MaxLength: '18'
Default: 0.0.0.0/0
AllowedPattern: '(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})/(\d{1,2})'
ConstraintDescription: must be a valid IP CIDR range of the form x.x.x.x/x.
Mappings: {}
Resources:
Resources:
EC2Instance:
Type: 'AWS::EC2::Instance'
Properties:
InstanceType: !Ref InstanceType
SecurityGroups:
- !Ref InstanceSecurityGroup
KeyName: !Ref KombustionExampleBastionHostKeyName
ImageId: 'ami-c267b0a0'
InstanceSecurityGroup:
Type: 'AWS::EC2::SecurityGroup'
Properties:
GroupDescription: Enable SSH access
SecurityGroupIngress:
- IpProtocol: tcp
FromPort: '22'
ToPort: '22'
CidrIp: !Ref KombustionExampleBastionHostSSHLocation
IPAddress:
Type: 'AWS::EC2::EIP'
IPAssoc:
Type: 'AWS::EC2::EIPAssociation'
Properties:
InstanceId: !Ref EC2Instance
EIP: !Ref IPAddressCheck out the examples directory for example stacks.
Kombustion uses the same method as the aws cli to get
credential information.
You can either use the standard environment variables AWS_ACCESS_KEY_ID,
AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN.
Or use a profile you have configured, for example:
$ kombustion --profile myAwsProfile upsert examples/stacks/test.yaml --stackName test-stackKombustion plugins are not yet supported on Windows, due to this issue. Please use Docker or WSL in the meantime.
Install a plugin:
$ kombustion add github.com/Example/ExamplePluginPlease read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.
We use SemVer for versioning. For the versions available, see the tags on this repository.
Kombustion is primarily maintained by the Kablamo team. Pull requests are welcome.
The Kombustion logo is based on an original design by Renee French.
This project is licensed under the MIT License.
Made with ❤️ in Australia.