01 January 2012

OpenNebula is a wonderful VEEM (Virtual Execution Environment Manager) and comes with many different drivers to manage Xen, KVM, VMware, Amazon EC2, Hyper-V and even VirtualBox!. After playing for a while with the EC2 driver provided with the standard distribution, I needed it to handle more Amazon Advanced features such as Security Groups, Tags, Virtual Private Cloud (VPC). I needed also the driver to manage Amazon Regions and Datacenter to allow building HA solutions while avoiding extra costs related to network traffic between regions.
So I decided to role up my sleeves and enhance the driver to suit my needs.

EC2 driver attributes

The actual EC2 driver accepts only five attributes in the template definition file. Those attributes are shown below (from OpenNebula documentation).

EC2 = [ AMI="ami-00bafcb5",

The two first attributes are mandatory and the three last ones are optional. I decided to add more optional attributes and the driver now accepts the ones shown in the table below. See Amazon EC2 User Guide for more details on how to use the different ‘ec2-run-instances’ options.

These first enhancements where quite easy to do. The driver just need to parse the definition file, get the data from the XML tree and define new options to the EC2 API Tools commands used by the initial driver.

Tags are really useful when it comes to develop management tools for Amazon EC2. I wanted the new driver to allow reuse of XML attributes from the VM definition file as instance tags. This is really useful to define the AWS Instance Name in the AWS Console from the NAME attribute.

See [Part 2](../Enhancing_OpenNebula_EC2_Driver-part2/) to learn how to use contextualization.
Category Attribute Usage
EC2 AKI Amazon Kernel Image
Example(s): AKI=aki-xxxxxxxx
(ec2-run-instances [GENERAL OPTIONS] $AMI -k $AKI ...)
EC2 AMI The Amazon Image ID to launch. Note that you must define an INSTANCETYPE compatible with the AMI you specify here.
Example(s): AMI=ami-xxxxxxx
(ec2-run-instances [GENERAL OPTIONS] $AMI ...)
EC2 AUTHORIZED_PORTS The ports to authorize on the security group 'default'. I prefer not to use this attribute and rather use SECURITYGROUPS I added, see below.
Example(s): AMI=ami-xxxxxxx
(ec2-run-instances [GENERAL OPTIONS] $AMI ...)
EC2 BLOCKMAPPING Defines a block device mapping for the instance(s), in the form '='
  • BLOCKMAPPING='/dev/sdb=snap-7eb96d16'
  • BLOCKMAPPING='/dev/sdc=snap-7eb96d16:80:false'
  • BLOCKMAPPING='/dev/sdd=:120'

(ec2-run-instances [GENERAL OPTIONS] $AMI -b $BLOCKMAPPING ...)
EC2 CLIENTTOKEN Token for idempotency. Useful to avoid instantiating multiple times the same VM and have to pay for them... not really useful in a template as we want to be able to instantiate a new VM based on a generic template. With this parameter set, AWS will return the state of the machine with the current token. AWS will refuse to create the new instance even if the previous one associated with the token is 'terminated'. You've been warned!
Example(s): CLIENTTOKEN="mytoken"
(ec2-run-instances [GENERAL OPTIONS] $AMI --client-token $CLIENTTOKEN ...)
EC2 ELASTICIP The Elastic IP address to associate to the instance. Note that the instance must be in running state for the ec2-associate-address to work. See the WAITFORINSTANCE attribute.
Example(s): ELASTICIP=eip-alloc-xxxxxxxx
(ec2-associate-address -a $ELASTICIP -i $INSTANCEID ...)
EC2 INSTANCETYPE Specifies the type of instance to launch.
Example(s): INSTANCETYPE=t1.micro
(ec2-run-instances [GENERAL OPTIONS] $AMI -t $INSTANCETYPE ...)
EC2 KEYPAIR The SSH keypair to inject in the instance. The keypair must already be defined in your EC2 environment.
Example(s): KEYPAIR=mykeypair
(ec2-run-instances [GENERAL OPTIONS] $AMI -k $KEYPAIR ...)
EC2 LICENSEPOOL Specifies the license pool to use when launching the instance(s).
Example(s): not tried yet, look in EC2 UserGuide for example and please let me know!
(ec2-run-instances [GENERAL OPTIONS] $AMI --license_pool $LICENSEPOOL ...)
EC2 NETWORKINTERFACE Specifies the Elastic Network Interface to connect to the instance. This options option requires EC2 API Tools or higher.
Example(s): NETWORKINTERFACE="eni-xxxxxxxx:0" all attempts to use this option while running ec2-run-instance directly from the command line failed... I suspect a bug in the ec2-run-instance code or the feature not implemented yet in region EU-WEST-1 because the option is silently ignored. If you succeed please let me know!
(ec2-run-instances [GENERAL OPTIONS] $AMI -a $NETWORKINTERFACE ...)
EC2 PLACEMENTGROUP Specifies the placement group into which the instances should be launched.
Example(s): not tried yet, look in EC2 UserGuide for example and please let me know!
(ec2-run-instances [GENERAL OPTIONS] $AMI --placement-group $PLACEMENTGROUP ...)
EC2 PRIVATEIP Specifies the private IP address to use when launching an Amazon VPC instance.
Example(s): AKI=aki-47eec433
(ec2-run-instances [GENERAL OPTIONS] $AMI --private-ip-address $PRIVATEIP ...)
EC2 RAMDISK Specifies the ID of the ramdisk to launch the instance(s) with.
Example(s): not tried yet, look in EC2 UserGuide for example and please let me know!
(ec2-run-instances [GENERAL OPTIONS] $AMI --ramdisk $RAMDISK ...)
EC2 SOURCEDESTCHECK Sets whether to enable the source/dest check on traffic through this network interface. Useful if you want to create a NAT instance in EC2. This options option requires EC2 API Tools or higher.
Example(s): SOURCEDESTCHECK=false
(ec2-modify-network-interface-attribute [GENERAL OPTIONS] $ENI_ID --source-dest-check $SOURCEDESTCHECK)
EC2 SECURITYGROUPS Specifies the security group (or groups if specified multiple times) within which the instance(s) should be run. Determines the ingress firewall rules that will be applied to the launched instances. Defaults to the user's default group if not supplied.
Example(s): SECURITYGROUPS=Group1,Group2,...
(ec2-run-instances [GENERAL OPTIONS] $AMI -g Group1, -g Group2, ...)
EC2 SUBNETID The ID of the Amazon VPC subnet in which to launch the instance(s).
Example(s): SUBNETID=subnet-xxxxxxxx
(ec2-run-instances [GENERAL OPTIONS] $AMI -g Group1, -g Group2, ...)
EC2 TAGS A comma separated list of Key=Value tags.
Example(s): "Name=$NAME, Description=\"My Description\", VMID=$VMID, TEMPLATE_ID=$TEMPLATE_ID, CREATED_BY=$USERNAME"
(ec2-create-tags [GENERAL OPTIONS] INSTANCEID --tag Key1=Val1, --tag Key2=Val2, ...)
EC2 TENANCY Specifies the tenancy of an instance, which can be default or dedicated. This option is only available for VPC instances. not tried yet, look in EC2 UserGuide for example and please let me know!
  • TENANCY=default => The default tenancy.
  • TENANCY=dedicated => The instance does not share hardware with instances launched from other accounts (additional charges apply).

(ec2-run-instances [GENERAL OPTIONS] $AMI --tenancy $TENANCY ...)
EC2 VPCID the ID of the Amazon VPC into with instantiate the instance
Example(s): VPCID=vpc-xxxxxxxx
Not used at the moment by the driver as only the SUBNETID is accepted by ec2-run-instances. Might be used in the future in combination with onevnet ...
EC2 WAITFORINSTANCE Trying to associate an elastic IP with an instance that is not yet in 'running' state will generate an error. Under some circumstances I faced this issue so I decided to add this switch. The switch will make the driver enter in a 'ec2-describe-instances' loop until the instance state returned is "running". This will put some load on the OpenNebula frontend as the driver currently relies on the Java EC2 AMI tools and we all know that java requires some CPU cycles...

blog comments powered by Disqus