How to customize an Amazon Elastic Beanstalk instance
The default Amazon Elastic Beanstalk AMI provides a Java-based application container with Apache Tomcat as the work horse. All you have to do is to deploy a standard Java WAR file containing your web application.
But sometimes, the standard AMI does not provide everything. Maybe the Apache configuration needs to be tweaked or some package, e.g. a local memcached server, is missing.
Customizing the Beanstalk AMI is easy, there are only a few simple steps, which are outlined here.
First of all, start the AMI to be customized in the AWS console. Note: as described by foremosttravel in the Beanstalk forum, the instance should be started from the EC2 console, NOT the Beanstalk console, as running the AMI within the Beanstalk environment may lead to it being terminated during the EBS snapshot, as it might fail to answer to the Beanstalk health checks.
Preparation
So here are the step by step instructions for the preparation:
- Go to the EC2 console
- Select region US-East, as Beanstalk is currently available only there
- Click Launch instance
- Enter either
ami-100fff79for the 64bit AMI orami-060fff6ffor the 32bit AMI (as of Feb 8th, 2011; these AMIs contain fixes to preserve the original hostname and protocol, which are stripped by the load balancer)
- Click Select, then Continue, until the step Create Key Pair
- Choose an existing key pair or create a new one. This will be used to access the running instance using SSH
- In the next step, specify an appropriate security group, which allows SSH access, e.g.
SSH - Press continue and finally launch the instance
- In the instance list, press the right mouse button over the instance and choose Connect
- Copy the SSH command line, adjust the path to your private key and connect to the instance using a SSH client.
Note: you need to connect as user
ec2-user,rootaccess can be obtained using the commandsudo su -. See this blog post for details on how to access the instance.
Customization
Now we are free to customize the AMI’s files to our heart’s content.
Note: As the AMI is running outside the Beanstalk environment, Apache, Tomcat, and HostManager (the software interface to Beanstalk), are not running, as they didn’t get the expected parameters, such as the path of the application to start. This doesn’t matter, as soon as we start the customized AMI in an Beanstalk environment, everything works again.
As a proof of concept, we change HostManager‘s default index page (/opt/elasticbeanstalk/srv/hostmanager/views/index.erb) to contain the following HTML body:
<body style="font-family:Verdana,Arial,Sans-serif;">
<div class="logo">
<img src="http://awsmedia.s3.amazonaws.com/logo_aws.gif" />
<h2>Host Manager</h2>
<b>Haz customization!</b>
</div>
</body>
Note: when changing HostManager or the Apache configuration, please make sure, that HostManager still answers to Beanstalk requests on /_hostmanager and the application to health checks on /, otherwise the instance will be terminated and another will be started!
Persisting changes
Now that we are done, we need to create an EBS snapshot to preserve our customizations. The AMI is EBS-backed, so a snapshot can be used to register an AMI, which is based on the snapshot.
Again, here are the step by step instructions:
- Remove eveything you do not want to remain in the instance such as the bash history, SSH keys, …
- Create an EBS snapshot, either from the EC2 console or the command line tools. See the user guide for details.
- You now have an AMI. See Images > AMI on the left side of the EC2 console and choose Owned By Me in the AMI tab to view your newly create AMI. Note down the AMI id.
If you want to make some more changes, keep the current instance running, while you test your changes from within Beanstalk. After a test drive (see below), make some more changes and create another image. Rinse and repeat until you are satisfied with the results. Don’t forget to clean up any unnecessary EBS snapshots and AMIs, as they cost actual money!
Start customized instance in Beanstalk
If you want to test-drive your customized AMI, you need to start an Beanstalk environment with the id of the customized AMI. There are two ways to perform this, via the Beanstalk console or from the command line.
Via Beanstalk console
- Go to the Beanstalk console
- Create an environment
- Wait for everything to be started so you can change the configuration
- Adjust the AMI id as described in the user guide
- Restart the environment
- Test your changes. In our example, we go to the changed
HostManagerindex page at http://myenv.elasticbeanstalk.com/_hostmanager
Via command line
We use my simplified script to start an Amazon Elastic Beanstalk application from command line. See here for a detailed description. We can specify all parameters right from the start, so we do not need to wait for the initial start, before we can adjust the configuration.
- Download the script from GitHub
- Start an environment with the following command:
eb-create-app.sh -a myapp -i ami-be55a5d7 -t t1.micro -C 64 -e myenv -k mykeypairMake sure to specify the id of your AMI as created above. Also don’t forget to specify a keypair, otherwise you won’t be able to log in using SSH. The name of the environment must be unique, as it is also used as CNAME (this can be overridden with
-c <CNAME>though) - Test your changes. In our example, we go to the changed
HostManagerindex page at http://myenv.elasticbeanstalk.com/_hostmanager
Outlook
Have fun creating customized instances. Please leave feedback and/or a note in the comments, which describes your changes. I will try to change HostManager to run the Virgo OSGi server instead of Tomcat, so stay tuned for the next installment.
