register_image ( $opt )

The RegisterImage operation registers an AMI with Amazon EC2. Images must be registered before they can be launched. For more information, see RunInstances.

Each AMI is associated with an unique ID which is provided by the Amazon EC2 service through the RegisterImage operation. During registration, Amazon EC2 retrieves the specified image manifest from Amazon S3 and verifies that the image is owned by the user registering the image.

The image manifest is retrieved once and stored within the Amazon EC2. Any modifications to an image in Amazon S3 invalidates this registration. If you make changes to an image, deregister the previous image and register the new image. For more information, see DeregisterImage.

Access

public

Parameters

Parameter

Type

Required

Description

$opt

array

Optional

An associative array of parameters that can have the following keys:

  • ImageLocation - string - Optional - The full path to your AMI manifest in Amazon S3 storage.
  • Name - string - Optional - The name to give the new Amazon Machine Image. Constraints: 3-128 alphanumeric characters, parenthesis (()), commas (,), slashes (/), dashes (-), or underscores(_)
  • Description - string - Optional - The description describing the new AMI.
  • Architecture - string - Optional - The architecture of the image. Valid Values: i386, x86_64
  • KernelId - string - Optional - The optional ID of a specific kernel to register with the new AMI.
  • RamdiskId - string - Optional - The optional ID of a specific ramdisk to register with the new AMI. Some kernels require additional drivers at launch. Check the kernel requirements for information on whether you need to specify a RAM disk.
  • RootDeviceName - string - Optional - The root device name (e.g., /dev/sda1).
  • BlockDeviceMapping - array - Optional - The block device mappings for the new AMI, which specify how different block devices (ex: EBS volumes and ephemeral drives) will be exposed on instances launched from the new image.
    • x - array - Optional - This represents a simple array index.
      • VirtualName - string - Optional - Specifies the virtual device name.
      • DeviceName - string - Optional - Specifies the device name (e.g., /dev/sdh).
      • Ebs - array - Optional - Specifies parameters used to automatically setup Amazon EBS volumes when the instance is launched.
        • x - array - Optional - This represents a simple array index.
          • SnapshotId - string - Optional - The ID of the snapshot from which the volume will be created.
          • VolumeSize - integer - Optional - The size of the volume, in gigabytes.
          • DeleteOnTermination - boolean - Optional - Specifies whether the Amazon EBS volume is deleted on instance termination.
          • VolumeType - string - Optional - [Allowed values: standard, io1]
          • Iops - integer - Optional -
      • NoDevice - string - Optional - Specifies the device name to suppress during instance launch.
  • curlopts - array - Optional - A set of values to pass directly into curl_setopt(), where the key is a pre-defined CURLOPT_* constant.
  • returnCurlHandle - boolean - Optional - A private toggle specifying that the cURL handle be returned rather than actually completing the request. This toggle is useful for manually managed batch requests.

Returns

Type

Description

CFResponse

A CFResponse object containing a parsed HTTP response.

Examples

Register an S3-backed AMI.

// Instantiate the class
$ec2 = new AmazonEC2();

// Register the image
$response = $ec2->register_image(array(
	'ImageLocation' => 'my-image-bucket/image01.manifest.xml',
	'Name' => 'my-image',
	'Description' => 'This is a sample description.',
	'BlockDeviceMapping' => array(
		array( // BlockDeviceMapping.0.{key}={value}
			"DeviceName" => "/dev/sdg",
			"VirtualName" => "sdg",
			"Ebs" => array(
				"VolumeSize" => 5,
				"DeleteOnTermination" => "true"
			)
		),
		array( // BlockDeviceMapping.1.{key}={value}
			"DeviceName" => "/dev/sdh",
			"VirtualName" => "sdh",
			"Ebs" => array(
				"VolumeSize" => 5,
				"DeleteOnTermination" => "true"
			)
		)
	)
));

// Success?
var_dump($response->isOK());
Result:
bool(true)

Changelog

Version

Description

1.3

The $image_location parameter is no longer required. To specify the image location for S3-backed AMIs, pass a value to the ImageLocation optional parameter.

Related Methods

Source

Method defined in services/ec2.class.php | Toggle source view (15 lines) | View on GitHub

public function register_image($opt = null)
{
    if (!$opt) $opt = array();
            
    // Optional list + map
    if (isset($opt['BlockDeviceMapping']))
    {
        $opt = array_merge($opt, CFComplexType::map(array(
            'BlockDeviceMapping' => $opt['BlockDeviceMapping']
        )));
        unset($opt['BlockDeviceMapping']);
    }

    return $this->authenticate('RegisterImage', $opt);
}

Copyright © 2010–2013 Amazon Web Services, LLC


Feedback