VM::EC2::Image(3pm)

📦
version 1.28 · 7 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

💖 VM::EC2::Image 💖

okay bestie, welcome to the VM::EC2::Image(3pm) page from the User Contributed Perl Documentation. this is where AMIs get their whole main-character moment. ✨

✨ NAME ✨

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

🌸 SYNOPSIS 🌸

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);

🦋 DESCRIPTION 🦋

This object represents an Amazon Machine Image (AMI), and it's what VM::EC2->describe_images() gives you back. Besides all the cute query methods for the image's attributes, the run_instances() method lets you launch and configure EC2 instances based on the AMI. slay.

💅 METHODS 💅

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 object.
  • 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 creation.
  • rootDeviceType — The root device type. One of "ebs" or "instance-store".
  • rootDeviceName — Name of the root device, e.g. "/dev/sda1"
  • blockDeviceMapping — List of block devices attached to this image. Each element is a VM::EC2::BlockDevice.
  • virtualizationType — One of "paravirtual" or "hvm".
  • hypervisor — One of "ovm" or "xen"

In addition, the object supports the tags() method described in VM::EC2::Generic:

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. It 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 information.

  • -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 list.
  • -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 only.
  • -placement_tenancy — Specify 'dedicated' to launch the instance on a dedicated server. Only applicable for VPC instances.
  • -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: Example: ['/dev/sdb=ephemeral0','/dev/sdc=snap-12345:80:false']
  • -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. See http://docs.amazonwebservices.com/AWSEC2/latest/UserGuide/Run_Instance_Idempotency.html

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 => $desc) 💖

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

💖 $image->refresh 💖

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.

🌈 STRING OVERLOADING 🌈

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

👑 SEE ALSO 👑

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

💖 AUTHOR 💖

Lincoln Stein <lincoln.stein@gmail.com>.

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.

and that's the tea, bestie 🫶 this page is from perl v5.38.2, dated 2024-08-10, for VM::EC2::Image(3pm). go launch something iconic 💅✨

📦 where this page comes from