User's Guide

AWS CloudFormation Stack

This Task enables you to create, update or delete a CloudFormation stack defined by a template provided via URL or inline and specify template parameters and advanced options.

Amazon Elastic Compute Cloud (EC2) Instance

This Task enables you to start, stop or reboot provisioned EC2 instances on demand, e.g. only when needed by the build itself (development) or at specific times of the day (operations).

Amazon Elastic Compute Cloud (EC2) Image

This Task enables you to create, delete or backup images of EBS backed EC2 instances; in particular, the Task provides backup management with retention handling and backup set correlation.

Amazon Elastic Block Store (EBS) Snapshot

This Task enables you to create, delete or backup snapshots of EBS volumes; in particular, the Task provides backup management with retention handling and backup set correlation.

Bamboo Variable Substitution/Definition

All Tasks support Bamboo variables, both substituting them within parameters for AWS resource management and defining them from created AWS resources.

Variable Substitution

Variables are substituted in all Task configuration text fields (e.g. Stack Name, Template URL, Instance ID, Volume ID etc.).

Please note the following feature:

• if the variable key contains the phrase "password", the value will be masked with "********" in the build logs; e.g. if the key is "password", "awsAccessKeyPassword" or "awsSecretKeyPassword" the build log will show the substituted value as "********"

Variable Definition

Variables are defined by all Tasks for reuse in subsequent Tasks as follows:

• variables have a dedicated prefix like bamboo.custom.aws.*, with * being a task specific prefix, e.g. bamboo.custom.aws.cfn.stack
• variables refering to a collection of resources provide their ids in a semicolon separated list (i.e. the same format available on input), e.g. ${bamboo.custom.aws.ec2.image.resources} with values ami-985b21f1;ami-9a5b21f3
• you can refer to these variables from subsequent tasks via something like ${bamboo.custom.aws.cfn.stack.sampleStackOutputKey}
• these variables are also available as environment variables in the Script Task for example, albeit named slightly different, e.g. $bamboo_custom_aws_cfn_stack_StringWithRegex (Unix) or %bamboo_custom_aws_cfn_stack_StringWithRegex% (Windows)

Please note the following constraints:

• variables are only reusable in subsequent tasks and not in other jobs/stages due to the implied concurrency, see the following discussion and workaround

Available variables per Task are as follows:

• AWS CloudFormation Stack
  • the collection of affected stack resources, e.g. bamboo.custom.aws.cfn.stack.resources=i-3280997f;vol-e1debbcd;test-stack-SecurityGroup-KZWPADIUPCL6
  • the status of each affected stack resource, e.g. bamboo.custom.aws.cfn.stack.i-3280997f=CREATE_COMPLETE
  • the collection of generated stack outputs, e.g. bamboo.custom.aws.cfn.stack.outputs=sampleStackOutputKey;StringWithRegex;...
  • the value of each generated stack output, e.g. bamboo.custom.aws.cfn.stack.StringWithRegex=Hello
    • Note: The variables with legacy naming without prefix remain available for compatibility (e.g. bamboo.StringWithRegex=Hello)
• AWS EC2 Instance
  • the collection of affected instances, e.g. bamboo.custom.aws.ec2.instance.resources=i-fa7b4596;i-080eec64
  • the status of each affected instance, e.g. bamboo.custom.aws.ec2.instance.i-fa7b4596=started
• AWS EC2 Image
  • the collection of affected images, e.g. bamboo.custom.aws.ec2.image.resources=ami-985b21f1;ami-9a5b21f3
  • the status of each affected instance, e.g. bamboo.custom.aws.ec2.image.ami-985b21f1=available
• AWS EBS Snapshots
  • the collection of affected snapshots, e.g. bamboo.custom.aws.ec2.snapshots.resources=snap-f4dc35a1
  • the status of each affected snapshots, e.g. bamboo.custom.aws.ec2.snapshots.snap-f4dc35a1=completed

AWS Credentials

The AWS credentials need to be specified for each task currently, which can be cumbersome quickly. Pending a more generic solution, it is already possible to ease this a bit via variable substitution as follows:

• configure Access Key and Secret Key as e.g. ${bamboo.awsAccessKeyPassword} and ${bamboo.awsSecretKeyPassword}
• define plan and/or global variables for the configured variable names (i.e. awsAccessKeyPassword and awsSecretKeyPassword given this example) with the actual credentials, which will then be substituted on task execution accordingly

AWS Client Configuration

The AWS API is eventually consistent only and also exhibits a customer specific dynamic throttling policy, both of which require respective retry logic to be in place. Accordingly the facilitated AWS SDK for Java features an exponential backoff strategy already, but its default retry number of 3 (accumulating to a retry window of up to ~4 seconds) has proven to be too low for the tasks at hand, which has been increased to 7 accordingly (accumulating to a retry window of up to ~1 minute).

This should ideally be sufficient for most scenarios, but the values are adjustable by defining one or both of the following variables if need be:

• ${custom.aws.maxErrorRetry} - how many retries should the exponential backoff algorithm perform (default: 7)
• ${custom.aws.awaitTransitionInterval} - how long should the task wait before querying the resource transition state again (default: 15000 milliseconds)

Limitations

You should be aware of the following limitations regarding AWS API coverage and integration:

AWS CloudFormation

• We have focused on API coverage so far and usability is not up to speed yet accordingly, there is obviously room for improvements, e.g.:
  • Some configuration screen polish should get us a long way already.
  • Fetching existing AWS resources for selection during configuration would avoid manual copying of information.
  • Offering several samples/defaults to ease getting started.
  • ...
• Stack rollback is currently handled as follows, hopefully covering the majority of use cases (please let us know otherwise):
  • A stack rolled back successfully by CloudFormation is treated as a failed build by Bamboo.
  • A stack not rolled back due to rollback being disabled explicitly is still treated as a failed build by Bamboo.

Amazon Elastic Compute Cloud (EC2)

• We currently consider instance lifecycle goals (i.e. create/terminate) to be sufficiently addressed by the CloudFormation Task, hopefully covering the majority of use cases (please let us know otherwise).