Register Image operation for the Amazon EC2 REST adapter

The Register Image operation enables you to register a specified Amazon Machine Image (AMI) with Amazon EC2. You should register images before launching them. Each AMI is associated with a unique ID. The Amazon EC2 service provides these unique IDs through this operation. If needed, you can deregister an AMI at any time.

The following figure shows a sample <items> XML element for the Register Image operation:

Sample <items> XML element for the Register Image operation
<items>
   <item>
       <parameters>
           <!-Optional:->
           <image-location></image-location>
           <name></name>
           <!-Optional:->
           <description></description>
           <!-Optional:->
           <architecture></architecture>
           <!-Optional:->
           <kernel-id></kernel-id>
           <!-Optional:->
           <ramdisk-id></ramdisk-id>
           <!-Optional:->
           <root-device-name></root-device-name>
           <!-Optional:->
           <block-device-mapping>
               <!-Zero or more repetitions:->
               <item>
                   <device-name></device-name>
                   <!-You have a CHOICE of the next 3 items at this level->
                   <virtual-name></virtual-name>
                   <ebs>
                       <!-Optional:->
                       <snapshot-id></snapshot-id>
                       <!-Optional:->
                       <volume-size></volume-size>
                       <!-Optional:->
                       <volume-type></volume-type>
                       <!-Optional:->
                       <iops></iops>
                       <!-Optional:->
                       <delete-on-termination></delete-on-termination>
                   </ebs>
                   <no-device/>
               </item>
           </block-device-mapping>
       </parameters>
   </item>
</items>

The following table describes the elements for this adapter request:

Adapter request elements for the Register Image operation

Element

Definition

Required

<access-key>

Specifies the Amazon Web Services (AWS) access key

You need to generate the AWS access key by going to the Security Credentials tab in the AWS console.

Conditional;

  • You must specify the Access Key and theSecret Key together in the configuration or the adapter request.
  • If you specify both the keys in the adapter request and in the adapter configuration, the key values in the request override the values in the configuration.
  • If only the Access Key is specified, the adapter ignores the value.
<secret-key>

Specifies the AWS secret access key

You need to generate the AWS secret access key by going to the Security Credentials tab in the AWS console.

Conditional;

  • You must specify the Access Key and theSecret Key together in the configuration or the adapter request.
  • If you specify both the keys in the adapter request and in the adapter configuration, the key values in the request override the values in the configuration.
  • If only the Secret Access Key is specified, the adapter ignores the value.
<session-token>

Specifies the temporary session token generated using the AWS APIs.

Conditional;

You must specify the Access Key and Secret Key as well in the configuration or the adapter request, else the <session-token> value is ignored.

<region>

Specifies the region with which you want the adapter to communicate

Amazon EC2 is hosted in multiple locations world-wide. You must specify the region in which you want the adapter to perform the actions.

Valid values:

  • us-east-1
  • us-west-2 (default)
  • us-west-1
  • eu-west-1
  • ap-southeast-1
  • ap-northeast-1
  • ap-southeast-2
  • sa-east-1

No

<operation-name>

Contains the name of the operation: register-image

Yes

<image-location>

Specifies the full path to the AMI manifest in Amazon Simple Storage Service (S3)
Amazon S3 is storage for the Internet. Amazon S3 provides a simple web services interface that you can use to store and retrieve any amount of data, at any time, from anywhere on the web.

Yes

<name>

Specifies the name of the AMI provided during image creation

Yes

<description>

Specifies the description of the AMI provided during image creation

No

<architecture>

Specifies the architecture of the image
Valid values: i386, x86_64 architecture

No

<kernel-id>

Specifies the ID of the kernel to select

No

<ramdisk-id>

Specifies the ID of the RAM disk to select

No

<root-device-name>

Specifies the root device name (For example, /dev/sda1)

No

<block-device-mapping>

Specifies how block devices are exposed to the instance

Each mapping is made up of a virtualName and a deviceName or device-name.

  • <device-name>
  • <virtual-name>
  • <ebs>
  • <snapshot-id>
  • <volume-size>
  • <volume-type>
  • <delete-on-termination>
  • <no-device>

No

<device-name>

Specifies the name of the physical device on the instance to map

For example, /dev/sdh

Conditional; required if you specify the<block-device-mapping> element

<virtual-name>

Specifies an instance store volume to be mapped to the device

For example, ephemeral0

No

Note: You can specify only one of the following elements within the <block-device-mapping> element:

  • <ebs>
  • <no-device>
  • <virtual-name>
<ebs>

Specifies the parent element that contains the following elements used to set up Amazon EBS volumes to be mapped to the device:

  • <snapshot-id>
  • <volume-size>
  • <volume-type>
  • <iops>
  • <delete-on-termination>

No

Note: You can specify only one of the following elements within the <block-device-mapping> element:

  • <ebs>
  • <no-device>
  • <virtual-name>
<snapshot-id>

Specifies the snapshot ID based on which a volume is created

No

<volume-size>

Specifies the volume size that you can use instead of the <snapshot-id> to create an empty Amazon EBS volume

No

<volume-type>

Specifies the type of the volume

Valid values: io1 (To create a Provisioned IOPS volume), standard (default) 

Note: If the volume type is io1, you can also provision the number of IOPS that the volume supports.

No

<iops>

Specifies the number of Input/Output operations per second (IOPS) that a volume of type I/O 1 supports

No

<delete-on-termination>

Specifies whether to prevent the volume from being deleted on termination of the instance

Valid values: true (default), false

No

<no-device>

Specifies the device to suppress during the instance launch

No

Note: You can specify only one of the following elements within the <block-device-mapping> element:

  • <ebs>
  • <no-device>
  • <virtual-name>

The following figure shows a sample adapter request for the Register Image operation:

Sample adapter request for the Register Image operation

 <amazon-ec2-rest-request>
   <operation-name>register-image</operation-name>
   <parameters>
     <image-location />
     <name>Aoimage0078</name>
     <description>This is AO test image00110011</description>
     <architecture>x86_64</architecture>
     <kernel-id>aki-004ec330</kernel-id>
     <ramdisk-id>ari-00e26f30</ramdisk-id>
     <root-device-name>/dev/sda1</root-device-name>
     <block-device-mapping>
       <item>
         <device-name>/dev/sda1</device-name>
         <virtual-name />
         <ebs>
           <snapshot-id>snap-167a24e6</snapshot-id>
           <volume-size />
           <volume-type />
           <iops />
           <delete-on-termination />
         </ebs>
         <no-device />
       </item>
     </block-device-mapping>
   </parameters>
 </amazon-ec2-rest-request>

The following figure shows a sample adapter response for the Register Image operation:

Sample adapter response for the Register Image operation

 <amazon-ec2-rest-response>
 <metadata>
   <status>success</status>
 </metadata>
 <RegisterImageResponse>
   <ImageInfo>
     <imageId>ami-1ed9b12e</imageId>
   </ImageInfo>
 </RegisterImageResponse>
</amazon-ec2-rest-response>

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*