You are viewing documentation for version 2 of the AWS SDK for Ruby. Version 3 documentation can be found here.

Class: Aws::EC2::Image

Inherits:
Resources::Resource show all
Defined in:
(unknown)

Instance Attribute Summary collapse

Attributes inherited from Resources::Resource

#client, #identifiers

Instance Method Summary collapse

Methods inherited from Resources::Resource

add_data_attribute, add_identifier, #data, data_attributes, #data_loaded?, identifiers, #load, #wait_until

Methods included from Resources::OperationMethods

#add_batch_operation, #add_operation, #batch_operation, #batch_operation_names, #batch_operations, #operation, #operation_names, #operations

Constructor Details

#initialize(id, options = {}) ⇒ Object #initialize(options = {}) ⇒ Object

Overloads:

  • #initialize(id, options = {}) ⇒ Object

    Parameters:

    • id (String)

    Options Hash (options):

    • :client (Client) —

      When `:client is not given, the options hash is used to construct a new Client object.

  • #initialize(options = {}) ⇒ Object

    Options Hash (options):

    • :id (required, String)
    • :client (Client) —

      When `:client is not given, the options hash is used to construct a new Client object.

Instance Attribute Details

#architecture ⇒ String (readonly)

The architecture of the image.

Possible values:

  • i386
  • x86_64
  • arm64

Returns:

  • (String) —

    The architecture of the image.

#block_device_mappings ⇒ Array<Types::BlockDeviceMapping> (readonly)

Any block device mapping entries.

Returns:

#creation_date ⇒ String (readonly)

The date and time the image was created.

Returns:

  • (String) —

    The date and time the image was created.

#description ⇒ String (readonly)

The description of the AMI that was provided during image creation.

Returns:

  • (String) —

    The description of the AMI that was provided during image creation.

#ena_support ⇒ Boolean (readonly)

Specifies whether enhanced networking with ENA is enabled.

Returns:

  • (Boolean) —

    Specifies whether enhanced networking with ENA is enabled.

#hypervisor ⇒ String (readonly)

The hypervisor type of the image.

Possible values:

  • ovm
  • xen

Returns:

  • (String) —

    The hypervisor type of the image.

#id ⇒ String (readonly)

Returns:

  • (String)

#image_id ⇒ String (readonly)

The ID of the AMI.

Returns:

  • (String) —

    The ID of the AMI.

#image_location ⇒ String (readonly)

The location of the AMI.

Returns:

  • (String) —

    The location of the AMI.

#image_owner_alias ⇒ String (readonly)

The AWS account alias (for example, amazon, self) or the AWS account ID of the AMI owner.

Returns:

  • (String) —

    The AWS account alias (for example, amazon, self) or the AWS account ID of the AMI owner.

#image_type ⇒ String (readonly)

The type of image.

Possible values:

  • machine
  • kernel
  • ramdisk

Returns:

  • (String) —

    The type of image.

#kernel_id ⇒ String (readonly)

The kernel associated with the image, if any. Only applicable for machine images.

Returns:

  • (String) —

    The kernel associated with the image, if any.

#name ⇒ String (readonly)

The name of the AMI that was provided during image creation.

Returns:

  • (String) —

    The name of the AMI that was provided during image creation.

#owner_id ⇒ String (readonly)

The AWS account ID of the image owner.

Returns:

  • (String) —

    The AWS account ID of the image owner.

#platform ⇒ String (readonly)

This value is set to windows for Windows AMIs; otherwise, it is blank.

Possible values:

  • Windows

Returns:

  • (String) —

    This value is set to windows for Windows AMIs; otherwise, it is blank.

#platform_details ⇒ String (readonly)

The platform details associated with the billing code of the AMI. For more information, see Obtaining Billing Information in the Amazon Elastic Compute Cloud User Guide.

Returns:

  • (String) —

    The platform details associated with the billing code of the AMI.

#product_codes ⇒ Array<Types::ProductCode> (readonly)

Any product codes associated with the AMI.

Returns:

#public ⇒ Boolean (readonly)

Indicates whether the image has public launch permissions. The value is true if this image has public launch permissions or false if it has only implicit and explicit launch permissions.

Returns:

  • (Boolean) —

    Indicates whether the image has public launch permissions.

