Creating an AMI from an Instance Store-Backed Instance

The following procedures are for creating an instance store-backed AMI from an instance store-backed instance. Before you begin, ensure that you've read the Prerequisites.

Topics

Creating an AMI from an Instance Store-Backed Amazon Linux Instance
Creating an AMI from an Instance Store-Backed Ubuntu Instance

Creating an AMI from an Instance Store-Backed Amazon Linux Instance

This section describes the creation of an AMI from an Amazon Linux instance. The following procedures may not work for instances running other Linux distributions. For Ubuntu-specific procedures, see Creating an AMI from an Instance Store-Backed Ubuntu Instance.

To prepare to use the Amazon EC2 AMI Tools (HVM instances only)

The Amazon EC2 AMI tools require GRUB Legacy to boot properly. Use the following command to install GRUB:
```
Copy
[ec2-user ~]$ sudo yum install -y grub
```
Install the partition management packages with the following command:
```
Copy
[ec2-user ~]$ sudo yum install -y gdisk kpartx parted
```

To create an AMI from an instance store-backed Linux instance

This procedure assumes that you have satisfied the prerequisites in Prerequisites.

Upload your credentials to your instance. We use these credentials to ensure that only you and Amazon EC2 can access your AMI.
1. Create a temporary directory on your instance for your credentials as follows:
```
Copy
[ec2-user ~]$ mkdir /tmp/cert
```
  This enables you to exclude your credentials from the created image.
2. Copy your X.509 certificate and corresponding private key from your computer to the /tmp/cert directory on your instance using a secure copy tool such as scp. The -i my-private-key.pem option in the following scp command is the private key you use to connect to your instance with SSH, not the X.509 private key. For example:
```
Copy
you@your_computer:~ $ scp -i my-private-key.pem /path/to/pk-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem /path/to/cert-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem ec2-user@ec2-203-0-113-25.compute-1.amazonaws.com:/tmp/cert/
pk-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem  100%  717     0.7KB/s   00:00
cert-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem  100%  685     0.7KB/s   00:00
```
Alternatively, because these are plain text files, you can open the certificate and key in a text editor and copy their contents into new files in /tmp/cert.
Prepare the bundle to upload to Amazon S3 by running the ec2-bundle-vol command from inside your instance. Be sure to specify the -e option to exclude the directory where your credentials are stored. By default, the bundle process excludes files that might contain sensitive information. These files include *.sw, *.swo, *.swp, *.pem, *.priv, *id_rsa*, *id_dsa* *.gpg, *.jks, */.ssh/authorized_keys, and */.bash_history. To include all of these files, use the --no-filter option. To include some of these files, use the --include option.

Important

By default, the AMI bundling process creates a compressed, encrypted collection of files in the /tmp directory that represents your root volume. If you do not have enough free disk space in /tmp to store the bundle, you need to specify a different location for the bundle to be stored with the -d /path/to/bundle/storage option. Some instances have ephemeral storage mounted at /mnt or /media/ephemeral0 that you can use, or you can also create, attach, and mount a new Amazon EBS volume to store the bundle.
1. The ec2-bundle-vol command needs to run as root. For most commands, you can use sudo to gain elevated permissions, but in this case, you should run sudo -E su to keep your environment variables.
```
Copy
[ec2-user ~]$ sudo -E su
```
  Note that bash prompt now identifies you as the root user, and that the dollar sign has been replaced by a hash tag, signalling that you are in a root shell:
```
Copy
[root ec2-user]#
```
2. To create the AMI bundle, run the ec2-bundle-vol command with the following parameters:
  
  -c
  
  Path and filename for RSA certificate
  
  -k
  
  Path and filename for RSA certificate private key
  
  --partition
  
  Partition type: mbr, gpt, or none. AMI s from HVM instances will not boot without this.
  
  -r
  
  CPU architecture: i386 or x86_64. You can check this by running the arch command.
  
  -u
  
  Your AWS user account ID
  
  -e
  
  Comma-separated list of directories to exclude from the created image.
  
  -d
  
  If default directory /tmp has insufficient space to accommodate the bundle, this provides the path to a directory with sufficient space.
  
  --ec2cert
  
  This parameter is required for the following regions only: China (Beijing) and AWS GovCloud (US). With these regions, you must specify a region-specific public key certificate.
  
  For more information about this command and its available options, see ec2-bundle-vol.
  
  The following is a sample command:
