gocloudformationplus

README

gocloudformationplus

A Golang module for interacting with AWS CloudFormation.

Creating/Updating stacks

The Stack struct has the following fields:

• Capabilities ([]string)
• Parameters ([]Parameter)
• RoleARN (string)
• StackName (string)
• Template (string)

The EnsureOptions struct has the following fields:

• TimeoutInMinutes int

The Stack struct has the following functions:

• Ensure(chan<- EnsureResult) creates/updates the stack then publishes a EnsureResult to the channel when it is complete.
• EnsureWithOptions(chan<- EnsureResult, EnsureOptions) creates/updates the stack then publishes a EnsureResult to the channel when it is complete.
• EnsureSyncWithOptions(EnsureOptions) (EnsureResult, error) creates/updates the stack. The function does not return until the operation is complete.

package main

func main() {
    stack := gocloudformationplus.Stack{
        Capabilities: []string{"CAPABILITY_IAM"},
        Parameters: []gocloudformationplus.Parameter{
            {
                Key:   "MyParameter",
                Value: "MyValue",
            },
        },
        StackName: "MyStack",
        Template:  "{...}",
    }

    options := gocloudformationplus.EnsureOptions{
        TimeoutInMinutes: 3,
    }

    stack.EnsureSyncWithOptions(options)
}

Getting the most recent stack events

• GetEvents(stackID string, chan<- GetEventsResult)
• GetEventsSync(stackID string) (GetEventsResult, error)

Getting a stack's outputs

• GetOutputs(stackID string, chan<- GetOutputsResult)
• GetOutputsSync(stackID string) (GetOutputsResult, error)

Deleting a stack

• Delete(stackID string, chan<- DeleteResult)
• DeleteSync(stackID string) (DeleteResult, error)

Licence, credit & sponsorship

This project is published under the MIT Licence.

You don't owe me anything in return, but as an indie freelance coder there are two things I'd appreciate:

• Credit. If your app or documentation has a credits page, please consider mentioning the projects you use.
• Cash. If you want and are able to support future development, please consider becoming a patron or buying me a coffee. Thank you!

Documentation

Index

• func Delete(stackID string, done chan<- DeleteResult)
• func GetEvents(stackID string, done chan<- GetEventsResult)
• func GetOutputs(stackID string, done chan<- GetOutputsResult)
• type CreateOptions
• type CreateResult
• type DeleteResult
  • func DeleteSync(stackID string) (result DeleteResult, err error)
• type EnsureOptions
• type EnsureResult
• type Event
• type GetEventsResult
  • func GetEventsSync(stackID string) (result GetEventsResult, err error)
• type GetOutputsResult
  • func GetOutputsSync(stackID string) (result GetOutputsResult, err error)
• type Output
• type Outputs
  • func (outputs Outputs) Get(key string) (string, error)
• type Parameter
• type Stack
  • func (stack Stack) Ensure(done chan<- EnsureResult)
  • func (stack Stack) EnsureSyncWithOptions(opts EnsureOptions) (result EnsureResult, err error)
  • func (stack Stack) EnsureWithOptions(done chan<- EnsureResult, opts EnsureOptions)
• type StackOperationError
  • func (e StackOperationError) Error() string
• type UpdateOptions
• type UpdateResult

Functions

func Delete

func Delete(stackID string, done chan<- DeleteResult)

Delete deletes a CloudFormation stack.

func GetEvents

func GetEvents(stackID string, done chan<- GetEventsResult)

GetEvents gets the most recent events on a CloudFormation stack.

func GetOutputs

func GetOutputs(stackID string, done chan<- GetOutputsResult)

GetOutputs gets the outputs of a CloudFormation stack.

Types

type CreateOptions

type CreateOptions struct {
	TimeoutInMinutes int
}

CreateOptions describes options for creating a CloudFormation stack.

type CreateResult

type CreateResult struct {
	// Error describes any error that occurred during the creation.
	//
	// The error is included within this struct so that it can be bundled with
	// other data (TBA) in a channel message.
	Error error

	// StackAlreadyExists indicates whether or not the stack already existed
	// before the creation was attempted.
	StackAlreadyExists bool
}