#ramdisk_id ⇒ String (readonly)

The RAM disk associated with the image, if any. Only applicable for machine images.

Returns:

  • (String) —

    The RAM disk associated with the image, if any.

#root_device_name ⇒ String (readonly)

The device name of the root device volume (for example, /dev/sda1).

Returns:

  • (String) —

    The device name of the root device volume (for example, /dev/sda1).

#root_device_type ⇒ String (readonly)

The type of root device used by the AMI. The AMI can use an EBS volume or an instance store volume.

Possible values:

  • ebs
  • instance-store

Returns:

  • (String) —

    The type of root device used by the AMI.

#sriov_net_support ⇒ String (readonly)

Specifies whether enhanced networking with the Intel 82599 Virtual Function interface is enabled.

Returns:

  • (String) —

    Specifies whether enhanced networking with the Intel 82599 Virtual Function interface is enabled.

#state ⇒ String (readonly)

The current state of the AMI. If the state is available, the image is successfully registered and can be used to launch an instance.

Possible values:

  • pending
  • available
  • invalid
  • deregistered
  • transient
  • failed
  • error

Returns:

  • (String) —

    The current state of the AMI.

#state_reason ⇒ Types::StateReason (readonly)

The reason for the state change.

Returns:

#tags ⇒ Array<Types::Tag> (readonly)

Any tags assigned to the image.

Returns:

  • (Array<Types::Tag>) —

    Any tags assigned to the image.

#usage_operation ⇒ String (readonly)

The operation of the Amazon EC2 instance and the billing code that is associated with the AMI. usageOperation corresponds to the lineitem/Operation column on your AWS Cost and Usage Report and in the AWS Price List API. For the list of UsageOperation codes, see Platform Details and Usage Operation Billing Codes in the Amazon Elastic Compute Cloud User Guide.

Returns:

  • (String) —

    The operation of the Amazon EC2 instance and the billing code that is associated with the AMI.

#virtualization_type ⇒ String (readonly)

The type of virtualization of the AMI.

Possible values:

  • hvm
  • paravirtual

Returns:

  • (String) —

    The type of virtualization of the AMI.

Instance Method Details

#create_tags(options = {}) ⇒ Array<Tag>

Examples:

Request syntax example with placeholder values


image.create_tags({
  dry_run: false,
  tags: [ # required
    {
      key: "String",
      value: "String",
    },
  ],
})

Basic usage

tags = image.create_tags(options)
tags.map(&:value)
#=> ["tag-value", ...]

Options Hash (options):

  • :dry_run (Boolean) —

    Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

  • :tags (required, Array<Types::Tag>) —

    The tags. The value parameter is required, but if you don\'t want the tag to have a value, specify the parameter with no value, and we set the value to an empty string.

Returns:

See Also:

#delete_tags(options = {}) ⇒ Array<Tag>

Examples:

Request syntax example with placeholder values


image.delete_tags({
  dry_run: false,
  tags: [
    {
      key: "String",
      value: "String",
    },
  ],
})

Basic usage

tags = image.delete_tags(options)
tags.map(&:value)
#=> ["tag-value", ...]

Options Hash (options):

  • :dry_run (Boolean) —

    Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

  • :tags (Array<Types::Tag>) —

    The tags to delete. Specify a tag key and an optional tag value to delete specific tags. If you specify a tag key without a tag value, we delete any tag with this key regardless of its value. If you specify a tag key with an empty string as the tag value, we delete the tag only if its value is an empty string.

    If you omit this parameter, we delete all user-defined tags for the specified resources. We do not delete AWS-generated tags (tags that have the aws: prefix).

Returns:

See Also:

#deregister(options = {}) ⇒ Struct

Deregisters the specified AMI. After you deregister an AMI, it can't be used to launch new instances; however, it doesn't affect any instances that you've already launched from the AMI. You'll continue to incur usage costs for those instances until you terminate them.

When you deregister an Amazon EBS-backed AMI, it doesn't affect the snapshot that was created for the root volume of the instance during the AMI creation process. When you deregister an instance store-backed AMI, it doesn't affect the files that you uploaded to Amazon S3 when you created the AMI.

Examples:

Request syntax example with placeholder values