```
Copy
[root ec2-user]# $EC2_AMITOOL_HOME/bin/ec2-bundle-vol -k /tmp/cert/pk-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem -c /tmp/cert/cert-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem -u your_aws_account_id -r x86_64 -e /tmp/cert --partition gpt
```
  It can take a few minutes to create the image. When this command completes, your /tmp (or non-default) directory contains the bundle (image.manifest.xml, plus multiple image.part.xx files).
3. Exit from the root shell.
```
Copy
[root ec2-user]# exit
```
(Optional) Edit the block device mappings in the image.manifest.xml file for your AMI. Instance store-backed AMIs can only specify instance store volumes in the block device mapping when the AMI is created, and these mappings are specified in the image.manifest.xml file. For more information, see Block Device Mapping.

Note

This step is required only if you wish to add one or more additional instance store volumes on your AMI.
1. Create a backup of your image.manifest.xml file.
```
Copy
[ec2-user ~]$ sudo cp /tmp/image.manifest.xml /tmp/image.manifest.xml.bak
```
2. Reformat the image.manifest.xml file so that it is easier to read and edit.
```
Copy
[ec2-user ~]$ sudo xmllint --format /tmp/image.manifest.xml.bak > sudo /tmp/image.manifest.xml
```
3. Edit the block device mappings in image.manifest.xml with a text editor. The example below shows a new entry for the ephemeral1 instance store volume.
```
Copy
    <block_device_mapping>
      <mapping>
        <virtual>ami</virtual>
        <device>sda</device>
      </mapping>
      <mapping>
        <virtual>ephemeral0</virtual>
        <device>sdb</device>
      </mapping>
      <mapping>
        <virtual>ephemeral1</virtual>
        <device>sdc</device>
      </mapping>
      <mapping>
        <virtual>root</virtual>
        <device>/dev/sda1</device>
      </mapping>
    </block_device_mapping>
```
4. Save the image.manifest.xml file and exit your text editor.
To upload your bundle to Amazon S3, run the ec2-upload-bundle command with the following parameters.

-b

Location of S3 bucket: my-s3-bucket/bundle_folder/bundle_name. Note that if the bucket and folder path does not exist, the command creates it.

-m

Path to image.manifest.xml. If you specified a path with -d /path/to/bundle/storage in Step 2, use that same path with this parameter.

-a

Your AWS account access key ID

-s

Your AWS account secret access key

--region

If you intend to register your AMI in a region other than US East (N. Virginia), you must specify both the target region with the --region option and a bucket path that already exists in the target region or a unique bucket path that can be created in the target region.

For more information on this command and its available options, see ec2-upload-bundle.

The following is a sample command:
```
Copy
[ec2-user ~]$ ec2-upload-bundle -b my-s3-bucket/bundle_folder/bundle_name -m /tmp/image.manifest.xml -a your_access_key_id -s your_secret_access_key
```
(Optional) After the bundle is uploaded to Amazon S3, you can remove the bundle from the /tmp directory on the instance using the following rm command:

Note

If you specified a path with the -d/path/to/bundle/storage option in Step 2, use that same path below, instead of /tmp.
```
Copy
[ec2-user ~]$ sudo rm /tmp/image.manifest.xml /tmp/image.part.* /tmp/image
```
To register your AMI , run the register-image AWS CLI command with the following parameters.

--image-location

my-s3-bucket/bundle_folder/bundle_name/image.manifest.xml

--name

A name for the AMI

--virtualization-type

Possible values are hvm and paravirtual.

--region

If you previously specified a region for the ec2-upload-bundle command, specify that region again for this command.

For more information on this command and its available options, see register-image in the AWS Command Line Interface Reference.

The following is a sample command:
```
Copy
[ec2-user ~]$ aws ec2 register-image --image-location my-s3-bucket/bundle_folder/bundle_name/image.manifest.xml --name AMI_name --virtualization-type hvm
```

