The EC2 create-image API/command/console action is a convenient trigger to create an AMI from a running (or stopped) EBS boot instance. It takes a snapshot of the instance’s EBS volume(s) and registers the snapshot as an AMI. New instances can be run of this AMI with their starting state almost identical to the original running instance.

For years, I’ve been propagating the belief that a create-image call against a running instance is equivalent to these steps:

  1. stop
  2. register-image
  3. start

However, through experimentation I’ve found that though create-image is similar to the above, it doesn’t have all of the effects that a stop/start has on an instance.

Specifically, when you trigger create-image,

  • the Elastic IP address is not disassociated, even if the instance is not in a VPC,

  • the Internal IP address is preserved, and

  • the ephemeral storage (often on /mnt) is not lost.

I have not tested it, but I suspect that a new billing hour is not started with create-image (as it would be with a stop/start).

So, I am now going to start saying that create-image is equivalent to:

  1. shutdown of the OS without stopping the instance - there is no way to do this in EC2 as a standalone operation
  2. register-image
  3. boot of the OS inside the still running instance - also no way to do this yourself.

or:

create-image is a reboot of the instance, with a register-image API call at the point when the OS is shutdown

As far as I’ve been able to tell, the instance stays in the running state the entire time.

I’ve talked before about the difference between a reboot and a stop/start on EC2.

Note: If you want to create an image (AMI) from your running instance, but can’t afford to have it reboot and be out of service for a few minutes, you can specify the no-reboot option.

There is a small risk of the new AMI having a corrupt file system in the rare event that the snapshot was created while the file system on the boot volume was being modified in an unstable state, but I haven’t heard of anybody actually getting bit by this.

If it is important, test the new AMI before depending on it for future use.

use concurrent AWS command line requests to search the world for your instance, image, volume, snapshot, …

Background

Amazon EC2 and many other AWS services are divided up into various regions across the world. Each region is a separate geographic area and is completely independent of other regions.

Though this is a great architecture for preventing global meltdown, it can occasionally make life more difficult for customers, as we must interact with each region separately.

One example of this is when we have the id for an AMI, instance, or other EC2 resource and want to do something with it but don’t know which region it is in.

This happens on ServerFault when a poster presents a problem with an instance, provides the initial AMI id, but forgets to specify the EC2 region. In order to find and examine the AMI, you need to look in each region to discover where it is.

Performance

You’ll hear a repeating theme when discussing performance in AWS:

To save time, run API requests concurrently.

This principle applies perfectly when performing requests across regions.

Parallelizing requests may seem like it would require an advanced programming language, but since I love using command line programs for simple interactive AWS tasks, I’ll present an easy mechanism for concurrent processing that works in bash.

Example

The following sample code finds an AMI using concurrent aws-cli commands to hit all regions in parallel.

id=ami-25b01138 # example AMI id
type=image # or "instance" or "volume" or "snapshot" or ...

regions=$(aws ec2 describe-regions --output text --query 'Regions[*].RegionName')
for region in $regions; do
    (
     aws ec2 describe-${type}s --region $region --$type-ids $id &>/dev/null && 
         echo "$id is in $region"
    ) &
done 2>/dev/null; wait 2>/dev/null

This results in the following output:

ami-25b01138 is in sa-east-1

By running the queries concurrently against all of the regions, we cut the run time by almost 90% and get our result in a second or two.

Drop this into a script, add code to automatically detect the type of the id, and you’ve got a useful command line tool… which you’re probably going to want to immediately rewrite in Python so there’s not quite so much forking going on.

configure your own ssh username in user-data

The official Ubuntu AMIs create a default user with the username ubuntu which is used for the initial ssh access, i.e.:

ssh ubuntu@<HOST>

You can create other users with your preferred usernames using standard Linux commands, but it is difficult to change the ubuntu username while you are logged in to that account since that is one of the checks made by usermod:

$ usermod -l myname ubuntu
usermod: user ubuntu is currently logged in

There are a couple ways to change the username of the default user on a new Ubuntu instance; both passing in special content for the user-data.

Approach 1: CloudInit cloud-config