image.deregister({
  dry_run: false,
})

Options Hash (options):

  • :dry_run (Boolean) —

    Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

Returns:

  • (Struct) —

    Returns an empty response.

See Also:

#describe_attribute(options = {}) ⇒ Types::ImageAttribute

Describes the specified attribute of the specified AMI. You can specify only one attribute at a time.

Examples:

Request syntax example with placeholder values


image.describe_attribute({
  attribute: "description", # required, accepts description, kernel, ramdisk, launchPermission, productCodes, blockDeviceMapping, sriovNetSupport
  dry_run: false,
})

Options Hash (options):

  • :attribute (required, String) —

    The AMI attribute.

    Note: Depending on your account privileges, the blockDeviceMapping attribute may return a Client.AuthFailure error. If this happens, use DescribeImages to get information about the block device mapping for the AMI.

  • :dry_run (Boolean) —

    Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

Returns:

See Also:

#exists? ⇒ Boolean

Returns true if this Image exists. Returns false otherwise.

Returns:

  • (Boolean) —

    Returns true if this Image exists. Returns false otherwise.

#modify_attribute(options = {}) ⇒ Struct

Modifies the specified attribute of the specified AMI. You can specify only one attribute at a time. You can use the Attribute parameter to specify the attribute or one of the following parameters: Description, LaunchPermission, or ProductCode.

AWS Marketplace product codes cannot be modified. Images with an AWS Marketplace product code cannot be made public.

To enable the SriovNetSupport enhanced networking attribute of an image, enable SriovNetSupport on an instance and create an AMI from the instance.

Examples:

Request syntax example with placeholder values


image.modify_attribute({
  attribute: "String",
  description: "value", # value <Hash,Array,String,Numeric,Boolean,IO,Set,nil>
  launch_permission: {
    add: [
      {
        group: "all", # accepts all
        user_id: "String",
      },
    ],
    remove: [
      {
        group: "all", # accepts all
        user_id: "String",
      },
    ],
  },
  operation_type: "add", # accepts add, remove
  product_codes: ["String"],
  user_groups: ["String"],
  user_ids: ["String"],
  value: "String",
  dry_run: false,
})

Options Hash (options):

  • :attribute (String) —

    The name of the attribute to modify. The valid values are description, launchPermission, and productCodes.

  • :description (Types::AttributeValue) —

    A new description for the AMI.

  • :launch_permission (Types::LaunchPermissionModifications) —

    A new launch permission for the AMI.

  • :operation_type (String) —

    The operation type. This parameter can be used only when the Attribute parameter is launchPermission.

  • :product_codes (Array<String>) —

    The DevPay product codes. After you add a product code to an AMI, it can\'t be removed.

  • :user_groups (Array<String>) —

    The user groups. This parameter can be used only when the Attribute parameter is launchPermission.

  • :user_ids (Array<String>) —

    The AWS account IDs. This parameter can be used only when the Attribute parameter is launchPermission.

  • :value (String) —

    The value of the attribute being modified. This parameter can be used only when the Attribute parameter is description or productCodes.

  • :dry_run (Boolean) —

    Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

Returns:

  • (Struct) —

    Returns an empty response.

See Also:

#reset_attribute(options = {}) ⇒ Struct

Resets an attribute of an AMI to its default value.

The productCodes attribute can't be reset.

Examples:

Request syntax example with placeholder values


image.reset_attribute({
  attribute: "launchPermission", # required, accepts launchPermission
  dry_run: false,
})

Options Hash (options):

  • :attribute (required, String) —

    The attribute to reset (currently you can only reset the launch permission attribute).

  • :dry_run (Boolean) —

    Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

Returns:

  • (Struct) —

    Returns an empty response.

See Also:

#wait_until_exists {|waiter| ... } ⇒ Image

Waits until this Image is exists. This method waits by polling Client#describe_images until successful. An error is raised after a configurable number of failed checks.

This waiter uses the following defaults:

Configuration Default
#delay 15
#max_attempts 40

You can modify defaults and register callbacks by passing a block argument.

Examples:

Basic usage

image.wait_until_exists

Yield Parameters:

Returns:

  • (Image) —

    Returns a copy of this Image with loaded data.

Raises:

See Also: