Amazon Elastic Compute Cloud
CLI Reference (API Version 2014-09-01)
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Did this page help you?  Yes | No |  Tell us about it...

ec2-create-image

Description

Creates an Amazon EBS-backed AMI from an Amazon EBS-backed instance that is either running or stopped.

If you customized your instance with instance store volumes or Amazon EBS volumes in addition to the root device volume, the new AMI contains block device mapping information for those volumes. When you launch an instance from this new AMI, the instance automatically launches with those additional volumes.

For more information, see the following topics:

The AMI creation process is different for instance store-backed AMIs. For more information about the differences between Amazon EBS-backed and instance store-backed instances, see Storage for the Root Device in the Amazon EC2 User Guide for Linux Instances. To create an instance store-backed AMI, use ec2-bundle-vol (Linux) or ec2-bundle-instance (Windows).

The short version of this command is ec2cim.

Tip

If you are using the AWS CLI, see create-image instead.

Syntax

ec2-create-image instance_id --name name [--description description] [--no-reboot] [-b, --blockdevicemapping mapping ]

Options

NameDescription

instance_id

The ID of the instance.

Type: String

Default: None

Required: Yes

Example: i-10a64379

-n, --name name

A name for the new AMI.

Type: String

Default: None

Constraints: 3-128 alphanumeric characters, parentheses (()), square brackets ([]), periods (.), slashes (/), dashes (-), single quotes ('), at-signs (@), or underscores(_). Allows spaces if the name is enclosed in quotation marks.

Required: Yes

Example: -n "Standard Web Server"

-d, --description description

A description for the new AMI.

Type: String

Default: None

Constraints: Up to 255 ASCII characters

Required: No

Example: -d Fedora_v11

--no-reboot

When this option is absent, Amazon EC2 attempts to cleanly shut down the instance before image creation and reboots the instance. When this option is used, Amazon EC2 doesn't shut down the instance before creating the image; therefore, file system integrity on the created image can't be guaranteed.

Type: Boolean

Default: false

Required: No

Example: --no-reboot

-b, --block-device-mapping mapping

The block device mapping for the instance. This argument is passed in the form of <devicename>=<blockdevice>. The devicename is the device name of the physical device on the instance to map. The blockdevice can be one of the following values:

  • none - Suppresses an existing mapping of the device from the AMI used to launch the instance. For example: "/dev/sdc=none".

  • ephemeral[0..3] - An instance store volume to be mapped to the device. For example: "/dev/sdc=ephemeral0".

  • [snapshot-id]:[volume-size]:[delete-on-termination]:[volume-type[:iops]]:[encrypted] - An Amazon EBS volume to be mapped to the device. For example "/dev/sdh=snap-7eb96d16::false:io1:500:encrypted".

    [snapshot-id]

    To create a volume from a snapshot, specify the snapshot ID.

    [volume-size]

    To create an empty Amazon EBS volume, omit the snapshot ID and specify a volume size instead. For example: "/dev/sdh=:20".

    [delete-on-termination]

    To prevent the volume from being deleted on termination of the instance, specify false. The default istrue.

    [volume-type]

    The default volume type is standard. To create a General Purpose (SSD) volume, specify gp2. To create a Provisioned IOPS (SSD) volume, specify io1. If the volume type is io1, you must also specify the number of IOPS that the volume should support. For more information, see Amazon EBS Volume Types in the Amazon EC2 User Guide for Linux Instances.

    [iops]

    The number of provisioned IOPS that the volume supports (this option is only valid with io1 volume types).

    [encrypted]

    Indicates that the volume should be encrypted. Encrypted Amazon EBS volumes may only be attached to instances that support Amazon EBS encryption. Volumes that are created from encrypted snapshots are automatically encrypted. There is no way to create an encrypted volume from an unencrypted snapshot or vice versa. If your AMI uses encrypted volumes, you can only launch it on supported instance types. For more information, see Amazon EBS Encryption in the Amazon EC2 User Guide for Linux Instances.

You can specify multiple --block-device-mapping options in one call.

For more information, see Block Device Mapping in the Amazon EC2 User Guide for Linux Instances.

Type: String

Default: None

Required: No

Example: -b "/dev/sdc=snap-7eb96d16:100:false:io1:500"

Note

On Windows, the mapping argument must be enclosed in double quotes, as shown in the example.

Note

For M3 instances, you must specify instance store volumes in the block device mapping for the instance. When you launch an M3 instance, we ignore any instance store volumes specified in the block device mapping for the AMI.

Common Options

OptionDescription

--region region

The region. Overrides the default region, the region specified by the EC2_URL environment variable, and the URL specified by the -U option.

Default: The region specified by the EC2_URL environment variable, or us-east-1 if EC2_URL isn't set.

-U, --url url

The uniform resource locator (URL) of the Amazon EC2 web service entry point.

Default: The endpoint specified by the EC2_URL environment variable, or https://ec2.amazonaws.com if EC2_URL isn't set.

-O, --aws-access-key aws_access_key_id

Your access key ID. For more information, see Tell the Tools Who You Are.

Default: The value of the AWS_ACCESS_KEY environment variable. If AWS_ACCESS_KEY isn't set, you must specify this option.

Example: -O AKIAIOSFODNN7EXAMPLE

-W, --aws-secret-key aws_secret_access_key

Your secret access key.

Default: The value of the AWS_SECRET_KEY environment variable. If AWS_SECRET_KEY isn't set, you must specify this option.

Example: -W wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

-T, --security-token delegation_token

The delegation token to pass along to the AWS request. This is only required when you are using temporary security credentials. For more information, see Using Temporary Security Credentials.

Default: The value of the AWS_DELEGATION_TOKEN environment variable (if set).

Example: -t AQoDYXdzEJr...<remainder of security token>

--connection-timeout timeout

The connection timeout, in seconds.

Example: --connection-timeout 30

--request-timeout timeout

The request timeout, in seconds.

Example: --request-timeout 45

-H, --headers

Includes column headers in the command output.

--show-empty-fields

Shows empty columns as (nil).

--hide-tags

Omits tags for tagged resources.

--debug

Displays internal debugging information. This can assist us when helping you troubleshooting problems.

-D, --auth-dry-run

Checks whether you have the required permissions for the command, without actually running the command. If you have the required permissions, the command returns DryRunOperation; otherwise, it returns UnauthorizedOperation.

-v, --verbose

Displays verbose output, including the API request and response on the command line. This is useful if you are building tools to talk directly to the Query API.

-

Reads arguments from standard input. This is useful when piping the output from one command to the input of another.

Example: ec2-describe-instances | grep stopped | cut -f 2 | ec2-start-instances -

-?, --help, -h

Displays usage information for the command.

Deprecated Options

We have deprecated the SOAP API for Amazon EC2. For more information, see SOAP Requests. From version 1.6.14.0 onwards of the Amazon EC2 CLI tools, the private key (-K, --private-key) and X.509 certificate (-C, --cert) options are not supported. Use your access key ID (-O, --aws-access-key) and secret access key (-W, --aws-secret-key) instead. For more information, see Setting Up the Amazon EC2 CLI and AMI Tools.

OptionDescription

-K, --private-key ec2_private_key

The private key to use when constructing requests to Amazon EC2.

Default: The value of the EC2_PRIVATE_KEY environment variable.

Example: -K pk-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem

-C, --cert ec2_cert

The X.509 certificate to use when constructing requests to Amazon EC2.

Default: The value of the EC2_CERT environment variable.

Example: -C cert-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem

Output

This command returns a table that contains the following information:

  • The IMAGE identifier

  • The ID of the new AMI

Amazon EC2 command line tools display errors on stderr.

Examples

Example

This example command creates an AMI from the specified instance.

PROMPT> ec2-create-image i-10a64379 --name "Standard Web Server" --description "Standard web server AMI"
IMAGE	ami-4fa54026

Example

This example command creates an AMI with three volumes. The first volume is based on an Amazon EBS snapshot. The second volume is an empty 100 GiB Amazon EBS volume. The third volume is an instance store volume, ephemeral0.

PROMPT> ec2-create-image i-10a64379 --name "Standard Web Server" --description "Standard web server AMI" -b "/dev/sdf=snap-2a3b4c5d" -b "/dev/sdg=:100" -b "/dev/sdc=ephemeral0" 
IMAGE	ami-4fa54026