Apache ACE with Amazon EC2

November 27, 2011 in Blog Leave a reply

Introduction

This article is a guide on how to install and use Apache ACE to provision Amazon EC2 instances.

Installing an ACE server

There are two kind of instances that you need when working with ACE:

One ACE server
One or more targets

You will upload your bundles to the ACE server and use it’s UI to provision distributions to targets. A target is a node where your application runs. Deployment scenarios can be more complex as described here, but for this article we will use a single ACE server.

We will start by setting up the ACE server. You can run this server anywhere (even a machine on your local network) but since this article is about provisioning Amazon EC2 instances we will install ACE itself on EC2 too. You can either download the latest binary ACE release or build one yourself from the sources. In this article we will build ACE ourselves.

Step 1 – Build ACE
Use the following commands to checkout the sources and build them using Maven.

svn checkout http://svn.apache.org/repos/asf/incubator/ace/trunk ace
cd ace
mvn install -Dmaven.test.skip=true

Step 2 – Install the ACE server
Because we will run on an Amazon EC2 instance you will need to start one first using the AWS management console. This is the only time you actually need to start an instance yourself, when we have ACE installed we can do this directly from ACE. It is a good idea to assign a static IP to the node, because you need to reconfigure ACE when the IP changes.

Start at least a “Small” instance. The standard Amazon Linux image (either 32 or 64 bit) is sufficient.

Next you have to transfer the ACE installation to the server. This can easily being done by using an SFTP client using the certificate that you generated in AWS, or you can use the SCP command:


scp -i mycertificate.pem org.apache.ace.target.devserver-0.8.1-incubator-SNAPSHOT-distribution.zip  ec2-user@[server-ip]:ace.zip

Transfer the zip file in ace-target-devserver/target to the Amazon instance. Now SSH to the Amazon Instance (you can use the “connect” button in the AWS console).
Unzip Ace:

unzip ace.zip

Step 3 – Configure the ACE server
ACE needs to be configured to work with EC2. Open conf/org.apache.ace.nodelauncher.amazon.cfg and use the following configuration:

# Configure your server here
server=http://[your-ace-server-ip]:8080

# Note that AMIs are specific to an Amazon availability zone
amiId=ami-6a31041e
location=eu-west-1

# Your access key ID and secret access key (AWS console, top right menu "Security Credentials")
accessKeyid=[your access key]
secretAccessKey=[your secret key]

# Tag prefix for instance names
tagPrefix=default

# Use this bootstrap to use a Sun VM instead of the OpenJDK one provided by Amazon
nodeBootstrap=cd ~; wget -Ojava.bin http://javadl.sun.com/webapps/download/AutoDL?BundleId=43871 ;chmod +x java.bin;./java.bin /y; export PATH=`pwd`/jre1.6.0_23/bin:$PATH

# Open up any extra ports (comma separated list)
extraPorts=9090
additionalObrDownloads=
externalDownloadUrls=

Optional – Use Glassfish on target nodes
By default ACE will start a plain Felix instance on provisioned nodes. You can use Glassfish instead however as shown in this video. The only thing you have to add to the configuration is the following:

aceLauncher=ace-glassfish-launcher.jar
additionalObrDownloads=ace-managementagent.jar
externalDownloadUrls=[glassfish zip download location]

Step 4 – Start the ACE server

./run.sh

The ACE UI should now be available on: http://[your-server-ip]:8080/ace

Running a local test server

Normally you should not need to access a provisioned server directly. In case of problems (e.g. bundles are not starting) it is very convenient to have an OSGi shell available however. Of course you could provision a remote shell to your target instance, but there is an even easier approach. You can run an ACE target on your local machine where you can easily connect to the OSGi shell. Remember that the shell is also just a bundle, so you do need to make it part of your distribution in the ACE UI. Go to the ace directory that you checked-out earlier and open the ace-launcher/target directory. Now start ACE (you might have a different name for the jar file):

java -jar ace-launcher.jar identification=LocalTest discovery=http://[your-ace-server-ip]:8080 fwOption=org.osgi.framework.system.packages.extra=sun.misc,com.sun.management

After a few seconds the LocalTest instance should be visible in the targets column in the ACE UI.

Upload Bundles

All the configuration is completed now. Use the ACE UI to upload some bundles and configure some features and distributions. It is recommended to provision small feature sets at a time to make debugging easier.

Provision EC2 target nodes

Now that you have tested your distribution on a local test server you can spawn real targets. Click the “add target” button, enter a name and click “start”. It will ~1 minute to start the instance. You can see the node starting in your AWS console too. When the node is started ACE will tell you the target’s IP.

When it all goes wrong…

In some rare occasions an ACE target can get into a state where you can no longer deploy or undeploy bundles, or where ACE gets into an endless loop of trying to deploy. Luckily this is not a really big issue because the target nodes are provisioned anyway. Just stop the target and create a new one. This does mean it’s probably not a good idea to store any persistent data on the nodes itself, but use external storage instead (e.g. S3). This is not an ACE issue, but a best practice in general when working with provisioned servers.

Limitations

An ACE server can only be configured to use a single AWS account. Install a second ACE server if you need to provision servers using another AWS account.
An ACE server can either provision Felix or Glassfish to target nodes. If you need some targets with Felix and some others with Glassfish, you need to install a second ACE server.