The CloudInit package supports a special user-data format where you can pass in configuration parameters for the setup. Here is sample user-data (including the comment-like first line) that will set up the first user as ec2-user instead of the default ubuntu username.

#cloud-config
system_info:
  default_user:
    name: ec2-user

Here is a complete example using this cloud-config approach. It assumes you have already uploaded your default ssh key to EC2:

username=ec2-user
ami_id=ami-6d0c2204 # Ubuntu 13.10 Saucy
user_data_file=$(mktemp /tmp/user-data-XXXX.txt)

cat <<EOF >$user_data_file
#cloud-config
system_info:
  default_user:
    name: $username
EOF

instance_id=$(aws ec2 run-instances --user-data file://$user_data_file --key-name $USER --image-id $ami_id --instance-type t1.micro --output text --query 'Instances[*].InstanceId')
rm $user_data_file
echo instance_id=$instance_id

ip_address=$(aws ec2 describe-instances --instance-ids $instance_id --output text --query 'Reservations[*].Instances[*].PublicIpAddress')
echo ip_address=$ip_address

ssh ec2-user@$ip_address

The above cloud-config options do not seem to work for some older versions of Ubuntu including Ubuntu 12.05 LTS Precise, so here is another way to accomplish the same functionality…

Approach 2: user-data script

If you are using an older version of Ubuntu where the above cloud-config approach does not work, then you can change the default ubuntu user to a different username in a user-data script using standard Linux commands.

This approach is also useful if you are already using user-data scripts to do other initialization so you don’t have to mix shell commands and cloud-config directives.

Here’s a sample user-data script that renames the ubuntu user so that you ssh to ec2-user instead.

#!/bin/bash -ex
user=ec2-user
usermod  -l $user ubuntu
groupmod -n $user ubuntu
usermod  -d /home/$user -m $user
if [ -f /etc/sudoers.d/90-cloudimg-ubuntu ]; then
  mv /etc/sudoers.d/90-cloudimg-ubuntu /etc/sudoers.d/90-cloud-init-users
fi
perl -pi -e "s/ubuntu/$user/g;" /etc/sudoers.d/90-cloud-init-users

Here is a complete example using this user-data script approach. It assumes you have already uploaded your default ssh key to EC2:

username=ec2-user
ami_id=ami-6d0c2204 # Ubuntu 13.10 Saucy
user_data_file=$(mktemp /tmp/user-data-XXXX.txt)

cat <<EOF >$user_data_file
#!/bin/bash -ex
user=$username
usermod  -l \$user ubuntu
groupmod -n \$user ubuntu
usermod  -d /home/\$user -m \$user
if [ -f /etc/sudoers.d/90-cloudimg-ubuntu ]; then
  mv /etc/sudoers.d/90-cloudimg-ubuntu /etc/sudoers.d/90-cloud-init-users
fi
perl -pi -e "s/ubuntu/\$user/g;" /etc/sudoers.d/90-cloud-init-users
EOF

instance_id=$(aws ec2 run-instances --user-data file://$user_data_file --key-name $USER --image-id $ami_id --instance-type t1.micro --output text --query 'Instances[*].InstanceId')
rm $user_data_file
echo instance_id=$instance_id

ip_address=$(aws ec2 describe-instances --instance-ids $instance_id --output text --query 'Reservations[*].Instances[*].PublicIpAddress')
echo ip_address=$ip_address

ssh ec2-user@$ip_address

If you include this code in another user-data script, you may want to change the username towards the beginning of the script so that you can log in and monitor progress of the rest of the script.

Clean Up

When you’re done testing, terminate each demo instance.

aws ec2 terminate-instances --instance-ids "$instance_id" --output text --query 'TerminatingInstances[*].CurrentState.Name'

The sample commands in this demo require you to install the aws-cli tool.

Each AMI publisher on EC2 decides what user (or users) should have ssh access enabled by default and what ssh credentials should allow you to gain access as that user.

For the second part, most AMIs allow you to ssh in to the system with the ssh keypair you specified at launch time. This is so common, users often assume that it is built in to EC2 even though it must be enabled by each AMI provider.

Unfortunately, there is no standard ssh username that is used to access EC2 instances across operating systems, distros, and AMI providers.

Here are some of the ssh usernames that I am aware of at this time:

OS/Distro Official AMI
ssh Username
Legacy / Community / Other AMI
ssh Usernames
Amazon Linux ec2-user
Ubuntu ubuntu root
Debian admin root
RHEL 6.4 and later ec2-user
RHEL 6.3 and earlier root
Fedora ec2-user root
Centos root
SUSE root
BitNami bitnami
TurnKey root
NanoStack ubuntu
FreeBSD ec2-user
OmniOS root

Even though the above list will get you in to most official AMIs, there may still be situations where you aren’t quite sure how the AMI was built or what user should be used for ssh.

If you know you have the correct ssh key but don’t know the username, this code can be used to try a number of possibilities, showing which one(s) worked:

host=<IP_ADDRESS>
keyfile=<SSH_KEY_FILE.pem>

for user in root ec2-user ubuntu admin bitnami
do
  if timeout 5 ssh -i $keyfile $user@$host true 2>/dev/null; then
    echo "ssh -i $keyfile $user@$host"
  fi
done

Some AMIs are configured so that an ssh to root@ will output a message informing you the correct user to use and then close the connection. For example,

$ ssh root@<UBUNTUHOST>
Please login as the user "ubuntu" rather than the user "root".

When you ssh to a username other than root, the provided user generally has passwordless sudo access to run commands as the root user. You can use sudo, ssh, and rsync with EC2 hosts in this configuration.

If you know of other common ssh usernames from popular AMI publishers, please add notes in the comments with a link to the appropriate documentation.

Worth switching.

Amazon shared that the new c3.* instance types have been in high demand on EC2 since they were released.

I finally had a minute to take a look at the specs for the c3.* instances which were just announced at AWS re:Invent, and it is obvious why they are popular and why they should probably be even more popular than they are.

Let’s just take a look at the cheapest of these, the c3.large, and compare it to the older generation c1.medium, which is similar in price:

c1.medium c3.large difference
Virtual Cores 2 2
Core Speed 2.5 3.5 +40%
Effective Compute Units 5 7 +40%
Memory 1.7 GB 3.75 GB +120%
Ephemeral Storage 350 GB 32 GB SSD -90%, but much faster
Hourly on-demand Cost (us-east-1) $0.145 $0.15 +3.4%

To summarize:

The c3.large is 40% faster and has more than double the memory than the c1.medium but costs about the same!

In fact, you only pay 12 cents more per day in us-east-1 for the much better c3.large.

I have been a fan of c1.medium for years, but there does not appear to be any reason to use it any more. I’m moving mine to c3.large.

If Amazon does not drastically drop the price on the c1.medium, then it would look like they might be trying to move folks off of the previous generation so that they can retire old hardware and make room in their data centers for newer, faster hardware.

While we’re at it, here’s a comparison of the old c1.xlarge with the new c3.2xlarge which are also about the same cost with similar benefits for switching:

c1.xlarge c3.2xlarge difference
Virtual Cores 8 8
Core Speed 2.5 3.5 +40%
Effective Compute Units 20 28 +40%
Memory 7 GB 15 GB +114%
Ephemeral Storage 1680 GB 160 GB SSD -90%, but much faster
Hourly on-demand Cost (us-east-1) $0.58 $0.60 +3.4%

In completely unrelated news… I’m selling some c1.medium Reserved Instances on the Reserved Instance Marketplace in case anybody is interested in buying them.

Here’s a useful tip mentioned in one of the sessions at AWS re:Invent this year.

There is a little known API call that lets you query some of the EC2 limits/attributes in your account. The API call is DescribeAccountAttributes and you can use the aws-cli to query it from the command line.

For full JSON output:

aws ec2 describe-account-attributes

To query select limits/attributes and output them in a handy table format:

attributes="max-instances max-elastic-ips vpc-max-elastic-ips"
aws ec2 describe-account-attributes --region us-west-2 --attribute-names $attributes --output table --query 'AccountAttributes[*].[AttributeName,AttributeValues[0].AttributeValue]'

Note that the limits vary by region even for a single account, so you can add the --region option:

regions=$(aws ec2 describe-regions --output text --query 'Regions[*].RegionName')
attributes="max-instances max-elastic-ips vpc-max-elastic-ips"
for region in $regions; do
  echo; echo "region=$region"
  aws ec2 describe-account-attributes --region $region --attribute-names $attributes --output text --query 'AccountAttributes[*].[AttributeName,AttributeValues[0].AttributeValue]' |
    tr '\t' '=' | sort
done

Here’s sample output of the above command for a basic account:

region=eu-west-1
max-elastic-ips=5
max-instances=20
vpc-max-elastic-ips=5

region=sa-east-1
max-elastic-ips=5
max-instances=20
vpc-max-elastic-ips=5

region=us-east-1
max-elastic-ips=5
max-instances=20
vpc-max-elastic-ips=5

region=ap-northeast-1
max-elastic-ips=5
max-instances=20
vpc-max-elastic-ips=5

region=us-west-2
max-elastic-ips=5
max-instances=20
vpc-max-elastic-ips=5

region=us-west-1
max-elastic-ips=5
max-instances=20
vpc-max-elastic-ips=5

region=ap-southeast-1
max-elastic-ips=5
max-instances=20
vpc-max-elastic-ips=5

region=ap-southeast-2
max-elastic-ips=5
max-instances=20
vpc-max-elastic-ips=5

My favorite session at AWS re:Invent was James Saryerwinnie’s clear, concise, and informative tour of the aws-cli (command line interface), which according to GitHub logs he is enhancing like crazy.

I just learned about a recent addition to aws-cli: The --query option lets you specify what parts of the response data structure you want output.

Instead of wading through pages of JSON output, you can select a few specific values and output them as JSON, table, or simple text. The new --query option is far easier to use than jq, grep+cut, or Perl, my other fallback tools for parsing the output.

aws --query Examples

The following sample aws-cli commands use the --query and --output options to extract the desired output fields so that we can assign them to shell variables:

Run a Ubuntu 12.04 Precise instance and assigns the instance id to a shell variable:

instance_id=$(aws ec2 run-instances --region us-east-1 --key $USER --instance-type t1.micro --image-id ami-d9a98cb0 --output text --query 'Instances[*].InstanceId')
echo instance_id=$instance_id

Wait for the instance to leave the pending state:

while state=$(aws ec2 describe-instances --instance-ids $instance_id --output text --query 'Reservations[*].Instances[*].State.Name'); test "$state" = "pending"; do
  sleep 1; echo -n '.'
done; echo " $state"

Get the IP address of the running instance:

ip_address=$(aws ec2 describe-instances --instance-ids $instance_id --output text --query 'Reservations[*].Instances[*].PublicIpAddress')
echo ip_address=$ip_address

Get the ssh host key fingerprints to compare at ssh time (might take a few minutes for this output to be available):

aws ec2 get-console-output --instance-id $instance_id --output text |
  perl -ne 'print if /BEGIN SSH .* FINGERPRINTS/../END SSH .* FINGERPRINTS/'

ssh to the instance. Check the prompted ssh host key fingerprint against the output above:

ssh ubuntu@$ip_address

Don’t forget to terminate the demo instance:

aws ec2 terminate-instances --instance-ids "$instance_id" --output text --query 'TerminatingInstances[*].CurrentState.Name'

The addition of the --query option greatly improves what was already a fantastic tool in aws-cli.

Note: The commands in this article assume you have already:

use aws-cli to extend expiration and restart the delete or archive countdown on objects in an S3 bucket

Background

S3 buckets allow you to specify lifecycle rules that tell AWS to automatically delete or archive any objects in that bucket after a specific number of days. You can also specify a prefix with each rule so that different objects in the same bucket stay for different amounts of time.

Example 1: I created a bucket named logs.example.com (not the real name) that automatically archives an object to AWS Glacier after it has been sitting in S3 for 90 days.

Example 2: I created a bucket named tmp.example.com (not the real name) that automatically delete a file after it has been sitting there for 30 days.

This works great until you realize that there are specific files that you want to keep around for just a bit longer than its original expiration.

You could download and then upload the object to reset its creation date, thus starting the countdown from zero; but through a little experimentation, I found that one easy way to reset the creation/modification timestamp on an S3 object is to ask S3 to change the object storage method to the same storage method it currently has.

The following example uses the new aws-cli command line tool to reset the timestamp of an S3 object, thus restarting the lifecycle counter. This has an effect similar to the Linux/Unix touch command.

Setup

Create a test S3 bucket and add a lifecycle to delete any object that is over 1 day old.

bucket=tmp-test.alestic.com
aws s3 mb s3://$bucket
aws s3api put-bucket-lifecycle --bucket $bucket --lifecycle-configuration '{"Rules":{"Status":"Enabled","Prefix":"","Expiration":{"Days":1}}]}'

Upload a test file.

file=somefile.txt
aws s3 cp $file s3://$bucket/

Look at the timestamp on the test file in the test bucket.

aws s3 ls s3://$bucket

Wait a bit (seconds, hours, whatever).

Reset S3 Object Timestamp

Modify the timestamp on the file to be the current time, by telling Amazon to change the storage class to the current storage class. If you are storing objects with REDUCED-REDUNDANCY storage, then specify that instead of STANDARD.

aws s3api copy-object --storage-class STANDARD --copy-source $bucket/$file --bucket $bucket --key $file

Look at the timestamp again, to make sure it has been updated.

aws s3 ls s3://$bucket

The response JSON from the copy-object command will tell you the new expiration date.

Cleanup

If you followed the above commands to create a temporary test file and bucket, you can delete the file by waiting a couple days for it to expire, or run this:

aws s3 rm s3://$bucket/$file

Delete the (empty) bucket using:

aws s3 rb s3://$bucket

Notes

  • With the sample 1 day expiration, S3 lifecycle does not expire the file at exactly 24 hours, but rather rounds up to the next UTC midnight then deletes it at some point after that.

  • Amazon may decide at some point to not change the timestamp when the storage class does not actually change. The above approach works today, but has no warranty.

consistent control over more AWS services with aws-cli, a single, powerful command line tool from Amazon

Readers of this tech blog know that I am a fan of the power of the command line. I enjoy presenting functional command line examples that can be copied and pasted to experience services and features.

The Old World

Users of the various AWS legacy command line tools know that, though they get the job done, they are often inconsistent in where you get them, how you install them, how you pass options, how you provide credentials, and more. Plus, there are only tool sets for a limited number of AWS services.

I wrote an article that demonstrated the simplest approach I use to install and configure the legacy AWS command line tools, and it ended up being extraordinarily long.

I’ve been using the term “legacy” when referring to the various old AWS command line tools, which must mean that there is something to replace them, right?

The New World

The future of the AWS command line tools is aws-cli, a single, unified, consistent command line tool that works with almost all of the AWS services.

Here is a quick list of the services that aws-cli currently supports: Auto Scaling, CloudFormation, CloudSearch, CloudWatch, Data Pipeline, Direct Connect, DynamoDB, EC2, ElastiCache, Elastic Beanstalk, Elastic Transcoder, ELB, EMR, Identity and Access Management, Import/Export, OpsWorks, RDS, Redshift, Route 53, S3, SES, SNS, SQS, Storage Gateway, Security Token Service, Support API, SWF, VPC.

Support for the following appears to be planned: CloudFront, Glacier, SimpleDB.

aws-cli is currently in “developer preview” as it is still being built and has some rough edges, but progress is being made steadily and I’ve already found it extremely useful, especially as it supports AWS services that have no other command line tools.

The aws-cli software is being actively developed as an open source project on Github, with a lot of support from Amazon. You’ll note that the biggest contributors to aws-cli are Amazon employees with Mitch Garnaat leading. Mitch is also the author of boto, the amazing Python library for AWS.

Installing aws-cli

I recommend reading the aws-cli documentation as it has complete instructions for various ways to install and configure the tool, but for convenience, here are the steps I use on Ubuntu:

sudo apt-get install -y python-pip
sudo pip install awscli

Add your Access Key ID and Secret Access Key to$HOME/.aws-config using this format:

[default]
aws_access_key_id = <access key id>
aws_secret_access_key = <secret access key>
region = us-east-1

Protect the config file:

chmod 600 $HOME/.aws-config

Set an environment variable pointing to config file. For future convenience, also add this line to your $HOME/.bashrc

export AWS_CONFIG_FILE=$HOME/.aws-config

Now, wasn’t that a lot easier than installing and configuring all of the old tools?

Testing

Test your installation and configuration:

aws ec2 describe-regions

The default output is in JSON. You can try out other output formats:

 aws ec2 describe-regions --output text
 aws ec2 describe-regions --output table

I posted this brief mention of aws-cli because I expect some of my future articles are going to make use of it instead of the legacy command line tools.

So go ahead and install aws-cli, read the docs, and start to get familiar with this valuable tool.

Notes

Some folks might already have a command line tool installed with the name “aws”. This is likely Tim Kay’s “aws” tool. I would recommend renaming that to another name so that you don’t run into conflicts and confusion with the “aws” command from the aws-cli software.

[Update 2013-10-09: Rename awscli to aws-cli as that seems to be the direction it’s heading.]

Launch a CloudFormation template to set up a stack of AWS resources to fill a simple need: Supporting Gmail addresses with “-” instead of “+” separating the user name from the arbitrary tag strings.

The CloudFormation stack launched by the template consists of:

  • ELB (Elastic Load Balancer)
  • Auto Scaling Group
  • EC2 instance(s) running Postfix on Ubuntu set up by a user-data script
  • Security Group allowing ELB to connect to the instances
  • CloudWatch CPU high/low alarms
  • Auto Scaling scale up/down policies.
  • SNS (Simple Notification Service) topic for notification of Auto Scaling events
  • Route53 Record Set

This basic stack structure can be used as a solution for a large number of different needs, but in this example it is set up as an SMTP email relay that filters and translates email addresses for Google Apps for Business customers.

Because it uses Auto Scaling, ELB, and Route53, it is scalable and able to recover from various types of failures.

If you’re in a rush to see code, you can look at the CloudFormation template and the initialization script run from the user-data script.

Now, let’s look a bit more in depth at the problem this is solving and how to set up the solution.

Background

If you have a Gmail address of user@example.com, then email messages sent to addresses of the form user+ANYTHING@example.com will also be delivered to you. You can use any email address string after the plus sign.

Google describes this feature in a blog post:

Append a plus (“+”) sign and any combination of words or numbers after your email address. For example, if your name was hikingfan@gmail.com, you could send mail to hikingfan+friends@gmail.com or hikingfan+mailinglists@gmail.com

This is is useful for tracking where you have entered your email address and findingout which services allow it to be used for spam. If an email variation starts getting abused, you can automatically filter it out in Gmail.

The Problem

Unfortunately, many web sites do not allow an email address with a “+” when registering and will reject any attempts to use this. I don’t know if they are trying to prevent people from using unique tracking addresses or if they just don’t know the specification for a valid email address, but the end result is the same.

If we could just use a dash (-) instead of a plus, we could enter unique tracking email addresses in each site registration.

Another example for why plus can be bad: My son added “+psat” to his email address when filling out the written PSAT so he could track who they sold his email address to (apparently every college out there). The data entry person typed a “t” instead of a “+”, so colleges started sending emails to the wrong address.

Prerequisites

The approach presented here works with custom domains set up with Google Apps for Business. You can’t use it for individual, free “@gmail.com” addresses without some additional work and a separate domain name registration.

As currently written, the CloudFormation stack requires that you already have your domain DNS handled by Route53, as the template will insert a new DNS entry for the email relay. This functionality could be removed from the template if you don’t use Route53.

The Solution

This CloudFormation template sets up a stack that will translate email addresses when Gmail forwards messages for unknown users (with dashes in the address).

After this is set up, email delivered to Gmail for the standard and plus domain email addresses, say user@example.com and user+ANYTHING@example.com, will still be processed exactly as they were before. This stack does not interfere with that operation.

When email is addressed to the new dash form, like user-ANYTHING@example.com, Gmail will not be able to find the user, and will forward this to the email relay set up by the CloudFormation template.

The email relay will translate the dash in user-ANYTHING@example.com back to a plus as user+ANYTHING@example.com and relay the message back to Gmail for standard delivery to the user.

Architecture

The Route53 DNS name is set to point at the ELB. The Load Balancer is listening on the SMTP (email) port and forwards connections to the instance(s) in the Auto Scaling group.

The Auto Scaling group make sure that there is at least 1 (or the min you specify) instance running and will replace failed instances. It also monitors the CPU usage on the instances and scales up (and down) more instances as specified.

When an instance is started by the Auto Scaling group, it runs the user-data script which installs and configures Postfix to accept email for users at the configured domain. The Postfix configuration then replaces the dash with a plus and submits the message back to the standard MX servers for the domain (e.g., Gmail).

When a scaling event happens, the SNS topic is notified which triggers an email to the address provided to the template. Other addresses and listeners can be subscribed to and unsubscribed from the SNS topic.

You get to pick the instance type, min, and max when you run the template, so that you can meet your company’s volume and cost needs.

Now, let’s look at how to set it all up.

Step 1: Launch CloudFormation Stack

You can run the CloudFormation template with the AWS console or with the command line. To run it through the AWS Console in the us-east-1 region, simply click this button:

Launch Stack

Fill out the template parameters and launch the stack. Once it’s running, follow the Google Apps Setup below.

If you have installed the AWS command line tools, then you can launch the stack in us-west-2 using commands like:

dnsdomain=example.com
dnshost=email-relay-dash-to-plus
ssh_key_name=$USER  # Your ssh keypair name here
notification_email=${DEBEMAIL:-${EMAIL:?Please_Set}}
instance_type=t1.micro
min_instances=1
max_instances=2
stackname="example-$host-$(date +%Y%m%d-%H%M)"
region=us-west-2

wget http://run.alestic.com.s3.amazonaws.com/cloudformation/email-relay-dash-to-plus.template
cfn-create-stack   --region $region   --stack-name "$stackname"   --template-file email-relay-dash-to-plus.template   --parameters "InstanceType=$instance_type;OperatorEmail=$notification_email;SshKeyName=$ssh_key_name;DnsDomain=$dnsdomain;DnsHostName=$dnshost;MinInstances=$min_instances;MaxInstances=$max_instances"

Once it’s running, follow the Google Apps Setup below.

Step 2: Configure Google Apps

Once the stack is running, configure Google Apps to forward unrecognized email addresses to the email relay:

  • Log in to administer your domain in Google Apps

  • Select “Google Apps”

  • Select “Gmail”

  • Select “Advanced”

  • Scroll down to “Email Routing”

  • Select “Add Another Destination”

  • In the “Destination:” field, add the hostname.domainname of your email relay access (e.g., email-relay-dash-to-plus.example.com)

  • Leave this option selected: (X) “Unknown mailbox accounts only”

Note: If Gmail forwards an unknown email address without a dash, the relay will simply reject it as unknown. This should not cause problems unless you need other unknown email address processing.

Step 3: Test

Make sure you can send email to allow of the following forms and have it delivered to the same user:

  • user@example.com
  • user+ANYTHING@example.com
  • user-ANYTHING@example.com

Cleanup

If you are just testing this out, don’t forget to delete the CloudFormation stack using the AWS console, or on the command line with:

cfn-delete-stack --region $region --force --stack-name "$stackname"

Notes

  • Though I am using this setup for a low-volume domain under Google Apps for Business, it may not work for every domain with high volume or other odd configurations. Please review the code and test to make sure it does what you need.

  • This CloudFormation stack tells AutoScaling to initialize each instance with a script that is downloaded from the GitHub repository for this project. You can remove your dependency on that repository (which may change as the software is improved) by copying the script to your own location (e.g., S3) and providing that URL in the CloudFormation template’s InitializationScriptURL parameter.

  • The Auto Scaling policies have not ben tested extensively. You may need to adjust them for scaling under real world load.

I’d be extremely curious to know if anybody actually runs one of these CloudFormation stacks and gets it to work—or where you had trouble. I’d also like to know your level of interest in CloudFormation and how much experience you’ve had with it. Would further CloudFormation articles be useful? At what level (beginner, intermediate, expert)?

Update 2012-07-22: @pmocek on Twitter points out that “-” is called a hyphen or a minus, not a dash.