Publishing image to EC2

This initially will just have the basic steps for creating EBS-backed, custom images. In this document will be refences to running commands from the ec2-api-tools suite; you may quickly find that these tools often do not do things the way you'd like, and find yourself writing your own tools for talking to the REST/Query API or using tools like euca2ools (which is part of the Fedora Cloud_SIG feature list for Fedora 14).

pvgrub

July 15, 2010, was a big "game changer" for AMI images at Amazon, when they announced Enabling User Provided Kernels in Amazon EC2. This allows people to build anything they want on EC2, running their own custom kernels; pv-grub is just a small chainloader (to put it simply).

In the case of EC2, it will either look at (hd0)/boot/grub/menu.lst or (hd0,0)/grub/menu.lst, depending on whether you used the hd0 or hd00 aki. Using the "hd0" image means that pv-grub is expecting /dev/xvda1 to be a partitionless target; the other option, hd00, is "root (hd0,0)" in a standard grub file - meaning, it's pointing to the first partition on the first drive (instead of hd0, the whole drive).

Custom EBS-backed images

Follows is the basic rundown of the steps:

create build instance

This doesn't need to be it's own instance. It can be an instance you already have. It can be anything, so long as it supports the filesystems you will want on your target AMI.

create build target volume

This is the volume the new OS will be installed upon, and of which a snapshot will be created. Make it, attach it to the build host - note the below script has "/dev/sdf" as the target, so it might be easiest to just attach there.

build custom OS

The basic concept here is that we're building a snapshot image within a chroot environment. This is made easy by the yum utilities' "--installroot" option. An overly simple example of a script that will do the entire OS snapshot build for you is the createfedorabootebs.sh script. NOTE: if you're starting from the official Fedora S3-backed AMI, that is a minimal install and does not have e2fsprogs - install that first

If you want to create your own process for creating an OS snapshot, the only difficulty is in the contents of the /boot/grub directory; everything else is extremely simple and more or less just falls in to place without effort.

Within the /boot/grub directory, there needs be only grub.conf and menu.lst; you may experience problems if either one is a symlink instead of a file, so creating one and then making the other a hardlink to the same is the best idea. This can be done with the ln command; simply omit the "-s" that is normally appended, as that flag is for making a soft link (while you want a hard link). Note this means that all the various stage files are not necessary; my personal AMIs run just fine with only 1 file in /boot/grub

Within this one file, note that you want the kernel line to have "root=/dev/xvda1" - despite the fact that you will be telling Amazon to mount the disk at /dev/sda1, and it will claim that's where it is mounted, in reality it will be mounted at /dev/xvda1. This behavior can be changed, but the goal here is a functional AMI; tailoring it further will be up to you.

Finally, since the device is at /dev/xvda1, remember to set the entry in fstab appropriately.

Of course, these steps are done for you in the above script; the script is primarily made available just so people have an idea how to do it themselves, however. It can be used "as-is", the steps all run manually, or adjusted however someone wants. The script is just a simple example of a process that works, feel free to create your own process instead.

Detach volume

This is simple enough; just run

ec2-detach-volume --region region_name volume_id

create snapshot

run:

ec2-create-snapshot --region region_name --description "description" volume_id

Many guides on the inter-tubes will tell you to stop mysql, run rsync, wash your dishes, order some pizza, etc. None of that is necessary here though, because we're not doing the dangerous activity of making a snapshot of a running OS and calling it blessed; we're making a snapshot of an OS that was built inside a chroot environment, which was then unmounted. The filesystems are in a pure, clean, unmounted, happy state. This step can be as fast as just a couple seconds, or it could get stuck in a queue for a couple minutes before completing.

AMI images

The basic components of an AMI are an AKI and a snapshot; we have the snapshot from above, now we need an AKI.

Finding a pvgrub AKI

Regardless how you come up with the snapshot you're using, creating the AMI itself is more or less the same (with only a change to --block-device-mapping necessary for the various storage options). You'll need to know what pv-grub AKI to use. A simple check will tell you what the kernels in your preferred region are:

ec2-describe-images -H --region us-west-1 -x all|grep "pv-grub-hd0"

Creating the AMI

So now you have your snapshot, your AKI...what else do you need? Nothing!

ec2-register --region region_name -n "ShortName" -d "Long Desc" \
--block-device-mapping /dev/sdc=ephemeral0 --snapshot snap-id \
--architecture [i386 | x86_64] --kernel aki-id

now just start an instance using that AMI and all the defaults, et viola!