Creating an AMI from an Instance Store-Backed Ubuntu Instance

This section describes the creation of an AMI from an Ubuntu Linux instance. The following procedures may not work for instances running other Linux distributions. For procedures specific to Amazon Linux, see Creating an AMI from an Instance Store-Backed Amazon Linux Instance.

To prepare to use the Amazon EC2 AMI Tools (HVM instances only)

The Amazon EC2 AMI tools require GRUB Legacy to boot properly. However, Ubuntu is configured to use GRUB 2. You must check to see that your instance uses GRUB Legacy, and if not, you need to install and configure it.

HVM instances also require partitioning tools to be installed for the AMI tools to work properly.

GRUB Legacy (version 0.9x or less) must be installed on your instance. Check to see if GRUB Legacy is present and install it if necessary.
1. Check the version of your GRUB installation.
```
Copy
ubuntu:~$ grub-install --version
grub-install (GRUB) 1.99-21ubuntu3.10
```
  In this example, the GRUB version is greater than 0.9x, so GRUB Legacy must be installed. Proceed to Step 2. If GRUB Legacy is already present, you can skip to Step 2.
2. Install the grub package using the following command.
```
Copy
ubuntu:~$ sudo apt-get install -y grub
```
  Verify that your instance is using GRUB Legacy.
```
Copy
ubuntu:~$ grub --version
grub (GNU GRUB 0.97)
```
Install the following partition management packages using the package manager for your distribution.
- gdisk (some distributions may call this package gptfdisk instead)
- kpartx
- parted
Use the following command.
```
Copy
ubuntu:~$ sudo apt-get install -y gdisk kpartx parted
```
Check the kernel parameters for yourinstance.
```
Copy
ubuntu:~$ cat /proc/cmdline
BOOT_IMAGE=/boot/vmlinuz-3.2.0-54-virtual root=UUID=4f392932-ed93-4f8f-aee7-72bc5bb6ca9d ro console=ttyS0 xen_emul_unplug=unnecessary
```
Note the options following the kernel and root device parameters: ro, console=ttyS0, and xen_emul_unplug=unnecessary. Your options may differ.
Check the kernel entries in /boot/grub/menu.lst.
```
Copy
ubuntu:~$ grep ^kernel /boot/grub/menu.lst
kernel		/boot/vmlinuz-3.2.0-54-virtual root=LABEL=cloudimg-rootfs ro console=hvc0
kernel		/boot/vmlinuz-3.2.0-54-virtual root=LABEL=cloudimg-rootfs ro single
kernel		/boot/memtest86+.bin
```
Note that the console parameter is pointing to hvc0 instead of ttyS0 and that the xen_emul_unplug=unnecessary parameter is missing. Again, your options may differ.

Edit the /boot/grub/menu.lst file with your favorite text editor (such as vim or nano) to change the console and add the parameters you identified earlier to the boot entries.

Copy
title           Ubuntu 12.04.3 LTS, kernel 3.2.0-54-virtual
root            (hd0)
kernel          /boot/vmlinuz-3.2.0-54-virtual root=LABEL=cloudimg-rootfs ro console=ttyS0 xen_emul_unplug=unnecessary
initrd          /boot/initrd.img-3.2.0-54-virtual

title           Ubuntu 12.04.3 LTS, kernel 3.2.0-54-virtual (recovery mode)
root            (hd0)
kernel          /boot/vmlinuz-3.2.0-54-virtual root=LABEL=cloudimg-rootfs ro single console=ttyS0 xen_emul_unplug=unnecessary
initrd          /boot/initrd.img-3.2.0-54-virtual

title           Ubuntu 12.04.3 LTS, memtest86+
root            (hd0)
kernel          /boot/memtest86+.bin

Verify that your kernel entries now contain the correct parameters.