CreateResult describes the result of creating a CloudFormation stack.

type DeleteResult

type DeleteResult struct {
	// Error describes any error that occurred during the deletion.
	//
	// The error is included within this struct so that it can be bundled with
	// other data (TBA) in a channel message.
	Error error
}

DeleteResult describes the result of deleting a CloudFormation stack.

func DeleteSync

func DeleteSync(stackID string) (result DeleteResult, err error)

DeleteSync syncronously deletes a CloudFormation stack.

type EnsureOptions

type EnsureOptions struct {
	TimeoutInMinutes int
}

EnsureOptions descriptions options for ensuring a CloudFormation stack.

type EnsureResult

type EnsureResult struct {
	// Error describes any error that occurred during the ensurance.
	//
	// The error is included within this struct so that it can be bundled with
	// other data (TBA) in a channel message.
	Error error
}

EnsureResult describes the result of ensuring a CloudFormation stack.

type Event

type Event struct {
	LogicalResourceID    string
	ResourceStatus       string
	ResourceStatusReason string
}

Event describes a CloudFormation stack event.

type GetEventsResult

type GetEventsResult struct {
	// Error describes the error (if any) that occurred when attempting to
	// get a CloudFormation stack's events
	//
	// The error is included within this struct so that it can be included with
	// any other data (to be added in the future) as a channel message.
	Error error

	// Events describes the most recent events on a CloudFormation stack.
	Events []Event
}

GetEventsResult describes the result of getting the most recent events on a CloudFormation stack.

func GetEventsSync

func GetEventsSync(stackID string) (result GetEventsResult, err error)

GetEventsSync syncronously gets the most recent events on a CloudFormation stack.

type GetOutputsResult

type GetOutputsResult struct {
	// Error describes any error that occurred during the get of the outputs.
	//
	// The error is included within this struct so that it can be bundled with
	// other data (TBA) in a channel message.
	Error error

	// Outputs describes the outputs of the CloudFormation stack
	Outputs Outputs
}

GetOutputsResult describes the result of getting the outputs of a CloudFormation stack.

func GetOutputsSync

func GetOutputsSync(stackID string) (result GetOutputsResult, err error)

GetOutputsSync syncronously gets the outputs of a CloudFormation stack.

type Output

type Output struct {
	Key   string
	Value string
}

Output describes a CloudFormation stack output.

type Outputs

type Outputs struct {
	Outputs []Output
}

Outputs describes a CloudFormation stack's outputs.

func (Outputs) Get

func (outputs Outputs) Get(key string) (string, error)

Get gets the value of the specified output.

type Parameter

type Parameter struct {
	Key   string
	Value string
}

Parameter describes a CloudFormation template parameter.

type Stack

type Stack struct {
	Capabilities []string
	Parameters   []Parameter
	RoleARN      string
	StackName    string
	Template     string
}

Stack describes a CloudFormation stack.

func (Stack) Ensure

func (stack Stack) Ensure(done chan<- EnsureResult)

Ensure creates/updates the CloudFormation stack.

func (Stack) EnsureSyncWithOptions

func (stack Stack) EnsureSyncWithOptions(opts EnsureOptions) (result EnsureResult, err error)

EnsureSyncWithOptions will syncronously create/update the CloudFormation stack with specific options.

func (Stack) EnsureWithOptions

func (stack Stack) EnsureWithOptions(done chan<- EnsureResult, opts EnsureOptions)

EnsureWithOptions creates/updates the CloudFormation stack with specific options.

type StackOperationError

type StackOperationError struct {
	Message string
	Events  []Event
}

StackOperationError describes a CloudFormation stack operation error (eg. a failure to create or update a stack).

func (StackOperationError) Error

func (e StackOperationError) Error() string

type UpdateOptions

type UpdateOptions struct {
}

UpdateOptions describes options for updating a CloudFormation stack.

type UpdateResult

type UpdateResult struct {
	// Error describes any error that occurred during the update.
	//
	// The error is included within this struct so that it can be bundled with
	// other data (TBA) in a channel message.
	Error error
}

UpdateResult describes the result of updating a CloudFormation stack.