Tuesday, June 7, 2011

Configuring and Customizing Elastic Bamboo

The Elastic Bamboo feature in JIRA Studio can utilize Amazon EC2 for builds. But integrating EC2 into Bamboo can be an overwhelming task for a beginner. To complement Atlassian's documentation, this article gives a few tips on how to setup a EC2 build account and configure EB. Even though this is not a Bamboo or a AWS tutorial, you can follow links in the article to learn more about the subjects applicable to the task at hand.

Setting up a Special Build User in AWS

Since EB needs AWS security credentials to launch and manage EC2 instances, you can use AWS Identity and Access Management (IAM) to setup a special build user with only EC2 permissions. Let's call this special user "eb-builder". Give this user its own access keys and X.509 certificates. Follow the IAM User Guide if you don't already know how to do this.

Configuring Elastic Bamboo to Use AWS

SSH Key Pair
These are the keys you will need later to log onto the EC2 instance launched by EB. When you configure EB for the first time, it will automatically generate a key pair for you called elasticbamboo. If you use hosted JIRA Studio, the private key is stored in the Atlassian host and can be downloaded later.

AWS Access Keys
EB needs access keys to call AWS APIs in order to perform AWS actions such as us launching EC2 instances. Instead of supplying EB the access keys from your master AWS account, use access keys you generated earlier for eb-builder.

AWS X.509 Certificate and Private Key
EB needs both the certificate and the private key to use EBS. Again, supplying EB with the certificate and the private key you generated earlier for eb-builder, not the ones you created for your master AWS account. This is a good security practice to keep in mind.

Customizing Elastic Bamboo Default Image

There are two reasons for customizing the default EB image:

(1) To persist build dependencies like 3rd party libraries. The default image uses instance-store which does not persist after the EC2 instance is gone. One easy way to persist build dependencies is to use an EBS volume.
(2) To add your own builder. For example, you may want Maven 3 instead of Maven 2 that comes with the default image.

EBS comes in handy when you have relatively static build dependencies like 3rd party libraries. It also allows you to install your own build tools instead of using those from the default image. You can follow the steps here to create an EBS volume to store your custom bits. But note Step 2 in Creating your first EBS snapshot on that link. That step is not applicable to the hosted version of JIRA Studio. In that case, you must file a support ticket and ask Atlassian to load your X.509 certificate and the private key for you. If you install a new Maven release like Maven 3 or a new JDK, do not put them in the bamboo:bamboo user path. Instead, configure their paths when you add a new custom builder as below.

Add Custom Builder
Let's say you have installed Maven 3 under /mnt/bamboo-ebs/maven3 and made a snapshot of the EBS volume. To configure EB to use the new Maven bits, you follow the Add Capabilities steps here. When adding a new builder for Maven 3, make sure you select the "Maven 2.x" capability type. Hopefully Atlassian will add an official Maven 3 capability type in the near future. Once you complete those steps, the new Maven 3 builder will show up as a builder candidate when you setup a build plan for your project.

That's the gist of configuring and customizing Elastic Bamboo. Happy building!