What's New in Euca2ools 3, Part 1: A User's Perspective
Version 3 of euca2ools, slated for release in just a couple months, gives the command line suite a much-needed refresh that makes it both easier to write and easier to use. Most of the innovation here involves changes to the platform upon which it is built. I will cover those changes from a developer’s perspective in future blog posts, but today I’m going to focus on what euca2ools 3 brings to the table for developers and other users alike. While there are too many small improvements to possibly cover them all, euca2ools 3 at last brings a few of the niceties power users have come to expect from their command line tools to cloud management.
A configuration file
Yes, you read that right: a configuration file. Both euca2ools and the command line tools provided by AWS themselves have astonishingly limited support for configuration, forcing people to resort to writing a separate shell script for each combination of users and clouds one might possibly want to access and then use them in place of one.
Your cries of anguish have been heard, so now we have this:
[user gholms]
key-id = AKIA93F29V0AEXAMPLE
secret-key = vcasd93cm1458un4vj84039vda78mDEXAMPLE
[user ecc-admin]
key-id = EVDB93F29V0AEXAMPLE
secret-key = 38fva93cm1458un4vj84039vda78mDEXAMPLE
[region us-east-1]
ec2-url = https://ec2.amazonaws.com/
iam-url = https://iam.amazonaws.com/
s3-url = https://s3.amazonaws.com/
user = gholms
[region ecc]
ec2-url = https://communitycloud.eucalyptus.com:8773/services/Eucalyptus/
iam-url = https://communitycloud.eucalyptus.com:8773/services/Euare/
s3-url = https://communitycloud.eucalyptus.com:8773/services/Walrus/
user = ecc-admin
[global]
default-region = us-east-1
A file like this, combined with the --region
option that all tools share, mean you can mix and match users and clouds to you heart’s content. Just throw a file like this inside of ~/.euca
, end it with .ini
, and away you go! You can add as many files to ~/.euca
as you want — they all get combined together.
Friendly error feedback
Another common complaint that people had with euca2ools 2 was its behavior in the face of input that didn’t match what it expected. Some of the worst offenders had error messages ranging from confusing to irrelevant to nonexistent. Euca2ools 3 overhauls the code that does this, replacing it with standard python tools and friendlier code that makes its behavior in the face of errors much better.
Here’s how it behaves in the face of the most common case of this:
$ euca-describe-availability-zones
error: missing access key ID; please supply one with -I
Also included is special treatment for “pick one from multiple alternatives” options:
$ euare-useraddcert
usage: euare-useraddcert (-c CERT | -f FILE) [-u USER]
[--as-account ACCOUNT] [--region REGION | -U URL]
[-I KEY_ID] [-S KEY]
euare-useraddcert: error: one of the arguments -c/--certificate-body -f/--certificate file is required
A lot of attention to detail went into dealing with some of the most common mistakes people make:
$ euca-register -n myimage -b /dev/sda1=snap-12345678:false
euca-register: error: argument -b/--block-device-mapping: second element of EBS block device mapping "/dev/sda1=snap-00000000:false" must be an integer
$ euca-authorize mygroup -p 8773:8777
euca-authorize: error: argument -p/--port-range: multi-port range must be separated by "-", not ":"
Tagging and filtering support
Euca2ools 3 at last offers full support for EC2’s massive sets of resource tags and filters:
$ euca-describe-instances -h
usage: euca-describe-instances [-h] [--show-empty-fields]
...
--filter NAME=VALUE restrict results to those that meet criteria
...
allowed filter names:
architecture CPU architecture
availability-zone
block-device-mapping.attach-time
volume attachment time
block-device-mapping.delete-on-termination
whether a volume is deleted upon instance
termination
block-device-mapping.device-name
volume device name (e.g. /dev/sdf)
block-device-mapping.status
volume status
block-device-mapping.volume-id
volume ID
client-token idempotency token provided at instance run
time
dns-name public DNS name
group-id security group membership
hypervisor hypervisor type
image-id machine image ID
instance-id
instance-lifecycle whether this is a spot instance
instance-state-code numeric code identifying instance state
instance-state-name instance state
instance-type
ip-address public IP address
kernel-id kernel image ID
key-name key pair name provided at instance launch time
launch-index launch index within a reservation
launch-time instance launch time
monitoring-state whether monitoring is enabled
owner-id instance owner's account ID
placement-group-name
platform whether this is a Windows instance
private-dns-name
private-ip-address
product-code
ramdisk-id ramdisk image ID
reason reason for the more recent state change
requestor-id ID of the entity that launched an instance
reservation-id
root-device-name root device name (e.g. /dev/sda1)
root-device-type root device type (ebs or instance-store)
spot-instance-request-id
state-reason-code reason code for the most recent state change
state-reason-message
message for the most recent state change
subnet-id ID of the VPC subnet the instance is in
tag-key name of any tag assigned to the instance
tag-value value of any tag assigned to the instance
tag:KEY specific tag key/value combination
virtualization-type
vpc-id ID of the VPC the instance is in
The new foundation this code is based upon makes it incredibly simple to extend support for these features as things change in the future.
What else?
Some other minor, but nonetheless noteworthy, changes include:
euca-*
tools gained a--show-empty-fields
option that tweaks their output to make it friendlier for running through thecolumn
command.- All tools that access web services use the same options (
-I
and-S
) for access keys. euare-*
tools’--delegate
option for cloud administrators is now--as-account
.- Multiple
--filter
options are handled correctly. - Machine image device mappings are now handled correctly.
A few tools have yet to be ported to the new framework, but will be in the near future. eustore-installimage
is known to be broken. The bundle management tools should work correctly, though their testing to date has been minimal. Finally, do not install them on a system that runs a Eucalyptus node controller.
Isn’t aws-cli the future? Why continue developing euca2ools?
Aws-cli is a great project. Both it and euca2ools tie what the server sees very closely to what the user sees under the hood, but the euca2ools suite does so in a way that makes it trivial to customize tools to do more complicated things behind the hood or to make them easier to use. For instance, consider changing a security group’s permissions in EC2 with aws-cli:
$ aws ec2 authorize-security-group-ingress --group-name MySecurityGroup --ip-permissions '{"from_port":22,"to_port":22,"ip_protocol":"tcp","ip_ranges":["0.0.0.0/0"]}'
The exact format we need to use to supply the info the tool needs requires relatively detailed knowledge of what EC2-the-server expects. Compared to that, the euca2ools version of that is easier to remember and much easier to type:
$ euca-authorize MySecurityGroup --port 22 --source-subnet 0.0.0.0/0
Aws-cli is a very young project, so people haven’t yet had the chance to iron it out completely. Perhaps some day it will become as user-friendly as euca2ools and finally eclipse it. But we aren’t there yet.
How can I try it out?
If you’re interested in a preview of the next major version of euca2ools, an alpha release is available on GitHub. In addition to the dependencies required to run euca2ools 2, you will also need to install requests and the new requestbuilder framework that drives the new tools. It is still alpha-quality software, so be prepared to find bugs. If you encounter any, feel free to file them in the euca2ools project’s bug tracker.
If you’re interested in helping with development, we are happy to accept pull requests on GitHub. Please also consider joining the euca-users mailing list or stopping by in the #eucalyptus-devel
IRC channel on Freenode. I look forward to hearing your feedback. 8^)