Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
VM::EC2::Image(3)     User Contributed Perl Documentation    VM::EC2::Image(3)

       VM::EC2::Image -	Object describing an Amazon Machine Image (AMI)

	 use VM::EC2;

	 $ec2	  = VM::EC2->new(...);
	 $image	  = $ec2->describe_images(-image_id=>'ami-12345');

	 $state	  = $image->imageState;
	 $owner	  = $image->imageOwnerId;
	 $rootdev = $image->rootDeviceName;
	 @devices = $image->blockDeviceMapping;
	 $tags	  = $image->tags;

	 @instances = $image->run_instances(-min_count=>10);

       This object represents an Amazon	Machine	Image (AMI), and is returned
       by VM::EC2->describe_images(). In addition to methods to	query the
       image's attributes, the run_instances() method allows you to launch and
       configure EC2 instances based on	the AMI.

       These object methods are	supported:

	imageId	      -- AMI ID
	imageLocation -- Location of the AMI
	imageState    -- Current state of the AMI. One of "available",
			 "pending" or "failed".	Only "available" AMIs
			 can be	launched.
	imageOwnerId  -- AWS account ID	of the image owner.
	isPublic      -- Returns true if this image has	public launch
			 permissions. Note that	this is	a Perl boolean,
			 and not the string "true".
	productCodes  -- A list	of product codes associated with the image.
	architecture  -- The architecture of the image.
	imageType     -- The image type	(machine, kernel or RAM	disk).
	kernelId      -- The kernel associated with the	image.
	ramdiskId     -- The RAM disk associated with the image.
	platform      -- "Windows" for Windows AMIs, otherwise undef.
	sriovNetSupport	-- Specifies whether enhanced networking is enabled.
			   "simple" if enabled.
	stateReason   -- Explanation of	a "failed" imageState. This is
			 a VM::EC2::Instance::State::Reason
	imageOwnerAlias	-The AWS account alias (e.g. "self") or	AWS
			 account ID that owns the AMI.
	name	      -- Name of the AMI provided during image creation.
	description   -- Description of	the AMI	provided during	image
	rootDeviceType -- The root device type.	One of "ebs" or
	rootDeviceName -- Name of the root device, e.g.	"/dev/sda1"
	blockDeviceMapping -- List of block devices attached to	this
			  image. Each element is a
	virtualizationType -- One of "paravirtual" or "hvm".
	hypervisor     -- One of "ovm" or "xen"

       In addition, the	object supports	the tags() method described in

	print "ready for production\n" if $image->tags->{Released};

   @instances =	$image->run_instances(%args)
       The run_instance() method will launch one or more instances based on
       this AMI. The method takes all the arguments recognized by
       VM::EC2->run_instances(), except	for the	-image_id argument. The	method
       returns a list of VM::EC2::Instance objects, which you may monitor
       periodically until they are up and running.

       All arguments are optional. See run_instances() in VM::EC2 for more

	 -min_count	    Minimum number of instances	to launch [1]
	 -max_count	    Maximum number of instances	to launch [1]
	 -key_name	    Name of the	keypair	to use
	 -security_group_id Security group ID to use for this instance.
			    Use	an arrayref for	multiple group IDs
	 -security_group    Security group name	to use for this	instance.
			    Use	an arrayref for	multiple values.
	 -user_data	    User data to pass to the instances.	Do NOT base64
			    encode this. It will be done for you.
	 -instance_type	    Type of the	instance to use. See below for a
	 -placement_zone    The	availability zone you want to launch the
			    instance into. Call	$ec2->regions for a list.
	 -placement_group   An existing	placement group	to launch the
			    instance into. Applicable to cluster instances
	 -placement_tenancy Specify 'dedicated'	to launch the instance on a
			    dedicated server. Only applicable for VPC
	 -kernel_id	    ID of the kernel to	use for	the instances,
			    overriding the kernel specified in the image.
	 -ramdisk_id	    ID of the ramdisk to use for the instances,
			    overriding the ramdisk specified in	the image.
	 -block_devices	    Specify block devices to map onto the instances,
			    overriding the values specified in the image.
			    This can be	a scalar string	or an arrayref for
			    multiple mappings:
	 -monitoring	    Pass a true	value to enable	detailed monitoring.
	 -subnet_id	    ID of the subnet to	launch the instance
			    into. Only applicable for VPC instances.
	 -termination_protection  Pass true to lock the	instance so that it
			    cannot be terminated using the API.	Use
			    modify_instance() to unset this if youu wish to
			    terminate the instance later.
	 -disable_api_termination -- Same as above.
	 -shutdown_behavior Pass "stop"	(the default) to stop the instance
			    and	save its disk state when "shutdown" is called
			    from within	the instance. Stopped instances	can
			    be restarted later.	Pass "terminate" to
			    instead terminate the instance and discard its
			    state completely.
	 -instance_initiated_shutdown_behavior -- Same as above.
	 -private_ip_address Assign the	instance to a specific IP address
			    from a VPC subnet (VPC only).
	 -client_token	    Unique identifier that you can provide to ensure
			    idempotency	of the request.	You can	use
			    $ec2->token() to generate a	suitable identifier.

       Note that after launching an instance, you may need to wait a few
       seconds before adding tags to it	or performing other operations.

       See VM::EC2 for details.

   $boolean = $image->make_public($public)
       Change the isPublic flag. Provide a true	value to make the image
       public, a false one to make it private.

   $state  = $image->current_status
       Refreshes the object and	then calls imageState()	to return one of
       "pending", "available" or "failed." You can use this to monitor an
       image_creation process in progress.

   @user_ids = $image->launchPermissions
       Returns a list of user IDs with launch permission for this image. Note
       that the	AWS API	calls this "launchPermission", but this	module makes
       it plural to emphasize that the result is a list.

   @user_ids = $image->authorized_users
       The same	as launchPermissions.

   $boolean = $image->add_authorized_users($id1,$id2,...)
   $boolean = $image->remove_authorized_users($id1,$id2,...)
       These methods add and remove user accounts which	have launch
       permissions for the image. The result code indicates whether the	list
       of user IDs were	successfully added or removed.

   $boolean = $image->add_authorized_users($id1,$id2,...)
   $boolean = $image->remove_authorized_users($id1,$id2,...)
   $boolean = $image->reset_authorized_users
       These methods add and remove user accounts which	have launch
       permissions for the image. The result code indicates whether the	list
       of user IDs were	successfully added or removed.

       reset_authorized_users()	resets the list	users authored to launch
       instances from this image to empty, effectively granting	launch
       privileges to the owner only.

       See also	authorized_users().

   $copy = $image->copy(-region	=> $region, -name => $name, -description =>
       Copies the image	to another region.

       Required	arguments:

	-region		  The region to	copy to

       Optional	arguments:

	-name		  The name of the image.

	-description	  The description of the image.

	-client_token	  Unique identifier to ensure idempotency of the request

       This method will	refresh	the object from	AWS, updating all values to
       their current ones. You can call	it after tagging or otherwise changing
       image attributes.

       When used in a string context, this object will interpolate the

       VM::EC2 VM::EC2::Generic	VM::EC2::BlockDevice VM::EC2::StateReason
       VM::EC2::Instance VM::EC2::Tag

       Lincoln Stein <>.

       Copyright (c) 2011 Ontario Institute for	Cancer Research

       This package and	its accompanying libraries is free software; you can
       redistribute it and/or modify it	under the terms	of the GPL (either
       version 1, or at	your option, any later version)	or the Artistic
       License 2.0.  Refer to LICENSE for the full license text. In addition,
       please see DISCLAIMER.txt for disclaimers of warranty.

perl v5.32.1			  2021-02-28		     VM::EC2::Image(3)


Want to link to this manual page? Use this URL:

home | help