At this month‘s St. Louis Cloud Computing User Group a question was posed:

What does Reservation id mean when an AMI instance is provisioned? And what is it’s use?

If you do not know what I’m talking about, see the following command ec2-run-instances (and it’s output) which is used to launch any number of instances of a specified Amazon AMI:

roshan@roshan:~/.ec2$ ec2-run-instances ami-cddf39a4  
[Deprecated] Xalan: org.apache.xml.res.XMLErrorResources_en_US
RESERVATION r-06acd26e 365788654425 default
INSTANCE i-2358b248 ami-cddf39a4 pending roshmac-keypair 0 m1.small 2010-02-19T15:04:28+0000 us-east-1d windows monitoring-disabled instance-store

In the above output the RESERVATION ID is r-06acd26e.

At the meeting I attempted to answer that question by waving my arms in a very mumbo jumbo sort of way. Pretty much like how those marketing/sales guys you meet do :) (j/k)
I did not make sense at all. Therefore I decided to spend some time putting my thoughts down in this post.

Reservation
A reservation in the above context is an atomic launch of one or many instances. One reservation does not imply a single reserved instance. For example, if you launch 1 instance, you get 1 instance ID and 1 reservation ID. If you launch 2 instances in a single ec2-run-instances command, you get 2 instance IDs, but still 1 reservation ID. Likewise if you launch N instances in a single ec2-run-instances command, you still get only 1 reservation ID.

Use
Since a reservation is an atomic launch and the reservation id serves as an identifier to a group of instances, you could use it, for instance, to terminate the entire reservation of instances. The attached Scala script does just that! It takes a reservation id as a parameter, gets the list of instances in that reservation and then terminates those instances. This script saves you the trouble of terminating each instance manually.

Let’s see this script (using reservation id) in action. Let’s start 5 instances of an AMI.

roshan@roshan:~/.ec2$ ec2-run-instances ami-cddf39a4 -n 5
[Deprecated] Xalan: org.apache.xml.res.XMLErrorResources_en_US
RESERVATION r-72feba1a 365788654425 default
INSTANCE i-f1ac539a ami-cddf39a4 pending roshmac-keypair 0 m1.small 2010-02-24T04:05:48+0000 us-east-1d windows monitoring-disabled instance-store
INSTANCE i-f7ac539c ami-cddf39a4 pending roshmac-keypair 1 m1.small 2010-02-24T04:05:48+0000 us-east-1d windows monitoring-disabled instance-store
INSTANCE i-f5ac539e ami-cddf39a4 pending roshmac-keypair 2 m1.small 2010-02-24T04:05:48+0000 us-east-1d windows monitoring-disabled instance-store
INSTANCE i-cbac53a0 ami-cddf39a4 pending roshmac-keypair 3 m1.small 2010-02-24T04:05:48+0000 us-east-1d windows monitoring-disabled instance-store
INSTANCE i-c9ac53a2 ami-cddf39a4 pending roshmac-keypair 4 m1.small 2010-02-24T04:05:48+0000 us-east-1d windows monitoring-disabled instance-store

Now, to delete all instances under reservation id r-72feba1a, all I have to do is the following:

roshan@roshan:~/.ec2$ ec2-terminate-reservation r-72feba1a
Instance ids: List(i-c9ac53a2, i-cbac53a0, i-f5ac539e, i-f7ac539c, i-f1ac539a)
INSTANCE i-f7ac539c pending shutting-down
INSTANCE i-c9ac53a2 pending shutting-down
INSTANCE i-f5ac539e pending shutting-down
INSTANCE i-f1ac539a pending shutting-down
INSTANCE i-cbac53a0 pending shutting-down
[Deprecated] Xalan: org.apache.xml.res.XMLErrorResources_en_US

As you can see from the above output of ec2-terminate-reservation, the instances are now in the shutting-down state

ec2-describe-instances confirms that the instances are being shutdown

roshan@roshan:~/.ec2$ ec2-describe-instances 
[Deprecated] Xalan: org.apache.xml.res.XMLErrorResources_en_US
RESERVATION r-36da9e5e 365788654425 default
INSTANCE i-e7728e8c ami-9dde38f4 terminated 0 m1.small 2010-02-24T02:33:32+0000 us-east-1d windows monitoring-disabled instance-store
INSTANCE i-e5728e8e ami-9dde38f4 terminated 1 m1.small 2010-02-24T02:33:32+0000 us-east-1d windows monitoring-disabled instance-store
RESERVATION r-72feba1a 365788654425 default
INSTANCE i-f1ac539a ami-cddf39a4 ec2-184-73-35-115.compute-1.amazonaws.com ip-10-242-193-159.ec2.internal shutting-down roshmac-keypair 0 m1.small 2010-02-24T04:05:48+0000 us-east-1d windows monitoring-disabled 184.73.35.115 10.242.193.159 instance-store
INSTANCE i-f7ac539c ami-cddf39a4 ec2-67-202-43-95.compute-1.amazonaws.com ip-10-243-23-239.ec2.internal shutting-down roshmac-keypair 1 m1.small 2010-02-24T04:05:48+0000 us-east-1d windows monitoring-disabled 67.202.43.95 10.243.23.239 instance-store
INSTANCE i-f5ac539e ami-cddf39a4 ec2-184-73-10-172.compute-1.amazonaws.com ip-10-243-25-175.ec2.internal shutting-down roshmac-keypair 2 m1.small 2010-02-24T04:05:48+0000 us-east-1d windows monitoring-disabled 184.73.10.172 10.243.25.175 instance-store
INSTANCE i-cbac53a0 ami-cddf39a4 ec2-174-129-77-181.compute-1.amazonaws.com ip-10-242-73-220.ec2.internal shutting-down roshmac-keypair 3 m1.small 2010-02-24T04:05:48+0000 us-east-1d windows monitoring-disabled 174.129.77.181 10.242.73.220 instance-store
INSTANCE i-c9ac53a2 ami-cddf39a4 ec2-75-101-231-29.compute-1.amazonaws.com ip-10-242-77-126.ec2.internal shutting-down roshmac-keypair 4 m1.small 2010-02-24T04:05:48+0000 us-east-1d windows monitoring-disabled 75.101.231.29 10.242.77.126 instance-store

How to use ec2-terminate-reservation
Download the attached ec2-terminate-reservation.sh script to your $EC2_HOME/bin directory, rename it to ec2-terminate-reservation and make it executable.

roshan@roshan:~/.ec2$ chmod +x ec2-terminate-reservation

You should have Scala installed and the $SCALA_HOME/bin appended to your PATH for the script to work.

ec2-terminate-reservation