Using Jython to Manage EC2 Resources: Part 3

In part 2, we started up an instance, created a volume, and attached it to the instance - all from the REPL. In this installment, we'll start building a library to aggregate these isolated functions into a complete implementation of our use case.

Remember, we're going to move faster now so the code samples will get larger and the REPL examples fewer and farther between.

We're going to be proactive and split off general functionality we can use elsewhere from our specific use case. Let's start on the general functionality. We essentially want a wrapper class for the portions of that we'll be using regularly.

import as ec2
import com.amazonaws.auth.BasicAWSCredentials as cred                    
import com.amazonaws.ClientConfiguration as conf
import as model
import pickle
Copyright 2011 Jeremy Ulstad

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
See the License for the specific language governing permissions and
   limitations under the License.
class ec2Client:
    def __init__(self, accessKey, secureKey):
        self.accessKey = accessKey
        self.secureKey = secureKey
        self.conf = conf()
        self.instance = None
        self.instanceId = None

    def setup(self):
        self.client=ec2.AmazonEC2Client(cred(self.accessKey,self.secureKey), self.conf)

    def runInstance(self, ami, securityGroup, keyName, instanceType='m1.large'):
        rir = self.client.runInstances((model.RunInstancesRequest(ami, 1,1)
        self.instance = rir.getReservation().getInstances()[0]
        self.instanceId = self.instance.getInstanceId()

    def instanceState(self):
        if self.instance: return self.instance.getState().getName()
        return None

    def createImage(self, name, desc=None):
        cir = self.client.createImage(model.CreateImageRequest()
        return cir.getImageId()

    def describeInstances(self):
        instances = []
        for r in self.client.describeInstances().getReservations():
            for i in r.getInstances():
        return instances

    def runningInstances(self):
        runners = []
        for i in self.describeInstances():
            if i.getState().getName() == 'running': runners.append(i)
        return runners

    def describeVolumes(self, vols=[]):
        return self.client.describeVolumes(model.DescribeVolumesRequest(vols)).getVolumes()

    def createVolume(self, sizeGB, zone):
        return self.client.createVolume(model.CreateVolumeRequest(sizeGB, zone))

    def attachVolume(self, vol, inst, device):
        return self.client.attachVolume(model.AttachVolumeRequest(vol, inst, device))

    def detachVolume(self, vol):
        return self.client.detachVolume(model.DetachVolumeRequest(vol))

    def deleteVolume(self, vol):

    def terminateInstance(self):

    # based on
    def toggleVolumePersistence(self, i, v=False):
        "set deleteOnTermination to v (default: False)"
        ebsVols = [ b.getEbs() for b in i.getBlockDeviceMappings() ]
        for e in ebsVols:
            if e.isDeleteOnTermination():
                # note use of parens to allow multi-line method chaining
                # inspired by
                spec = (model.EbsInstanceBlockDeviceSpecification()
                ispec = (model.InstanceBlockDeviceMappingSpecification()
                mreq = (model.ModifyInstanceAttributeRequest()

Now we have neatly encapsulated everything we have done in previous installments into one class. We can start an instance, create and attach volumes. Nice and general. There's also some extra goodies in there we didn't do from the REPL previously that can come in handy. Finding those can be an exercise for you.

Now let's get specific and create a subclass which will implement our specific use case. To recapitulate: we want to start an instance with six EBS volumes and attach them to the instance automatically.

class ec2Datanode(ec2Client):
    def __init__(self, name, proxy=None, proxyPort=80): = name
        self.volumes = []
        self.volumeIds = []
        self.ami = 'ami-e4a3578d'
        self.securityGroup = 'datanode'
        self.keyName = 'redacted'
        self.sizeGB = 1 = 'us-east-1b'
        self.proxy = proxy
        self.proxyPort = proxyPort
        ec2Client.__init__(self, self.accessKey, self.secureKey)

    def setup(self):
        if self.proxy:
            self.conf = (conf()

    def runInstance(self):
        ec2Client.runInstance(self, self.ami, self.securityGroup, self.keyName)   

    def createVolume(self):
        return ec2Client.createVolume(self, self.sizeGB,

    def createVolset(self, count=6):
        for i in range(0,count):
            vrsp = self.createVolume()
            vol = vrsp.getVolume()
            nametag = '%s vol%s' % (, i)
            vol.setTags([model.Tag('Name', nametag)])

    def attachVolset(self):
        pairs = zip(self.volumeIds, ['f','g','h','i','j','k'])
        for k,v in pairs:
            self.attachVolume(k, self.instanceId, '/dev/sd%s' % v)

    def detachVolset(self):
        for v in self.volumeIds:

    def pickle(self):
        "pickle state of object in case we need to restart the instance after a shutdown"
        filename = '%s-configuration' %
        f = open(filename, 'w')
                     'volumeIds':self.volumeIds}, f)

    def unpickle(self):
        "restore state of instance with volume mappings"
        filename = '%s-configuration' %
        f = open(filename, 'r')
        d = pickle.load(f)
        for k,v in d.items():
            setattr(self, k, v)

You'll notice that we use instance variables to encapsulate all the arguments (availability zone, instance type, etc.) that we need to pass to the general class. Note especially the sizeGB at line 9: when you're getting your code working it's a good idea to use small volumes/instances to minimize the charges you will incur in the process of getting a full working system. I spun up about 30 volumes before I got it right. You don't want to be using a terabyte volume there.

We also code up our specific use cases for the volume creation, attachment, etc. You'll also note the pickle method at the end. EBS volume names are not particularly legible, so if we ever shutdown our instance and want to restart it and reattach the volumes it's nice to be able to unpickle the grouping of them so they can be reattached in the right place. Ideally the tags (lines 38-39) would help with that, but while they can be seen by calling getTags() on the volume for some reason they aren't visible in the AWS console.

Now let's try out our use case.

>>> import aws
>>> d = aws.ec2Datanode('testnode')
>>> d.runInstance()
INFO: Received successful response: 200, AWS Request ID: baaee963-4a02-4ccd-b0ae-03a5bbb84e4e
>>> d.instanceState()
>>> d.createVolset()
INFO: Received successful response: 200, AWS Request ID: 0dcc7744-504f-4929-a83a-61d3b198ab3f
INFO: Received successful response: 200, AWS Request ID: af71b717-f85f-46c5-8681-838a6b6bfb53
INFO: Received successful response: 200, AWS Request ID: 8e7fcb56-b023-4f94-9cb3-c718f0e9f2fe
INFO: Received successful response: 200, AWS Request ID: 43bfbb7c-4a81-4e25-adfe-06c1cb279436
INFO: Received successful response: 200, AWS Request ID: 885b065d-6253-4a80-8cca-943df6961c20
INFO: Received successful response: 200, AWS Request ID: 38043789-f55e-4f2f-a432-1fbc845f629f
>>> d.attachVolset()
INFO: Received error response: Status Code: 400, 
AWS Request ID: 2b9a2e92-4f9e-4648-aa9d-8fa0f42b9ca4, 
AWS Error Code: InvalidVolume.ZoneMismatch, 
AWS Error Message: The volume 'vol-d876eeb0' is not in the same 
availability zone as instance 'i-17a7c27b'
>>> d.volumes = []
>>> d.volumeIds = []
>>> d.createVolset()
Feb 6, 2011 3:21:26 PM com.amazonaws.http.HttpClient execute
INFO: Received successful response: 200, AWS Request ID: 07e17565-2871-4525-80f9-6fee8add6c32
INFO: Received successful response: 200, AWS Request ID: bf3fdf64-c3da-41b7-9bad-c74f57d93834
INFO: Received successful response: 200, AWS Request ID: 6bdcd7ec-af7f-4a26-a32a-4de92c831654
INFO: Received successful response: 200, AWS Request ID: 9ec38e11-228a-4fb6-963e-c1e30357c1c7
INFO: Received successful response: 200, AWS Request ID: 4e4f05a8-8860-4d8b-a12c-da3cfe058e0a
INFO: Received successful response: 200, AWS Request ID: a45eaba9-5212-4cd2-8861-42cff49c2c85
>>> d.attachVolset()
Feb 6, 2011 3:21:33 PM com.amazonaws.http.HttpClient execute
INFO: Received successful response: 200, AWS Request ID: a5660cbe-2af5-41e6-9fce-b3cbc55e4e91
INFO: Received successful response: 200, AWS Request ID: 684b9c2d-9145-4601-9615-d7375d9fabf6
INFO: Received successful response: 200, AWS Request ID: 7ba9818d-9fda-4e2e-a448-522150288fae
INFO: Received successful response: 200, AWS Request ID: 258e5530-36a6-4641-8f8d-fe24fa03535a
INFO: Received successful response: 200, AWS Request ID: fbcb1f93-50dc-408b-95a3-71a31416e616
INFO: Received successful response: 200, AWS Request ID: fed78d01-2ca5-4621-b5ba-40a395127255
>>> d.instance.getBlockDeviceMappings()
>>> d.instanceId
>>> d.pickle()

Mission accomplished, but not without some caveats. We specified the availability zone for our volumes, but not our instance - see the error at line 18. Oops. The nice thing about writing this up is that my oversight gives me a chance to show how easy it is to clean things up when using the REPL. Simply change the zone, reset the volume state (lines 22-24) and we're back in business. I cleaned up the volumes in the wrong zone using the console.

You'll also notice that when we checked the blockDeviceMapping to see if our attachment succeeded, it showed an empty array. That's a caching artifact, which also bit us at line 6 if you were paying attention. The instance was actually running, or our volume attachment would have failed. Just to prove it worked, we check the shell.

julstad$ ec2-describe-instances i-17a7c27b
RESERVATION     r-4635f02b      923332273044    web
INSTANCE        i-17a7c27b      ami-e4a3578d       ip-10-116-161-3.ec2.internal        running redacted  0               m1.large        2011-02-06T21:18:55+0000        us-east-1c      aki-427d952b                        monitoring-disabled                    ebs        paravirtual
BLOCKDEVICE     /dev/sda1       vol-e876ee80    2011-02-06T21:19:04.000Z
BLOCKDEVICE     /dev/sdf        vol-5477ef3c    2011-02-06T21:21:28.000Z
BLOCKDEVICE     /dev/sdg        vol-5677ef3e    2011-02-06T21:21:28.000Z
BLOCKDEVICE     /dev/sdh        vol-2877ef40    2011-02-06T21:21:29.000Z
BLOCKDEVICE     /dev/sdi        vol-2a77ef42    2011-02-06T21:21:29.000Z
BLOCKDEVICE     /dev/sdj        vol-2c77ef44    2011-02-06T21:21:29.000Z
BLOCKDEVICE     /dev/sdk        vol-2e77ef46    2011-02-06T21:21:29.000Z

Yep - they're there. The next iteration of this code will need to specify the availability zone for the instance as well as call back to EC2 to refresh the instance state. It would also be nice to have it poll until the state changes to running and create and/or attach the volumes at that point. Even better would be using a Java SSH client to mount them on the host automatically after attachment. That will remain a future exercise.

Hopefully you get the idea from this series how handy jython and the REPL can be when working with java API's as well as the gist of using the EC2 API.

Jeremy Ulstad

Dad, IT Architect, Hack Musician, Sailor

Minneapolis, Minnesota