Fundamentals

Fundamentals

Creating a Template

You can create a template by invoking the create method on KloudFormationTemplate in the package io.kloudformation.model

fun myStack() = KloudFormationTemplate.create { }

Alternatively, if you are implementing StackBuilder your stack building method will look like this:

class Stack: StackBuilder {
    override fun KloudFormation.create() { }
}

You can invoke this method by running the main method in StackBuilder as part of a build tool like Maven or Gradle (See Get Started).

Within the { } braces you have access to all of KloudFormation

Creating Resources

Creating resources is covered in detail in the Resources section.

To create a resource simply call the builder function for that resource, for example if in CloudFormation the type is AWS::SNS::Topic then the function will be called topic which will exist in the package io.kloudformation.resource.aws.sns.

Every resource has a builder function of the same name.

Here are some of the resource packages

Required Resource Properties

The builder function can be invoked by passing any required parameters for that resource inside ( ) brackets

import io.kloudformation.model.KloudFormationTemplate
import io.kloudformation.toYaml
//sampleStart
import io.kloudformation.KloudFormation
import io.kloudformation.StackBuilder
import io.kloudformation.resource.aws.sns.topic
import io.kloudformation.resource.aws.ec2.vPC

class Stack: StackBuilder {
    override fun KloudFormation.create() {
        topic() // No required properties
        vPC(cidrBlock = +"0.0.0.0/0") // cidrBlock is required
    }
}
//sampleEnd

fun main(){
 println(KloudFormationTemplate.create {
         Stack().run { create() }
 }.toYaml())
}

Not Required Resource Properties

Any properties that are not required appear as functions on the builder for that resource. The builder is passed to you in the last argument. The last argument can be a lambda with { } braces.

import io.kloudformation.model.KloudFormationTemplate
import io.kloudformation.toYaml
//sampleStart
import io.kloudformation.KloudFormation
import io.kloudformation.StackBuilder
import io.kloudformation.resource.aws.s3.bucket
import io.kloudformation.resource.aws.ec2.vPC

class Stack: StackBuilder {
    override fun KloudFormation.create() {
        bucket {
            bucketName("myBucket") // This property is not required
        }
        vPC(cidrBlock = +"0.0.0.0/0") { // Notice the + here, See the section below on Value<T>
            enableDnsHostnames(true) // This property is not required
        }
    }
}
//sampleEnd

fun main(){
 println(KloudFormationTemplate.create {
         Stack().run { create() }
 }.toYaml())
}

The Value<T> Type

You will spot the Value type all over KloudFormation. It’s simply a way for us to represent any of CloudFormation’s types.

For example, cidrBlock is a required property of vpc. It looks like this in IntelliJ’s Code Completion.

cidrBlock is a Value<String>. In CloudFormation this property is listed as a String. However you can actually provide anything that will result in a String at deploy time. This includes: a String, a resource reference Ref, a join Fn::Join, a resource attribute Fn::GetAtt or any of the other functions in CloudFormation.

The Value<T> type allows us to do this in KloudFormation.

To provide a String anywhere a Value<String> is needed you can use the provided unaryPlus.

vPC(cidrBlock = +"0.0.0.0/0")

Other types can be provided using Value.Of(...)

dBCluster { 
    port(Value.Of(3306))
}

In most cases, function overloads are provided with the simple type

dBCluster { 
    port(3306)
}

The Value<JsonNode> Type

In some places within KloudFormation you will come across the Value<JsonNode> type. This occurs anywhere where JSON is expected.

We have provided a json() function that allows you to pass a kotlin Map<String, Any> that will evaluate to Value<JsonNode>.

For IAM Policies use the policyDocument() function, see IAM Policies

Table of contents