Copy
ubuntu:~$ grep ^kernel /boot/grub/menu.lst
kernel		/boot/vmlinuz-3.2.0-54-virtual root=LABEL=cloudimg-rootfs ro console=ttyS0 xen_emul_unplug=unnecessary
kernel		/boot/vmlinuz-3.2.0-54-virtual root=LABEL=cloudimg-rootfs ro single console=ttyS0 xen_emul_unplug=unnecessary
kernel		/boot/memtest86+.bin

(For Ubuntu 14.04 and later only) Starting with Ubuntu 14.04, instance store backed Ubuntu AMIs use a GPT partition table and a separate EFI partition mounted at /boot/efi. The ec2-bundle-vol command will not bundle this boot partition, so you need to comment out the /etc/fstab entry for the EFI partition as shown in the following example.
```
Copy
LABEL=cloudimg-rootfs   /        ext4   defaults        0 0
#LABEL=UEFI     /boot/efi       vfat    defaults        0 0
/dev/xvdb       /mnt    auto    defaults,nobootwait,comment=cloudconfig 0       2
```

To create an AMI from an instance store-backed Linux instance

This procedure assumes that you have satisfied the prerequisites in Prerequisites.

Upload your credentials to your instance. We use these credentials to ensure that only you and Amazon EC2 can access your AMI.
1. Create a temporary directory on your instance for your credentials as follows:
```
Copy
ubuntu:~$ mkdir /tmp/cert
```
  This enables you to exclude your credentials from the created image.
2. Copy your X.509 certificate and private key from your computer to the /tmp/cert directory on your instance, using a secure copy tool such as scp. The -i my-private-key.pem option in the following scp command is the private key you use to connect to your instance with SSH, not the X.509 private key. For example:
```
Copy
you@your_computer:~ $ scp -i my-private-key.pem /path/to/pk-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem /path/to/cert-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem ec2-user@ec2-203-0-113-25.compute-1.amazonaws.com:/tmp/cert/
pk-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem  100%  717     0.7KB/s   00:00
cert-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem  100%  685     0.7KB/s   00:00
```
Alternatively, because these are plain text files, you can open the certificate and key in a text editor and copy their contents into new files in /tmp/cert.
Prepare the bundle to upload to Amazon S3 by running the ec2-bundle-vol command from inside your instance. Be sure to specify the -e option to exclude the directory where your credentials are stored. By default, the bundle process excludes files that might contain sensitive information. These files include *.sw, *.swo, *.swp, *.pem, *.priv, *id_rsa*, *id_dsa* *.gpg, *.jks, */.ssh/authorized_keys, and */.bash_history. To include all of these files, use the --no-filter option. To include some of these files, use the --include option.

Important

By default, the AMI bundling process creates a compressed, encrypted collection of files in the /tmp directory that represents your root volume. If you do not have enough free disk space in /tmp to store the bundle, you need to specify a different location for the bundle to be stored with the -d /path/to/bundle/storage option. Some instances have ephemeral storage mounted at /mnt or /media/ephemeral0 that you can use, or you can also create, attach, and mount a new Amazon EBS volume to store the bundle.
1. The ec2-bundle-vol command needs to run as root. For most commands, you can use sudo to gain elevated permissions, but in this case, you should run sudo -E su to keep your environment variables.
```
Copy
ubuntu:~$ sudo -E su
```
  Note that bash prompt now identifies you as the root user, and that the dollar sign has been replaced by a hash tag, signalling that you are in a root shell:
```
Copy
root@ubuntu:#
```
2. To create the AMI bundle, run the ec2-bundle-vol command with the following parameters.
  
  -c
  
  Path and filename for RSA certificate
  
  -k
  
  Path and filename for RSA certificate private key
  
  --partition
  
  Partition type: mbr, gpt, or none. For Ubuntu 14.04 and later HVM instances, add the --partition mbr flag to bundle the boot instructions properly; otherwise, your newly-created AMI will not boot.
  
  -r
  
  CPU architecture: i386 or x86_64. You can check this by running the arch command.
  
  -u
  
  Your AWS user account ID
  
  -e
  
  Comma-separated list of directories to exclude from the created image.
  
  -d
  
  If default directory /tmp has insufficient space to accommodate the bundle, this provides the path to a directory with sufficient space.
  
  For more information on this command and its available options, see ec2-bundle-vol.
  
  The following is a sample command:
```
Copy
root@ubuntu:# $EC2_AMITOOL_HOME/bin/ec2-bundle-vol -k /tmp/cert/pk-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem -c /tmp/cert/cert-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem -u your_aws_account_id -r x86_64 -e /tmp/cert --partition gpt
```
  It can take a few minutes to create the image. When this command completes, your tmp directory contains the bundle (image.manifest.xml, plus multiple image.part.xx files).
3. Exit from the root shell.
```
Copy
root@ubuntu:# exit
```
(Optional) Edit the block device mappings in the image.manifest.xml file for your AMI. Instance store-backed AMIs can only specify instance store volumes in the block device mapping when the AMI is created, and these mappings are specified in the image.manifest.xml file. For more information, see Block Device Mapping.

Note

This step is required only if you wish to add one or more additional instance store volumes on your AMI.
1. Create a backup of your image.manifest.xml file.
```
Copy
ubuntu:~$ sudo cp /tmp/image.manifest.xml /tmp/image.manifest.xml.bak
```
2. Reformat the image.manifest.xml file so that it is easier to read and edit.
```
Copy
ubuntu:~$ sudo xmllint --format /tmp/image.manifest.xml.bak > /tmp/image.manifest.xml
```
3. Edit the block device mappings in image.manifest.xml with a text editor. The example below shows a new entry for the ephemeral1 instance store volume.
```
Copy
    <block_device_mapping>
      <mapping>
        <virtual>ami</virtual>
        <device>sda</device>
      </mapping>
      <mapping>
        <virtual>ephemeral0</virtual>
        <device>sdb</device>
      </mapping>
      <mapping>
        <virtual>ephemeral1</virtual>
        <device>sdc</device>
      </mapping>
      <mapping>
        <virtual>root</virtual>
        <device>/dev/sda1</device>
      </mapping>
    </block_device_mapping>
```
4. Save the image.manifest.xml file and exit your text editor.
To upload your bundle to Amazon S3, run the ec2-upload-bundle command with the following parameters.

-b

Location of S3 bucket: my-s3-bucket/bundle_folder/bundle_name. Note that if the bucket and folder path does not exist, the command creates it.

-m

Path to image.manifest.xml. If you specified a path with -d /path/to/bundle/storage in Step 2, use that same path in this parameter.

-a

Your AWS account access key ID

-s

Your AWS account secret access key

--region

If you intend to register your AMI in a region other than US East (N. Virginia), you must specify both the target region with the --region option and a bucket path that already exists in the target region or a unique bucket path that can be created in the target region.

For more information on this command and its available options, see ec2-upload-bundle.

The following is a sample command:
```
Copy
ubuntu:~$ ec2-upload-bundle -b my-s3-bucket/bundle_folder/bundle_name -m /tmp/image.manifest.xml -a your_access_key_id -s your_secret_access_key
```
(Optional) After the bundle is uploaded to Amazon S3, you can remove the bundle from the /tmp directory on the instance using the following rm command:

Note

If you specified a path with the -d/path/to/bundle/storage option in Step 2, use that same path below, instead of /tmp.
```
Copy
ubuntu:~$ sudo rm /tmp/image.manifest.xml /tmp/image.part.* /tmp/image
```
To register your AMI, run the register-image AWS CLI command with the following parameters.

Path to manifest

my-s3-bucket/bundle_folder/bundle_name/image.manifest.xml

-n

A name for the AMI

--virtualization-type

Possible values are hvm and paravirtual.

--region

If you previously specified a region for the ec2-upload-bundle command, specify that region again for this command.

For more information on this command and its available options, see register-image in the AWS Command Line Interface Reference.

The following is a sample command:
```
Copy
ubuntu:~$ aws ec2 register-image my-s3-bucket/bundle_folder/bundle_name/image.manifest.xml --name AMI_name --virtualization-type hvm
```
(For Ubuntu 14.04 and later only) Uncomment the EFI entry in /etc/fstab; otherwise, your running instance will not be able to reboot.

Document Conventions

« Previous Next »