Extend CloudFormation with plugins
Clone or download
ojkelly [WIP] Fixes for #134, #135, and some more tests (#136)
* fixed up delete tests

* added generate test case against a template

* setting all properties to interface{} as a template can no only be validated by cfn itself

* removed fmt
Latest commit 47f1d46 Nov 19, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Ok/readme (#77) Jul 23, 2018
config Change environment.yaml to pull from kombustion.yaml (#42) Jun 11, 2018
documentation Work for overriding the manifest file location (#122) Oct 2, 2018
examples Adds plugin management, and a more defined plugin api (#18) Jun 5, 2018
generate [WIP] Fixes for #134, #135, and some more tests (#136) Nov 19, 2018
internal [WIP] Fixes for #134, #135, and some more tests (#136) Nov 19, 2018
pkg [WIP] Fixes for #134, #135, and some more tests (#136) Nov 19, 2018
tools/vscode-helper Allow plugins to access Parameters, Condtions, Mapping, Metadata, Tra… Jul 20, 2018
types updated cfResource attributes (#131) Nov 7, 2018
vendor Isolate side-effects / Task testing (#105) Aug 31, 2018
.dockerignore initial commit 🚀 May 21, 2018
.editorconfig Added .editorconfig May 24, 2018
.gitignore template tests (#54) Jun 20, 2018
.travis.yml fixing tagged build destination Jul 4, 2018
CODE_OF_CONDUCT.md Updated readme, and moved configs to examples (#6) May 23, 2018
CONTRIBUTING.md Updated readme, and moved configs to examples (#6) May 23, 2018
Dockerfile initial commit 🚀 May 21, 2018
Gopkg.lock Isolate side-effects / Task testing (#105) Aug 31, 2018
Gopkg.toml Adds plugin management, and a more defined plugin api (#18) Jun 5, 2018
LICENSE Add License May 22, 2018
README.md Replace whitelist with allowlist (#109) Sep 7, 2018
main.go Isolate side effect part 2 (#106) Sep 6, 2018
netlify.toml Documentation update (#56) Jun 29, 2018

README.md

Kombustion Logo

Kombustion

Build Status Go Report Card Coverage Status

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.

Getting Started

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/kombustion

Usage

Initialise a kombustion.yaml file with the following:

$ kombustion init

This 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: false

CloudFormation Stack Management

Upsert a CloudFormation template:

$ kombustion upsert examples/stacks/test.yaml --stackName test-stack

Delete a CloudFormation stack:

$ kombustion delete examples/stacks/test.yaml

Print all the events for a stack:

$ kombustion events examples/stacks/test.yaml

StackName

You 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.

CloudFormation Stacks

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: true

The 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 IPAddress

Check out the examples directory for example stacks.

Credentials

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-stack

Plugins

Kombustion 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/ExamplePlugin

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

Maintainers

Kombustion is primarily maintained by the Kablamo team. Pull requests are welcome.

Acknowledgements

The Kombustion logo is based on an original design by Renee French.

License

This project is licensed under the MIT License.


Made with ❤️ in Australia.