2025/05/06 - Amazon Elastic Compute Cloud - 16 updated api methods
Changes This release adds support for Amazon EBS Provisioned Rate for Volume Initialization, which lets you specify a volume initialization rate to ensure that your EBS volumes are initialized in a predictable amount of time.
{'BlockDeviceMappings': {'Ebs': {'VolumeInitializationRate': 'integer'}}}
Creates an Amazon EBS-backed AMI from an Amazon EBS-backed instance that is either running or stopped.
If you customized your instance with instance store volumes or Amazon EBS volumes in addition to the root device volume, the new AMI contains block device mapping information for those volumes. When you launch an instance from this new AMI, the instance automatically launches with those additional volumes.
For more information, see Create an Amazon EBS-backed Linux AMI in the Amazon Elastic Compute Cloud User Guide.
See also: AWS API Documentation
Request Syntax
client.create_image(
TagSpecifications=[
{
'ResourceType': 'capacity-reservation'|'client-vpn-endpoint'|'customer-gateway'|'carrier-gateway'|'coip-pool'|'declarative-policies-report'|'dedicated-host'|'dhcp-options'|'egress-only-internet-gateway'|'elastic-ip'|'elastic-gpu'|'export-image-task'|'export-instance-task'|'fleet'|'fpga-image'|'host-reservation'|'image'|'import-image-task'|'import-snapshot-task'|'instance'|'instance-event-window'|'internet-gateway'|'ipam'|'ipam-pool'|'ipam-scope'|'ipv4pool-ec2'|'ipv6pool-ec2'|'key-pair'|'launch-template'|'local-gateway'|'local-gateway-route-table'|'local-gateway-virtual-interface'|'local-gateway-virtual-interface-group'|'local-gateway-route-table-vpc-association'|'local-gateway-route-table-virtual-interface-group-association'|'natgateway'|'network-acl'|'network-interface'|'network-insights-analysis'|'network-insights-path'|'network-insights-access-scope'|'network-insights-access-scope-analysis'|'outpost-lag'|'placement-group'|'prefix-list'|'replace-root-volume-task'|'reserved-instances'|'route-table'|'security-group'|'security-group-rule'|'service-link-virtual-interface'|'snapshot'|'spot-fleet-request'|'spot-instances-request'|'subnet'|'subnet-cidr-reservation'|'traffic-mirror-filter'|'traffic-mirror-session'|'traffic-mirror-target'|'transit-gateway'|'transit-gateway-attachment'|'transit-gateway-connect-peer'|'transit-gateway-multicast-domain'|'transit-gateway-policy-table'|'transit-gateway-route-table'|'transit-gateway-route-table-announcement'|'volume'|'vpc'|'vpc-endpoint'|'vpc-endpoint-connection'|'vpc-endpoint-service'|'vpc-endpoint-service-permission'|'vpc-peering-connection'|'vpn-connection'|'vpn-gateway'|'vpc-flow-log'|'capacity-reservation-fleet'|'traffic-mirror-filter-rule'|'vpc-endpoint-connection-device-type'|'verified-access-instance'|'verified-access-group'|'verified-access-endpoint'|'verified-access-policy'|'verified-access-trust-provider'|'vpn-connection-device-type'|'vpc-block-public-access-exclusion'|'route-server'|'route-server-endpoint'|'route-server-peer'|'ipam-resource-discovery'|'ipam-resource-discovery-association'|'instance-connect-endpoint'|'verified-access-endpoint-target'|'ipam-external-resource-verification-token',
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
]
},
],
DryRun=True|False,
InstanceId='string',
Name='string',
Description='string',
NoReboot=True|False,
BlockDeviceMappings=[
{
'Ebs': {
'DeleteOnTermination': True|False,
'Iops': 123,
'SnapshotId': 'string',
'VolumeSize': 123,
'VolumeType': 'standard'|'io1'|'io2'|'gp2'|'sc1'|'st1'|'gp3',
'KmsKeyId': 'string',
'Throughput': 123,
'OutpostArn': 'string',
'Encrypted': True|False,
'VolumeInitializationRate': 123
},
'NoDevice': 'string',
'DeviceName': 'string',
'VirtualName': 'string'
},
]
)
list
The tags to apply to the AMI and snapshots on creation. You can tag the AMI, the snapshots, or both.
To tag the AMI, the value for ResourceType must be image.
To tag the snapshots that are created of the root volume and of other Amazon EBS volumes that are attached to the instance, the value for ResourceType must be snapshot. The same tag is applied to all of the snapshots that are created.
If you specify other values for ResourceType, the request fails.
To tag an AMI or snapshot after it has been created, see CreateTags.
(dict) --
The tags to apply to a resource when the resource is being created. When you specify a tag, you must specify the resource type to tag, otherwise the request will fail.
ResourceType (string) --
The type of resource to tag on creation.
Tags (list) --
The tags to apply to the resource.
(dict) --
Describes a tag.
Key (string) --
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maximum of 127 Unicode characters. May not begin with aws:.
Value (string) --
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maximum of 256 Unicode characters.
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.
string
[REQUIRED]
The ID of the instance.
string
[REQUIRED]
A name for the new image.
Constraints: 3-128 alphanumeric characters, parentheses (()), square brackets ([]), spaces ( ), periods (.), slashes (/), dashes (-), single quotes ('), at-signs (@), or underscores(_)
string
A description for the new image.
boolean
Indicates whether or not the instance should be automatically rebooted before creating the image. Specify one of the following values:
true - The instance is not rebooted before creating the image. This creates crash-consistent snapshots that include only the data that has been written to the volumes at the time the snapshots are created. Buffered data and data in memory that has not yet been written to the volumes is not included in the snapshots.
false - The instance is rebooted before creating the image. This ensures that all buffered data and data in memory is written to the volumes before the snapshots are created.
Default: false
list
The block device mappings.
When using the CreateImage action:
You can't change the volume size using the VolumeSize parameter. If you want a different volume size, you must first change the volume size of the source instance.
You can't modify the encryption status of existing volumes or snapshots. To create an AMI with volumes or snapshots that have a different encryption status (for example, where the source volume and snapshots are unencrypted, and you want to create an AMI with encrypted volumes or snapshots), use the CopyImage action.
The only option that can be changed for existing mappings or snapshots is DeleteOnTermination.
(dict) --
Describes a block device mapping, which defines the EBS volumes and instance store volumes to attach to an instance at launch.
Ebs (dict) --
Parameters used to automatically set up EBS volumes when the instance is launched.
DeleteOnTermination (boolean) --
Indicates whether the EBS volume is deleted on instance termination. For more information, see Preserving Amazon EBS volumes on instance termination in the Amazon EC2 User Guide.
Iops (integer) --
The number of I/O operations per second (IOPS). For gp3, io1, and io2 volumes, this represents the number of IOPS that are provisioned for the volume. For gp2 volumes, this represents the baseline performance of the volume and the rate at which the volume accumulates I/O credits for bursting.
The following are the supported values for each volume type:
gp3: 3,000 - 16,000 IOPS
io1: 100 - 64,000 IOPS
io2: 100 - 256,000 IOPS
For io2 volumes, you can achieve up to 256,000 IOPS on instances built on the Nitro System. On other instances, you can achieve performance up to 32,000 IOPS.
This parameter is required for io1 and io2 volumes. The default for gp3 volumes is 3,000 IOPS.
SnapshotId (string) --
The ID of the snapshot.
VolumeSize (integer) --
The size of the volume, in GiBs. You must specify either a snapshot ID or a volume size. If you specify a snapshot, the default is the snapshot size. You can specify a volume size that is equal to or larger than the snapshot size.
The following are the supported sizes for each volume type:
gp2 and gp3: 1 - 16,384 GiB
io1: 4 - 16,384 GiB
io2: 4 - 65,536 GiB
st1 and sc1: 125 - 16,384 GiB
standard: 1 - 1024 GiB
VolumeType (string) --
The volume type. For more information, see Amazon EBS volume types in the Amazon EBS User Guide.
KmsKeyId (string) --
Identifier (key ID, key alias, key ARN, or alias ARN) of the customer managed KMS key to use for EBS encryption.
This parameter is only supported on BlockDeviceMapping objects called by RunInstances, RequestSpotFleet, and RequestSpotInstances.
Throughput (integer) --
The throughput that the volume supports, in MiB/s.
This parameter is valid only for gp3 volumes.
Valid Range: Minimum value of 125. Maximum value of 1000.
OutpostArn (string) --
The ARN of the Outpost on which the snapshot is stored.
This parameter is not supported when using CreateImage.
Encrypted (boolean) --
Indicates whether the encryption state of an EBS volume is changed while being restored from a backing snapshot. The effect of setting the encryption state to true depends on the volume origin (new or from a snapshot), starting encryption state, ownership, and whether encryption by default is enabled. For more information, see Amazon EBS encryption in the Amazon EBS User Guide.
In no case can you remove encryption from an encrypted volume.
Encrypted volumes can only be attached to instances that support Amazon EBS encryption. For more information, see Supported instance types.
This parameter is not returned by DescribeImageAttribute.
For CreateImage and RegisterImage, whether you can include this parameter, and the allowed values differ depending on the type of block device mapping you are creating.
If you are creating a block device mapping for a new (empty) volume, you can include this parameter, and specify either true for an encrypted volume, or false for an unencrypted volume. If you omit this parameter, it defaults to false (unencrypted).
If you are creating a block device mapping from an existing encrypted or unencrypted snapshot, you must omit this parameter. If you include this parameter, the request will fail, regardless of the value that you specify.
If you are creating a block device mapping from an existing unencrypted volume, you can include this parameter, but you must specify false. If you specify true, the request will fail. In this case, we recommend that you omit the parameter.
If you are creating a block device mapping from an existing encrypted volume, you can include this parameter, and specify either true or false. However, if you specify false, the parameter is ignored and the block device mapping is always encrypted. In this case, we recommend that you omit the parameter.
VolumeInitializationRate (integer) --
Specifies the Amazon EBS Provisioned Rate for Volume Initialization (volume initialization rate), in MiB/s, at which to download the snapshot blocks from Amazon S3 to the volume. This is also known as volume initialization. Specifying a volume initialization rate ensures that the volume is initialized at a predictable and consistent rate after creation.
This parameter is supported only for volumes created from snapshots. Omit this parameter if:
You want to create the volume using fast snapshot restore. You must specify a snapshot that is enabled for fast snapshot restore. In this case, the volume is fully initialized at creation.
You want to create a volume that is initialized at the default rate.
For more information, see Initialize Amazon EBS volumes in the Amazon EC2 User Guide.
This parameter is not supported when using CreateImage.
Valid range: 100 - 300 MiB/s
NoDevice (string) --
To omit the device from the block device mapping, specify an empty string. When this property is specified, the device is removed from the block device mapping regardless of the assigned value.
DeviceName (string) --
The device name (for example, /dev/sdh or xvdh).
VirtualName (string) --
The virtual device name ( ephemeral``N). Instance store volumes are numbered starting from 0. An instance type with 2 available instance store volumes can specify mappings for ``ephemeral0 and ephemeral1. The number of available instance store volumes depends on the instance type. After you connect to the instance, you must mount the volume.
NVMe instance store volumes are automatically enumerated and assigned a device name. Including them in your block device mapping has no effect.
Constraints: For M3 instances, you must specify instance store volumes in the block device mapping for the instance. When you launch an M3 instance, we ignore any instance store volumes specified in the block device mapping for the AMI.
dict
Response Syntax
{
'ImageId': 'string'
}
Response Structure
(dict) --
ImageId (string) --
The ID of the new AMI.
{'LaunchTemplateData': {'BlockDeviceMappings': {'Ebs': {'VolumeInitializationRate': 'integer'}}}}
{'LaunchTemplateData': {'BlockDeviceMappings': {'Ebs': {'VolumeInitializationRate': 'integer'}}}}
Response {'LaunchTemplateVersion': {'LaunchTemplateData': {'BlockDeviceMappings': {'Ebs': {'VolumeInitializationRate': 'integer'}}}}}
{'VolumeInitializationRate': 'long'}
Replaces the EBS-backed root volume for a running instance with a new volume that is restored to the original root volume's launch state, that is restored to a specific snapshot taken from the original root volume, or that is restored from an AMI that has the same key characteristics as that of the instance.
For more information, see Replace a root volume in the Amazon EC2 User Guide.
See also: AWS API Documentation
Request Syntax
client.create_replace_root_volume_task(
InstanceId='string',
SnapshotId='string',
ClientToken='string',
DryRun=True|False,
TagSpecifications=[
{
'ResourceType': 'capacity-reservation'|'client-vpn-endpoint'|'customer-gateway'|'carrier-gateway'|'coip-pool'|'declarative-policies-report'|'dedicated-host'|'dhcp-options'|'egress-only-internet-gateway'|'elastic-ip'|'elastic-gpu'|'export-image-task'|'export-instance-task'|'fleet'|'fpga-image'|'host-reservation'|'image'|'import-image-task'|'import-snapshot-task'|'instance'|'instance-event-window'|'internet-gateway'|'ipam'|'ipam-pool'|'ipam-scope'|'ipv4pool-ec2'|'ipv6pool-ec2'|'key-pair'|'launch-template'|'local-gateway'|'local-gateway-route-table'|'local-gateway-virtual-interface'|'local-gateway-virtual-interface-group'|'local-gateway-route-table-vpc-association'|'local-gateway-route-table-virtual-interface-group-association'|'natgateway'|'network-acl'|'network-interface'|'network-insights-analysis'|'network-insights-path'|'network-insights-access-scope'|'network-insights-access-scope-analysis'|'outpost-lag'|'placement-group'|'prefix-list'|'replace-root-volume-task'|'reserved-instances'|'route-table'|'security-group'|'security-group-rule'|'service-link-virtual-interface'|'snapshot'|'spot-fleet-request'|'spot-instances-request'|'subnet'|'subnet-cidr-reservation'|'traffic-mirror-filter'|'traffic-mirror-session'|'traffic-mirror-target'|'transit-gateway'|'transit-gateway-attachment'|'transit-gateway-connect-peer'|'transit-gateway-multicast-domain'|'transit-gateway-policy-table'|'transit-gateway-route-table'|'transit-gateway-route-table-announcement'|'volume'|'vpc'|'vpc-endpoint'|'vpc-endpoint-connection'|'vpc-endpoint-service'|'vpc-endpoint-service-permission'|'vpc-peering-connection'|'vpn-connection'|'vpn-gateway'|'vpc-flow-log'|'capacity-reservation-fleet'|'traffic-mirror-filter-rule'|'vpc-endpoint-connection-device-type'|'verified-access-instance'|'verified-access-group'|'verified-access-endpoint'|'verified-access-policy'|'verified-access-trust-provider'|'vpn-connection-device-type'|'vpc-block-public-access-exclusion'|'route-server'|'route-server-endpoint'|'route-server-peer'|'ipam-resource-discovery'|'ipam-resource-discovery-association'|'instance-connect-endpoint'|'verified-access-endpoint-target'|'ipam-external-resource-verification-token',
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
]
},
],
ImageId='string',
DeleteReplacedRootVolume=True|False,
VolumeInitializationRate=123
)
string
[REQUIRED]
The ID of the instance for which to replace the root volume.
string
The ID of the snapshot from which to restore the replacement root volume. The specified snapshot must be a snapshot that you previously created from the original root volume.
If you want to restore the replacement root volume to the initial launch state, or if you want to restore the replacement root volume from an AMI, omit this parameter.
string
Unique, case-sensitive identifier you provide to ensure the idempotency of the request. If you do not specify a client token, a randomly generated token is used for the request to ensure idempotency. For more information, see Ensuring idempotency.
This field is autopopulated if not provided.
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.
list
The tags to apply to the root volume replacement task.
(dict) --
The tags to apply to a resource when the resource is being created. When you specify a tag, you must specify the resource type to tag, otherwise the request will fail.
ResourceType (string) --
The type of resource to tag on creation.
Tags (list) --
The tags to apply to the resource.
(dict) --
Describes a tag.
Key (string) --
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maximum of 127 Unicode characters. May not begin with aws:.
Value (string) --
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maximum of 256 Unicode characters.
string
The ID of the AMI to use to restore the root volume. The specified AMI must have the same product code, billing information, architecture type, and virtualization type as that of the instance.
If you want to restore the replacement volume from a specific snapshot, or if you want to restore it to its launch state, omit this parameter.
boolean
Indicates whether to automatically delete the original root volume after the root volume replacement task completes. To delete the original root volume, specify true. If you choose to keep the original root volume after the replacement task completes, you must manually delete it when you no longer need it.
integer
Specifies the Amazon EBS Provisioned Rate for Volume Initialization (volume initialization rate), in MiB/s, at which to download the snapshot blocks from Amazon S3 to the replacement root volume. This is also known as volume initialization. Specifying a volume initialization rate ensures that the volume is initialized at a predictable and consistent rate after creation.
Omit this parameter if:
You want to create the volume using fast snapshot restore. You must specify a snapshot that is enabled for fast snapshot restore. In this case, the volume is fully initialized at creation.
You want to create a volume that is initialized at the default rate.
For more information, see Initialize Amazon EBS volumes in the Amazon EC2 User Guide.
Valid range: 100 - 300 MiB/s
dict
Response Syntax
{
'ReplaceRootVolumeTask': {
'ReplaceRootVolumeTaskId': 'string',
'InstanceId': 'string',
'TaskState': 'pending'|'in-progress'|'failing'|'succeeded'|'failed'|'failed-detached',
'StartTime': 'string',
'CompleteTime': 'string',
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
],
'ImageId': 'string',
'SnapshotId': 'string',
'DeleteReplacedRootVolume': True|False
}
}
Response Structure
(dict) --
ReplaceRootVolumeTask (dict) --
Information about the root volume replacement task.
ReplaceRootVolumeTaskId (string) --
The ID of the root volume replacement task.
InstanceId (string) --
The ID of the instance for which the root volume replacement task was created.
TaskState (string) --
The state of the task. The task can be in one of the following states:
pending - the replacement volume is being created.
in-progress - the original volume is being detached and the replacement volume is being attached.
succeeded - the replacement volume has been successfully attached to the instance and the instance is available.
failing - the replacement task is in the process of failing.
failed - the replacement task has failed but the original root volume is still attached.
failing-detached - the replacement task is in the process of failing. The instance might have no root volume attached.
failed-detached - the replacement task has failed and the instance has no root volume attached.
StartTime (string) --
The time the task was started.
CompleteTime (string) --
The time the task completed.
Tags (list) --
The tags assigned to the task.
(dict) --
Describes a tag.
Key (string) --
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maximum of 127 Unicode characters. May not begin with aws:.
Value (string) --
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maximum of 256 Unicode characters.
ImageId (string) --
The ID of the AMI used to create the replacement root volume.
SnapshotId (string) --
The ID of the snapshot used to create the replacement root volume.
DeleteReplacedRootVolume (boolean) --
Indicates whether the original root volume is to be deleted after the root volume replacement task completes.
{'VolumeInitializationRate': 'integer'}
Creates an EBS volume that can be attached to an instance in the same Availability Zone.
You can create a new empty volume or restore a volume from an EBS snapshot. Any Amazon Web Services Marketplace product codes from the snapshot are propagated to the volume.
You can create encrypted volumes. Encrypted volumes must be attached to instances that support Amazon EBS encryption. Volumes that are created from encrypted snapshots are also automatically encrypted. For more information, see Amazon EBS encryption in the Amazon EBS User Guide.
You can tag your volumes during creation. For more information, see Tag your Amazon EC2 resources in the Amazon EC2 User Guide.
For more information, see Create an Amazon EBS volume in the Amazon EBS User Guide.
See also: AWS API Documentation
Request Syntax
client.create_volume(
AvailabilityZone='string',
Encrypted=True|False,
Iops=123,
KmsKeyId='string',
OutpostArn='string',
Size=123,
SnapshotId='string',
VolumeType='standard'|'io1'|'io2'|'gp2'|'sc1'|'st1'|'gp3',
TagSpecifications=[
{
'ResourceType': 'capacity-reservation'|'client-vpn-endpoint'|'customer-gateway'|'carrier-gateway'|'coip-pool'|'declarative-policies-report'|'dedicated-host'|'dhcp-options'|'egress-only-internet-gateway'|'elastic-ip'|'elastic-gpu'|'export-image-task'|'export-instance-task'|'fleet'|'fpga-image'|'host-reservation'|'image'|'import-image-task'|'import-snapshot-task'|'instance'|'instance-event-window'|'internet-gateway'|'ipam'|'ipam-pool'|'ipam-scope'|'ipv4pool-ec2'|'ipv6pool-ec2'|'key-pair'|'launch-template'|'local-gateway'|'local-gateway-route-table'|'local-gateway-virtual-interface'|'local-gateway-virtual-interface-group'|'local-gateway-route-table-vpc-association'|'local-gateway-route-table-virtual-interface-group-association'|'natgateway'|'network-acl'|'network-interface'|'network-insights-analysis'|'network-insights-path'|'network-insights-access-scope'|'network-insights-access-scope-analysis'|'outpost-lag'|'placement-group'|'prefix-list'|'replace-root-volume-task'|'reserved-instances'|'route-table'|'security-group'|'security-group-rule'|'service-link-virtual-interface'|'snapshot'|'spot-fleet-request'|'spot-instances-request'|'subnet'|'subnet-cidr-reservation'|'traffic-mirror-filter'|'traffic-mirror-session'|'traffic-mirror-target'|'transit-gateway'|'transit-gateway-attachment'|'transit-gateway-connect-peer'|'transit-gateway-multicast-domain'|'transit-gateway-policy-table'|'transit-gateway-route-table'|'transit-gateway-route-table-announcement'|'volume'|'vpc'|'vpc-endpoint'|'vpc-endpoint-connection'|'vpc-endpoint-service'|'vpc-endpoint-service-permission'|'vpc-peering-connection'|'vpn-connection'|'vpn-gateway'|'vpc-flow-log'|'capacity-reservation-fleet'|'traffic-mirror-filter-rule'|'vpc-endpoint-connection-device-type'|'verified-access-instance'|'verified-access-group'|'verified-access-endpoint'|'verified-access-policy'|'verified-access-trust-provider'|'vpn-connection-device-type'|'vpc-block-public-access-exclusion'|'route-server'|'route-server-endpoint'|'route-server-peer'|'ipam-resource-discovery'|'ipam-resource-discovery-association'|'instance-connect-endpoint'|'verified-access-endpoint-target'|'ipam-external-resource-verification-token',
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
]
},
],
MultiAttachEnabled=True|False,
Throughput=123,
ClientToken='string',
VolumeInitializationRate=123,
Operator={
'Principal': 'string'
},
DryRun=True|False
)
string
[REQUIRED]
The ID of the Availability Zone in which to create the volume. For example, us-east-1a.
boolean
Indicates whether the volume should be encrypted. The effect of setting the encryption state to true depends on the volume origin (new or from a snapshot), starting encryption state, ownership, and whether encryption by default is enabled. For more information, see Encryption by default in the Amazon EBS User Guide.
Encrypted Amazon EBS volumes must be attached to instances that support Amazon EBS encryption. For more information, see Supported instance types.
integer
The number of I/O operations per second (IOPS). For gp3, io1, and io2 volumes, this represents the number of IOPS that are provisioned for the volume. For gp2 volumes, this represents the baseline performance of the volume and the rate at which the volume accumulates I/O credits for bursting.
The following are the supported values for each volume type:
gp3: 3,000 - 16,000 IOPS
io1: 100 - 64,000 IOPS
io2: 100 - 256,000 IOPS
For io2 volumes, you can achieve up to 256,000 IOPS on instances built on the Nitro System. On other instances, you can achieve performance up to 32,000 IOPS.
This parameter is required for io1 and io2 volumes. The default for gp3 volumes is 3,000 IOPS. This parameter is not supported for gp2, st1, sc1, or standard volumes.
string
The identifier of the KMS key to use for Amazon EBS encryption. If this parameter is not specified, your KMS key for Amazon EBS is used. If KmsKeyId is specified, the encrypted state must be true.
You can specify the KMS key using any of the following:
Key ID. For example, 1234abcd-12ab-34cd-56ef-1234567890ab.
Key alias. For example, alias/ExampleAlias.
Key ARN. For example, arn:aws:kms:us-east-1:012345678910:key/1234abcd-12ab-34cd-56ef-1234567890ab.
Alias ARN. For example, arn:aws:kms:us-east-1:012345678910:alias/ExampleAlias.
Amazon Web Services authenticates the KMS key asynchronously. Therefore, if you specify an ID, alias, or ARN that is not valid, the action can appear to complete, but eventually fails.
string
The Amazon Resource Name (ARN) of the Outpost on which to create the volume.
If you intend to use a volume with an instance running on an outpost, then you must create the volume on the same outpost as the instance. You can't use a volume created in an Amazon Web Services Region with an instance on an Amazon Web Services outpost, or the other way around.
integer
The size of the volume, in GiBs. You must specify either a snapshot ID or a volume size. If you specify a snapshot, the default is the snapshot size. You can specify a volume size that is equal to or larger than the snapshot size.
The following are the supported volumes sizes for each volume type:
gp2 and gp3: 1 - 16,384 GiB
io1: 4 - 16,384 GiB
io2: 4 - 65,536 GiB
st1 and sc1: 125 - 16,384 GiB
standard: 1 - 1024 GiB
string
The snapshot from which to create the volume. You must specify either a snapshot ID or a volume size.
string
The volume type. This parameter can be one of the following values:
General Purpose SSD: gp2 | gp3
Provisioned IOPS SSD: io1 | io2
Throughput Optimized HDD: st1
Cold HDD: sc1
Magnetic: standard
For more information, see Amazon EBS volume types in the Amazon EBS User Guide.
Default: gp2
list
The tags to apply to the volume during creation.
(dict) --
The tags to apply to a resource when the resource is being created. When you specify a tag, you must specify the resource type to tag, otherwise the request will fail.
ResourceType (string) --
The type of resource to tag on creation.
Tags (list) --
The tags to apply to the resource.
(dict) --
Describes a tag.
Key (string) --
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maximum of 127 Unicode characters. May not begin with aws:.
Value (string) --
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maximum of 256 Unicode characters.
boolean
Indicates whether to enable Amazon EBS Multi-Attach. If you enable Multi-Attach, you can attach the volume to up to 16 Instances built on the Nitro System in the same Availability Zone. This parameter is supported with io1 and io2 volumes only. For more information, see Amazon EBS Multi-Attach in the Amazon EBS User Guide.
integer
The throughput to provision for a volume, with a maximum of 1,000 MiB/s.
This parameter is valid only for gp3 volumes.
Valid Range: Minimum value of 125. Maximum value of 1000.
string
Unique, case-sensitive identifier that you provide to ensure the idempotency of the request. For more information, see Ensure Idempotency.
This field is autopopulated if not provided.
integer
Specifies the Amazon EBS Provisioned Rate for Volume Initialization (volume initialization rate), in MiB/s, at which to download the snapshot blocks from Amazon S3 to the volume. This is also known as volume initialization. Specifying a volume initialization rate ensures that the volume is initialized at a predictable and consistent rate after creation.
This parameter is supported only for volumes created from snapshots. Omit this parameter if:
You want to create the volume using fast snapshot restore. You must specify a snapshot that is enabled for fast snapshot restore. In this case, the volume is fully initialized at creation.
You want to create a volume that is initialized at the default rate.
For more information, see Initialize Amazon EBS volumes in the Amazon EC2 User Guide.
Valid range: 100 - 300 MiB/s
dict
Reserved for internal use.
Principal (string) --
The service provider that manages the resource.
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.
dict
Response Syntax
{
'OutpostArn': 'string',
'Iops': 123,
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
],
'VolumeType': 'standard'|'io1'|'io2'|'gp2'|'sc1'|'st1'|'gp3',
'FastRestored': True|False,
'MultiAttachEnabled': True|False,
'Throughput': 123,
'SseType': 'sse-ebs'|'sse-kms'|'none',
'Operator': {
'Managed': True|False,
'Principal': 'string'
},
'VolumeInitializationRate': 123,
'VolumeId': 'string',
'Size': 123,
'SnapshotId': 'string',
'AvailabilityZone': 'string',
'State': 'creating'|'available'|'in-use'|'deleting'|'deleted'|'error',
'CreateTime': datetime(2015, 1, 1),
'Attachments': [
{
'DeleteOnTermination': True|False,
'AssociatedResource': 'string',
'InstanceOwningService': 'string',
'VolumeId': 'string',
'InstanceId': 'string',
'Device': 'string',
'State': 'attaching'|'attached'|'detaching'|'detached'|'busy',
'AttachTime': datetime(2015, 1, 1)
},
],
'Encrypted': True|False,
'KmsKeyId': 'string'
}
Response Structure
(dict) --
Describes a volume.
OutpostArn (string) --
The Amazon Resource Name (ARN) of the Outpost.
Iops (integer) --
The number of I/O operations per second (IOPS). For gp3, io1, and io2 volumes, this represents the number of IOPS that are provisioned for the volume. For gp2 volumes, this represents the baseline performance of the volume and the rate at which the volume accumulates I/O credits for bursting.
Tags (list) --
Any tags assigned to the volume.
(dict) --
Describes a tag.
Key (string) --
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maximum of 127 Unicode characters. May not begin with aws:.
Value (string) --
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maximum of 256 Unicode characters.
VolumeType (string) --
The volume type.
FastRestored (boolean) --
Indicates whether the volume was created using fast snapshot restore.
MultiAttachEnabled (boolean) --
Indicates whether Amazon EBS Multi-Attach is enabled.
Throughput (integer) --
The throughput that the volume supports, in MiB/s.
SseType (string) --
Reserved for future use.
Operator (dict) --
The service provider that manages the volume.
Managed (boolean) --
If true, the resource is managed by a service provider.
Principal (string) --
If managed is true, then the principal is returned. The principal is the service provider that manages the resource.
VolumeInitializationRate (integer) --
The Amazon EBS Provisioned Rate for Volume Initialization (volume initialization rate) specified for the volume during creation, in MiB/s. If no volume initialization rate was specified, the value is null.
VolumeId (string) --
The ID of the volume.
Size (integer) --
The size of the volume, in GiBs.
SnapshotId (string) --
The snapshot from which the volume was created, if applicable.
AvailabilityZone (string) --
The Availability Zone for the volume.
State (string) --
The volume state.
CreateTime (datetime) --
The time stamp when volume creation was initiated.
Attachments (list) --
Information about the volume attachments.
(dict) --
Describes volume attachment details.
DeleteOnTermination (boolean) --
Indicates whether the EBS volume is deleted on instance termination.
AssociatedResource (string) --
The ARN of the Amazon ECS or Fargate task to which the volume is attached.
InstanceOwningService (string) --
The service principal of Amazon Web Services service that owns the underlying instance to which the volume is attached.
This parameter is returned only for volumes that are attached to Fargate tasks.
VolumeId (string) --
The ID of the volume.
InstanceId (string) --
The ID of the instance.
If the volume is attached to a Fargate task, this parameter returns null.
Device (string) --
The device name.
If the volume is attached to a Fargate task, this parameter returns null.
State (string) --
The attachment state of the volume.
AttachTime (datetime) --
The time stamp when the attachment initiated.
Encrypted (boolean) --
Indicates whether the volume is encrypted.
KmsKeyId (string) --
The Amazon Resource Name (ARN) of the KMS key that was used to protect the volume encryption key for the volume.
{'BlockDeviceMappings': {'Ebs': {'VolumeInitializationRate': 'integer'}}}
Describes the specified attribute of the specified AMI. You can specify only one attribute at a time.
See also: AWS API Documentation
Request Syntax
client.describe_image_attribute(
Attribute='description'|'kernel'|'ramdisk'|'launchPermission'|'productCodes'|'blockDeviceMapping'|'sriovNetSupport'|'bootMode'|'tpmSupport'|'uefiData'|'lastLaunchedTime'|'imdsSupport'|'deregistrationProtection',
ImageId='string',
DryRun=True|False
)
string
[REQUIRED]
The AMI attribute.
Note: The blockDeviceMapping attribute is deprecated. Using this attribute returns the Client.AuthFailure error. To get information about the block device mappings for an AMI, use the DescribeImages action.
string
[REQUIRED]
The ID of the AMI.
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.
dict
Response Syntax
{
'Description': {
'Value': 'string'
},
'KernelId': {
'Value': 'string'
},
'RamdiskId': {
'Value': 'string'
},
'SriovNetSupport': {
'Value': 'string'
},
'BootMode': {
'Value': 'string'
},
'TpmSupport': {
'Value': 'string'
},
'UefiData': {
'Value': 'string'
},
'LastLaunchedTime': {
'Value': 'string'
},
'ImdsSupport': {
'Value': 'string'
},
'DeregistrationProtection': {
'Value': 'string'
},
'ImageId': 'string',
'LaunchPermissions': [
{
'OrganizationArn': 'string',
'OrganizationalUnitArn': 'string',
'UserId': 'string',
'Group': 'all'
},
],
'ProductCodes': [
{
'ProductCodeId': 'string',
'ProductCodeType': 'devpay'|'marketplace'
},
],
'BlockDeviceMappings': [
{
'Ebs': {
'DeleteOnTermination': True|False,
'Iops': 123,
'SnapshotId': 'string',
'VolumeSize': 123,
'VolumeType': 'standard'|'io1'|'io2'|'gp2'|'sc1'|'st1'|'gp3',
'KmsKeyId': 'string',
'Throughput': 123,
'OutpostArn': 'string',
'Encrypted': True|False,
'VolumeInitializationRate': 123
},
'NoDevice': 'string',
'DeviceName': 'string',
'VirtualName': 'string'
},
]
}
Response Structure
(dict) --
Describes an image attribute.
Description (dict) --
A description for the AMI.
Value (string) --
The attribute value. The value is case-sensitive.
KernelId (dict) --
The kernel ID.
Value (string) --
The attribute value. The value is case-sensitive.
RamdiskId (dict) --
The RAM disk ID.
Value (string) --
The attribute value. The value is case-sensitive.
SriovNetSupport (dict) --
Indicates whether enhanced networking with the Intel 82599 Virtual Function interface is enabled.
Value (string) --
The attribute value. The value is case-sensitive.
BootMode (dict) --
The boot mode.
Value (string) --
The attribute value. The value is case-sensitive.
TpmSupport (dict) --
If the image is configured for NitroTPM support, the value is v2.0.
Value (string) --
The attribute value. The value is case-sensitive.
UefiData (dict) --
Base64 representation of the non-volatile UEFI variable store. To retrieve the UEFI data, use the GetInstanceUefiData command. You can inspect and modify the UEFI data by using the python-uefivars tool on GitHub. For more information, see UEFI Secure Boot in the Amazon EC2 User Guide.
Value (string) --
The attribute value. The value is case-sensitive.
LastLaunchedTime (dict) --
The date and time, in ISO 8601 date-time format, when the AMI was last used to launch an EC2 instance. When the AMI is used to launch an instance, there is a 24-hour delay before that usage is reported.
Value (string) --
The attribute value. The value is case-sensitive.
ImdsSupport (dict) --
If v2.0, it indicates that IMDSv2 is specified in the AMI. Instances launched from this AMI will have HttpTokens automatically set to required so that, by default, the instance requires that IMDSv2 is used when requesting instance metadata. In addition, HttpPutResponseHopLimit is set to 2. For more information, see Configure the AMI in the Amazon EC2 User Guide.
Value (string) --
The attribute value. The value is case-sensitive.
DeregistrationProtection (dict) --
Indicates whether deregistration protection is enabled for the AMI.
Value (string) --
The attribute value. The value is case-sensitive.
ImageId (string) --
The ID of the AMI.
LaunchPermissions (list) --
The launch permissions.
(dict) --
Describes a launch permission.
OrganizationArn (string) --
The Amazon Resource Name (ARN) of an organization.
OrganizationalUnitArn (string) --
The Amazon Resource Name (ARN) of an organizational unit (OU).
UserId (string) --
The Amazon Web Services account ID.
Constraints: Up to 10 000 account IDs can be specified in a single request.
Group (string) --
The name of the group.
ProductCodes (list) --
The product codes.
(dict) --
Describes a product code.
ProductCodeId (string) --
The product code.
ProductCodeType (string) --
The type of product code.
BlockDeviceMappings (list) --
The block device mapping entries.
(dict) --
Describes a block device mapping, which defines the EBS volumes and instance store volumes to attach to an instance at launch.
Ebs (dict) --
Parameters used to automatically set up EBS volumes when the instance is launched.
DeleteOnTermination (boolean) --
Indicates whether the EBS volume is deleted on instance termination. For more information, see Preserving Amazon EBS volumes on instance termination in the Amazon EC2 User Guide.
Iops (integer) --
The number of I/O operations per second (IOPS). For gp3, io1, and io2 volumes, this represents the number of IOPS that are provisioned for the volume. For gp2 volumes, this represents the baseline performance of the volume and the rate at which the volume accumulates I/O credits for bursting.
The following are the supported values for each volume type:
gp3: 3,000 - 16,000 IOPS
io1: 100 - 64,000 IOPS
io2: 100 - 256,000 IOPS
For io2 volumes, you can achieve up to 256,000 IOPS on instances built on the Nitro System. On other instances, you can achieve performance up to 32,000 IOPS.
This parameter is required for io1 and io2 volumes. The default for gp3 volumes is 3,000 IOPS.
SnapshotId (string) --
The ID of the snapshot.
VolumeSize (integer) --
The size of the volume, in GiBs. You must specify either a snapshot ID or a volume size. If you specify a snapshot, the default is the snapshot size. You can specify a volume size that is equal to or larger than the snapshot size.
The following are the supported sizes for each volume type:
gp2 and gp3: 1 - 16,384 GiB
io1: 4 - 16,384 GiB
io2: 4 - 65,536 GiB
st1 and sc1: 125 - 16,384 GiB
standard: 1 - 1024 GiB
VolumeType (string) --
The volume type. For more information, see Amazon EBS volume types in the Amazon EBS User Guide.
KmsKeyId (string) --
Identifier (key ID, key alias, key ARN, or alias ARN) of the customer managed KMS key to use for EBS encryption.
This parameter is only supported on BlockDeviceMapping objects called by RunInstances, RequestSpotFleet, and RequestSpotInstances.
Throughput (integer) --
The throughput that the volume supports, in MiB/s.
This parameter is valid only for gp3 volumes.
Valid Range: Minimum value of 125. Maximum value of 1000.
OutpostArn (string) --
The ARN of the Outpost on which the snapshot is stored.
This parameter is not supported when using CreateImage.
Encrypted (boolean) --
Indicates whether the encryption state of an EBS volume is changed while being restored from a backing snapshot. The effect of setting the encryption state to true depends on the volume origin (new or from a snapshot), starting encryption state, ownership, and whether encryption by default is enabled. For more information, see Amazon EBS encryption in the Amazon EBS User Guide.
In no case can you remove encryption from an encrypted volume.
Encrypted volumes can only be attached to instances that support Amazon EBS encryption. For more information, see Supported instance types.
This parameter is not returned by DescribeImageAttribute.
For CreateImage and RegisterImage, whether you can include this parameter, and the allowed values differ depending on the type of block device mapping you are creating.
If you are creating a block device mapping for a new (empty) volume, you can include this parameter, and specify either true for an encrypted volume, or false for an unencrypted volume. If you omit this parameter, it defaults to false (unencrypted).
If you are creating a block device mapping from an existing encrypted or unencrypted snapshot, you must omit this parameter. If you include this parameter, the request will fail, regardless of the value that you specify.
If you are creating a block device mapping from an existing unencrypted volume, you can include this parameter, but you must specify false. If you specify true, the request will fail. In this case, we recommend that you omit the parameter.
If you are creating a block device mapping from an existing encrypted volume, you can include this parameter, and specify either true or false. However, if you specify false, the parameter is ignored and the block device mapping is always encrypted. In this case, we recommend that you omit the parameter.
VolumeInitializationRate (integer) --
Specifies the Amazon EBS Provisioned Rate for Volume Initialization (volume initialization rate), in MiB/s, at which to download the snapshot blocks from Amazon S3 to the volume. This is also known as volume initialization. Specifying a volume initialization rate ensures that the volume is initialized at a predictable and consistent rate after creation.
This parameter is supported only for volumes created from snapshots. Omit this parameter if:
You want to create the volume using fast snapshot restore. You must specify a snapshot that is enabled for fast snapshot restore. In this case, the volume is fully initialized at creation.
You want to create a volume that is initialized at the default rate.
For more information, see Initialize Amazon EBS volumes in the Amazon EC2 User Guide.
This parameter is not supported when using CreateImage.
Valid range: 100 - 300 MiB/s
NoDevice (string) --
To omit the device from the block device mapping, specify an empty string. When this property is specified, the device is removed from the block device mapping regardless of the assigned value.
DeviceName (string) --
The device name (for example, /dev/sdh or xvdh).
VirtualName (string) --
The virtual device name ( ephemeral``N). Instance store volumes are numbered starting from 0. An instance type with 2 available instance store volumes can specify mappings for ``ephemeral0 and ephemeral1. The number of available instance store volumes depends on the instance type. After you connect to the instance, you must mount the volume.
NVMe instance store volumes are automatically enumerated and assigned a device name. Including them in your block device mapping has no effect.
Constraints: For M3 instances, you must specify instance store volumes in the block device mapping for the instance. When you launch an M3 instance, we ignore any instance store volumes specified in the block device mapping for the AMI.
{'Images': {'BlockDeviceMappings': {'Ebs': {'VolumeInitializationRate': 'integer'}}}}
Describes the specified images (AMIs, AKIs, and ARIs) available to you or all of the images available to you.
The images available to you include public images, private images that you own, and private images owned by other Amazon Web Services accounts for which you have explicit launch permissions.
Recently deregistered images appear in the returned results for a short interval and then return empty results. After all instances that reference a deregistered AMI are terminated, specifying the ID of the image will eventually return an error indicating that the AMI ID cannot be found.
When Allowed AMIs is set to enabled, only allowed images are returned in the results, with the imageAllowed field set to true for each image. In audit-mode, the imageAllowed field is set to true for images that meet the account's Allowed AMIs criteria, and false for images that don't meet the criteria. For more information, see EnableAllowedImagesSettings.
See also: AWS API Documentation
Request Syntax
client.describe_images(
ExecutableUsers=[
'string',
],
ImageIds=[
'string',
],
Owners=[
'string',
],
IncludeDeprecated=True|False,
IncludeDisabled=True|False,
MaxResults=123,
NextToken='string',
DryRun=True|False,
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
]
)
list
Scopes the images by users with explicit launch permissions. Specify an Amazon Web Services account ID, self (the sender of the request), or all (public AMIs).
If you specify an Amazon Web Services account ID that is not your own, only AMIs shared with that specific Amazon Web Services account ID are returned. However, AMIs that are shared with the account’s organization or organizational unit (OU) are not returned.
If you specify self or your own Amazon Web Services account ID, AMIs shared with your account are returned. In addition, AMIs that are shared with the organization or OU of which you are member are also returned.
If you specify all, all public AMIs are returned.
(string) --
list
The image IDs.
Default: Describes all images available to you.
(string) --
list
Scopes the results to images with the specified owners. You can specify a combination of Amazon Web Services account IDs, self, amazon, aws-backup-vault, and aws-marketplace. If you omit this parameter, the results include all images for which you have launch permissions, regardless of ownership.
(string) --
boolean
Specifies whether to include deprecated AMIs.
Default: No deprecated AMIs are included in the response.
boolean
Specifies whether to include disabled AMIs.
Default: No disabled AMIs are included in the response.
integer
The maximum number of items to return for this request. To get the next page of items, make another request with the token returned in the output. For more information, see Pagination.
string
The token returned from a previous paginated request. Pagination continues from the end of the items returned by the previous request.
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.
list
The filters.
architecture - The image architecture ( i386 | x86_64 | arm64 | x86_64_mac | arm64_mac).
block-device-mapping.delete-on-termination - A Boolean value that indicates whether the Amazon EBS volume is deleted on instance termination.
block-device-mapping.device-name - The device name specified in the block device mapping (for example, /dev/sdh or xvdh).
block-device-mapping.snapshot-id - The ID of the snapshot used for the Amazon EBS volume.
block-device-mapping.volume-size - The volume size of the Amazon EBS volume, in GiB.
block-device-mapping.volume-type - The volume type of the Amazon EBS volume ( io1 | io2 | gp2 | gp3 | sc1 ``| ``st1 | standard).
block-device-mapping.encrypted - A Boolean that indicates whether the Amazon EBS volume is encrypted.
creation-date - The time when the image was created, in the ISO 8601 format in the UTC time zone (YYYY-MM-DDThh:mm:ss.sssZ), for example, 2021-09-29T11:04:43.305Z. You can use a wildcard ( *), for example, 2021-09-29T*, which matches an entire day.
description - The description of the image (provided during image creation).
ena-support - A Boolean that indicates whether enhanced networking with ENA is enabled.
hypervisor - The hypervisor type ( ovm | xen).
image-allowed - A Boolean that indicates whether the image meets the criteria specified for Allowed AMIs.
image-id - The ID of the image.
image-type - The image type ( machine | kernel | ramdisk).
is-public - A Boolean that indicates whether the image is public.
kernel-id - The kernel ID.
manifest-location - The location of the image manifest.
name - The name of the AMI (provided during image creation).
owner-alias - The owner alias ( amazon | aws-backup-vault | aws-marketplace). The valid aliases are defined in an Amazon-maintained list. This is not the Amazon Web Services account alias that can be set using the IAM console. We recommend that you use the Owner request parameter instead of this filter.
owner-id - The Amazon Web Services account ID of the owner. We recommend that you use the Owner request parameter instead of this filter.
platform - The platform. The only supported value is windows.
product-code - The product code.
product-code.type - The type of the product code ( marketplace).
ramdisk-id - The RAM disk ID.
root-device-name - The device name of the root device volume (for example, /dev/sda1).
root-device-type - The type of the root device volume ( ebs | instance-store).
source-image-id - The ID of the source AMI from which the AMI was created.
source-image-region - The Region of the source AMI.
source-instance-id - The ID of the instance that the AMI was created from if the AMI was created using CreateImage. This filter is applicable only if the AMI was created using CreateImage.
state - The state of the image ( available | pending | failed).
state-reason-code - The reason code for the state change.
state-reason-message - The message for the state change.
sriov-net-support - A value of simple indicates that enhanced networking with the Intel 82599 VF interface is enabled.
tag:<key> - The key/value combination of a tag assigned to the resource. Use the tag key in the filter name and the tag value as the filter value. For example, to find all resources that have a tag with the key Owner and the value TeamA, specify tag:Owner for the filter name and TeamA for the filter value.
tag-key - The key of a tag assigned to the resource. Use this filter to find all resources assigned a tag with a specific key, regardless of the tag value.
virtualization-type - The virtualization type ( paravirtual | hvm).
(dict) --
A filter name and value pair that is used to return a more specific list of results from a describe operation. Filters can be used to match a set of resources by specific criteria, such as tags, attributes, or IDs.
If you specify multiple filters, the filters are joined with an AND, and the request returns only results that match all of the specified filters.
For more information, see List and filter using the CLI and API in the Amazon EC2 User Guide.
Name (string) --
The name of the filter. Filter names are case-sensitive.
Values (list) --
The filter values. Filter values are case-sensitive. If you specify multiple values for a filter, the values are joined with an OR, and the request returns all results that match any of the specified values.
(string) --
dict
Response Syntax
{
'NextToken': 'string',
'Images': [
{
'PlatformDetails': 'string',
'UsageOperation': 'string',
'BlockDeviceMappings': [
{
'Ebs': {
'DeleteOnTermination': True|False,
'Iops': 123,
'SnapshotId': 'string',
'VolumeSize': 123,
'VolumeType': 'standard'|'io1'|'io2'|'gp2'|'sc1'|'st1'|'gp3',
'KmsKeyId': 'string',
'Throughput': 123,
'OutpostArn': 'string',
'Encrypted': True|False,
'VolumeInitializationRate': 123
},
'NoDevice': 'string',
'DeviceName': 'string',
'VirtualName': 'string'
},
],
'Description': 'string',
'EnaSupport': True|False,
'Hypervisor': 'ovm'|'xen',
'ImageOwnerAlias': 'string',
'Name': 'string',
'RootDeviceName': 'string',
'RootDeviceType': 'ebs'|'instance-store',
'SriovNetSupport': 'string',
'StateReason': {
'Code': 'string',
'Message': 'string'
},
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
],
'VirtualizationType': 'hvm'|'paravirtual',
'BootMode': 'legacy-bios'|'uefi'|'uefi-preferred',
'TpmSupport': 'v2.0',
'DeprecationTime': 'string',
'ImdsSupport': 'v2.0',
'SourceInstanceId': 'string',
'DeregistrationProtection': 'string',
'LastLaunchedTime': 'string',
'ImageAllowed': True|False,
'SourceImageId': 'string',
'SourceImageRegion': 'string',
'ImageId': 'string',
'ImageLocation': 'string',
'State': 'pending'|'available'|'invalid'|'deregistered'|'transient'|'failed'|'error'|'disabled',
'OwnerId': 'string',
'CreationDate': 'string',
'Public': True|False,
'ProductCodes': [
{
'ProductCodeId': 'string',
'ProductCodeType': 'devpay'|'marketplace'
},
],
'Architecture': 'i386'|'x86_64'|'arm64'|'x86_64_mac'|'arm64_mac',
'ImageType': 'machine'|'kernel'|'ramdisk',
'KernelId': 'string',
'RamdiskId': 'string',
'Platform': 'Windows'
},
]
}
Response Structure
(dict) --
NextToken (string) --
The token to include in another request to get the next page of items. This value is null when there are no more items to return.
Images (list) --
Information about the images.
(dict) --
Describes an image.
PlatformDetails (string) --
The platform details associated with the billing code of the AMI. For more information, see Understand AMI billing information in the Amazon EC2 User Guide.
UsageOperation (string) --
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 Amazon Web Services Cost and Usage Report and in the Amazon Web Services Price List API. You can view these fields on the Instances or AMIs pages in the Amazon EC2 console, or in the responses that are returned by the DescribeImages command in the Amazon EC2 API, or the describe-images command in the CLI.
BlockDeviceMappings (list) --
Any block device mapping entries.
(dict) --
Describes a block device mapping, which defines the EBS volumes and instance store volumes to attach to an instance at launch.
Ebs (dict) --
Parameters used to automatically set up EBS volumes when the instance is launched.
DeleteOnTermination (boolean) --
Indicates whether the EBS volume is deleted on instance termination. For more information, see Preserving Amazon EBS volumes on instance termination in the Amazon EC2 User Guide.
Iops (integer) --
The number of I/O operations per second (IOPS). For gp3, io1, and io2 volumes, this represents the number of IOPS that are provisioned for the volume. For gp2 volumes, this represents the baseline performance of the volume and the rate at which the volume accumulates I/O credits for bursting.
The following are the supported values for each volume type:
gp3: 3,000 - 16,000 IOPS
io1: 100 - 64,000 IOPS
io2: 100 - 256,000 IOPS
For io2 volumes, you can achieve up to 256,000 IOPS on instances built on the Nitro System. On other instances, you can achieve performance up to 32,000 IOPS.
This parameter is required for io1 and io2 volumes. The default for gp3 volumes is 3,000 IOPS.
SnapshotId (string) --
The ID of the snapshot.
VolumeSize (integer) --
The size of the volume, in GiBs. You must specify either a snapshot ID or a volume size. If you specify a snapshot, the default is the snapshot size. You can specify a volume size that is equal to or larger than the snapshot size.
The following are the supported sizes for each volume type:
gp2 and gp3: 1 - 16,384 GiB
io1: 4 - 16,384 GiB
io2: 4 - 65,536 GiB
st1 and sc1: 125 - 16,384 GiB
standard: 1 - 1024 GiB
VolumeType (string) --
The volume type. For more information, see Amazon EBS volume types in the Amazon EBS User Guide.
KmsKeyId (string) --
Identifier (key ID, key alias, key ARN, or alias ARN) of the customer managed KMS key to use for EBS encryption.
This parameter is only supported on BlockDeviceMapping objects called by RunInstances, RequestSpotFleet, and RequestSpotInstances.
Throughput (integer) --
The throughput that the volume supports, in MiB/s.
This parameter is valid only for gp3 volumes.
Valid Range: Minimum value of 125. Maximum value of 1000.
OutpostArn (string) --
The ARN of the Outpost on which the snapshot is stored.
This parameter is not supported when using CreateImage.
Encrypted (boolean) --
Indicates whether the encryption state of an EBS volume is changed while being restored from a backing snapshot. The effect of setting the encryption state to true depends on the volume origin (new or from a snapshot), starting encryption state, ownership, and whether encryption by default is enabled. For more information, see Amazon EBS encryption in the Amazon EBS User Guide.
In no case can you remove encryption from an encrypted volume.
Encrypted volumes can only be attached to instances that support Amazon EBS encryption. For more information, see Supported instance types.
This parameter is not returned by DescribeImageAttribute.
For CreateImage and RegisterImage, whether you can include this parameter, and the allowed values differ depending on the type of block device mapping you are creating.
If you are creating a block device mapping for a new (empty) volume, you can include this parameter, and specify either true for an encrypted volume, or false for an unencrypted volume. If you omit this parameter, it defaults to false (unencrypted).
If you are creating a block device mapping from an existing encrypted or unencrypted snapshot, you must omit this parameter. If you include this parameter, the request will fail, regardless of the value that you specify.
If you are creating a block device mapping from an existing unencrypted volume, you can include this parameter, but you must specify false. If you specify true, the request will fail. In this case, we recommend that you omit the parameter.
If you are creating a block device mapping from an existing encrypted volume, you can include this parameter, and specify either true or false. However, if you specify false, the parameter is ignored and the block device mapping is always encrypted. In this case, we recommend that you omit the parameter.
VolumeInitializationRate (integer) --
Specifies the Amazon EBS Provisioned Rate for Volume Initialization (volume initialization rate), in MiB/s, at which to download the snapshot blocks from Amazon S3 to the volume. This is also known as volume initialization. Specifying a volume initialization rate ensures that the volume is initialized at a predictable and consistent rate after creation.
This parameter is supported only for volumes created from snapshots. Omit this parameter if:
You want to create the volume using fast snapshot restore. You must specify a snapshot that is enabled for fast snapshot restore. In this case, the volume is fully initialized at creation.
You want to create a volume that is initialized at the default rate.
For more information, see Initialize Amazon EBS volumes in the Amazon EC2 User Guide.
This parameter is not supported when using CreateImage.
Valid range: 100 - 300 MiB/s
NoDevice (string) --
To omit the device from the block device mapping, specify an empty string. When this property is specified, the device is removed from the block device mapping regardless of the assigned value.
DeviceName (string) --
The device name (for example, /dev/sdh or xvdh).
VirtualName (string) --
The virtual device name ( ephemeral``N). Instance store volumes are numbered starting from 0. An instance type with 2 available instance store volumes can specify mappings for ``ephemeral0 and ephemeral1. The number of available instance store volumes depends on the instance type. After you connect to the instance, you must mount the volume.
NVMe instance store volumes are automatically enumerated and assigned a device name. Including them in your block device mapping has no effect.
Constraints: For M3 instances, you must specify instance store volumes in the block device mapping for the instance. When you launch an M3 instance, we ignore any instance store volumes specified in the block device mapping for the AMI.
Description (string) --
The description of the AMI that was provided during image creation.
EnaSupport (boolean) --
Specifies whether enhanced networking with ENA is enabled.
Hypervisor (string) --
The hypervisor type of the image. Only xen is supported. ovm is not supported.
ImageOwnerAlias (string) --
The owner alias ( amazon | aws-backup-vault | aws-marketplace).
Name (string) --
The name of the AMI that was provided during image creation.
RootDeviceName (string) --
The device name of the root device volume (for example, /dev/sda1).
RootDeviceType (string) --
The type of root device used by the AMI. The AMI can use an Amazon EBS volume or an instance store volume.
SriovNetSupport (string) --
Specifies whether enhanced networking with the Intel 82599 Virtual Function interface is enabled.
StateReason (dict) --
The reason for the state change.
Code (string) --
The reason code for the state change.
Message (string) --
The message for the state change.
Server.InsufficientInstanceCapacity: There was insufficient capacity available to satisfy the launch request.
Server.InternalError: An internal error caused the instance to terminate during launch.
Server.ScheduledStop: The instance was stopped due to a scheduled retirement.
Server.SpotInstanceShutdown: The instance was stopped because the number of Spot requests with a maximum price equal to or higher than the Spot price exceeded available capacity or because of an increase in the Spot price.
Server.SpotInstanceTermination: The instance was terminated because the number of Spot requests with a maximum price equal to or higher than the Spot price exceeded available capacity or because of an increase in the Spot price.
Client.InstanceInitiatedShutdown: The instance was shut down from the operating system of the instance.
Client.InstanceTerminated: The instance was terminated or rebooted during AMI creation.
Client.InternalError: A client error caused the instance to terminate during launch.
Client.InvalidSnapshot.NotFound: The specified snapshot was not found.
Client.UserInitiatedHibernate: Hibernation was initiated on the instance.
Client.UserInitiatedShutdown: The instance was shut down using the Amazon EC2 API.
Client.VolumeLimitExceeded: The limit on the number of EBS volumes or total storage was exceeded. Decrease usage or request an increase in your account limits.
Tags (list) --
Any tags assigned to the image.
(dict) --
Describes a tag.
Key (string) --
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maximum of 127 Unicode characters. May not begin with aws:.
Value (string) --
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maximum of 256 Unicode characters.
VirtualizationType (string) --
The type of virtualization of the AMI.
BootMode (string) --
The boot mode of the image. For more information, see Boot modes in the Amazon EC2 User Guide.
TpmSupport (string) --
If the image is configured for NitroTPM support, the value is v2.0. For more information, see NitroTPM in the Amazon EC2 User Guide.
DeprecationTime (string) --
The date and time to deprecate the AMI, in UTC, in the following format: YYYY-MM-DD*T*HH:MM:*SS*Z. If you specified a value for seconds, Amazon EC2 rounds the seconds to the nearest minute.
ImdsSupport (string) --
If v2.0, it indicates that IMDSv2 is specified in the AMI. Instances launched from this AMI will have HttpTokens automatically set to required so that, by default, the instance requires that IMDSv2 is used when requesting instance metadata. In addition, HttpPutResponseHopLimit is set to 2. For more information, see Configure the AMI in the Amazon EC2 User Guide.
SourceInstanceId (string) --
The ID of the instance that the AMI was created from if the AMI was created using CreateImage. This field only appears if the AMI was created using CreateImage.
DeregistrationProtection (string) --
Indicates whether deregistration protection is enabled for the AMI.
LastLaunchedTime (string) --
The date and time, in ISO 8601 date-time format, when the AMI was last used to launch an EC2 instance. When the AMI is used to launch an instance, there is a 24-hour delay before that usage is reported.
ImageAllowed (boolean) --
If true, the AMI satisfies the criteria for Allowed AMIs and can be discovered and used in the account. If false and Allowed AMIs is set to enabled, the AMI can't be discovered or used in the account. If false and Allowed AMIs is set to audit-mode, the AMI can be discovered and used in the account.
For more information, see Control the discovery and use of AMIs in Amazon EC2 with Allowed AMIs in Amazon EC2 User Guide.
SourceImageId (string) --
The ID of the source AMI from which the AMI was created.
The ID only appears if the AMI was created using CreateImage, CopyImage, or CreateRestoreImageTask. The ID does not appear if the AMI was created using any other API. For some older AMIs, the ID might not be available. For more information, see Identify the source AMI used to create a new AMI in the Amazon EC2 User Guide.
SourceImageRegion (string) --
The Region of the source AMI.
The Region only appears if the AMI was created using CreateImage, CopyImage, or CreateRestoreImageTask. The Region does not appear if the AMI was created using any other API. For some older AMIs, the Region might not be available. For more information, see Identify the source AMI used to create a new AMI in the Amazon EC2 User Guide.
ImageId (string) --
The ID of the AMI.
ImageLocation (string) --
The location of the AMI.
State (string) --
The current state of the AMI. If the state is available, the image is successfully registered and can be used to launch an instance.
OwnerId (string) --
The ID of the Amazon Web Services account that owns the image.
CreationDate (string) --
The date and time the image was created.
Public (boolean) --
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.
ProductCodes (list) --
Any product codes associated with the AMI.
(dict) --
Describes a product code.
ProductCodeId (string) --
The product code.
ProductCodeType (string) --
The type of product code.
Architecture (string) --
The architecture of the image.
ImageType (string) --
The type of image.
KernelId (string) --
The kernel associated with the image, if any. Only applicable for machine images.
RamdiskId (string) --
The RAM disk associated with the image, if any. Only applicable for machine images.
Platform (string) --
This value is set to windows for Windows AMIs; otherwise, it is blank.
{'LaunchTemplateVersions': {'LaunchTemplateData': {'BlockDeviceMappings': {'Ebs': {'VolumeInitializationRate': 'integer'}}}}}
{'SpotFleetRequestConfigs': {'SpotFleetRequestConfig': {'LaunchSpecifications': {'BlockDeviceMappings': {'Ebs': {'VolumeInitializationRate': 'integer'}}}}}}
{'SpotInstanceRequests': {'LaunchSpecification': {'BlockDeviceMappings': {'Ebs': {'VolumeInitializationRate': 'integer'}}}}}
{'Volumes': {'VolumeInitializationRate': 'integer'}}
Describes the specified EBS volumes or all of your EBS volumes.
If you are describing a long list of volumes, we recommend that you paginate the output to make the list more manageable. For more information, see Pagination.
For more information about EBS volumes, see Amazon EBS volumes in the Amazon EBS User Guide.
See also: AWS API Documentation
Request Syntax
client.describe_volumes(
VolumeIds=[
'string',
],
DryRun=True|False,
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
],
NextToken='string',
MaxResults=123
)
list
The volume IDs. If not specified, then all volumes are included in the response.
(string) --
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.
list
The filters.
attachment.attach-time - The time stamp when the attachment initiated.
attachment.delete-on-termination - Whether the volume is deleted on instance termination.
attachment.device - The device name specified in the block device mapping (for example, /dev/sda1).
attachment.instance-id - The ID of the instance the volume is attached to.
attachment.status - The attachment state ( attaching | attached | detaching).
availability-zone - The Availability Zone in which the volume was created.
create-time - The time stamp when the volume was created.
encrypted - Indicates whether the volume is encrypted ( true | false)
fast-restored - Indicates whether the volume was created from a snapshot that is enabled for fast snapshot restore ( true | false).
multi-attach-enabled - Indicates whether the volume is enabled for Multi-Attach ( true | false)
operator.managed - A Boolean that indicates whether this is a managed volume.
operator.principal - The principal that manages the volume. Only valid for managed volumes, where managed is true.
size - The size of the volume, in GiB.
snapshot-id - The snapshot from which the volume was created.
status - The state of the volume ( creating | available | in-use | deleting | deleted | error).
tag:<key> - The key/value combination of a tag assigned to the resource. Use the tag key in the filter name and the tag value as the filter value. For example, to find all resources that have a tag with the key Owner and the value TeamA, specify tag:Owner for the filter name and TeamA for the filter value.
tag-key - The key of a tag assigned to the resource. Use this filter to find all resources assigned a tag with a specific key, regardless of the tag value.
volume-id - The volume ID.
volume-type - The Amazon EBS volume type ( gp2 | gp3 | io1 | io2 | st1 | sc1``| ``standard)
(dict) --
A filter name and value pair that is used to return a more specific list of results from a describe operation. Filters can be used to match a set of resources by specific criteria, such as tags, attributes, or IDs.
If you specify multiple filters, the filters are joined with an AND, and the request returns only results that match all of the specified filters.
For more information, see List and filter using the CLI and API in the Amazon EC2 User Guide.
Name (string) --
The name of the filter. Filter names are case-sensitive.
Values (list) --
The filter values. Filter values are case-sensitive. If you specify multiple values for a filter, the values are joined with an OR, and the request returns all results that match any of the specified values.
(string) --
string
The token returned from a previous paginated request. Pagination continues from the end of the items returned by the previous request.
integer
The maximum number of items to return for this request. To get the next page of items, make another request with the token returned in the output. For more information, see Pagination.
dict
Response Syntax
{
'NextToken': 'string',
'Volumes': [
{
'OutpostArn': 'string',
'Iops': 123,
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
],
'VolumeType': 'standard'|'io1'|'io2'|'gp2'|'sc1'|'st1'|'gp3',
'FastRestored': True|False,
'MultiAttachEnabled': True|False,
'Throughput': 123,
'SseType': 'sse-ebs'|'sse-kms'|'none',
'Operator': {
'Managed': True|False,
'Principal': 'string'
},
'VolumeInitializationRate': 123,
'VolumeId': 'string',
'Size': 123,
'SnapshotId': 'string',
'AvailabilityZone': 'string',
'State': 'creating'|'available'|'in-use'|'deleting'|'deleted'|'error',
'CreateTime': datetime(2015, 1, 1),
'Attachments': [
{
'DeleteOnTermination': True|False,
'AssociatedResource': 'string',
'InstanceOwningService': 'string',
'VolumeId': 'string',
'InstanceId': 'string',
'Device': 'string',
'State': 'attaching'|'attached'|'detaching'|'detached'|'busy',
'AttachTime': datetime(2015, 1, 1)
},
],
'Encrypted': True|False,
'KmsKeyId': 'string'
},
]
}
Response Structure
(dict) --
NextToken (string) --
The token to include in another request to get the next page of items. This value is null when there are no more items to return.
Volumes (list) --
Information about the volumes.
(dict) --
Describes a volume.
OutpostArn (string) --
The Amazon Resource Name (ARN) of the Outpost.
Iops (integer) --
The number of I/O operations per second (IOPS). For gp3, io1, and io2 volumes, this represents the number of IOPS that are provisioned for the volume. For gp2 volumes, this represents the baseline performance of the volume and the rate at which the volume accumulates I/O credits for bursting.
Tags (list) --
Any tags assigned to the volume.
(dict) --
Describes a tag.
Key (string) --
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maximum of 127 Unicode characters. May not begin with aws:.
Value (string) --
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maximum of 256 Unicode characters.
VolumeType (string) --
The volume type.
FastRestored (boolean) --
Indicates whether the volume was created using fast snapshot restore.
MultiAttachEnabled (boolean) --
Indicates whether Amazon EBS Multi-Attach is enabled.
Throughput (integer) --
The throughput that the volume supports, in MiB/s.
SseType (string) --
Reserved for future use.
Operator (dict) --
The service provider that manages the volume.
Managed (boolean) --
If true, the resource is managed by a service provider.
Principal (string) --
If managed is true, then the principal is returned. The principal is the service provider that manages the resource.
VolumeInitializationRate (integer) --
The Amazon EBS Provisioned Rate for Volume Initialization (volume initialization rate) specified for the volume during creation, in MiB/s. If no volume initialization rate was specified, the value is null.
VolumeId (string) --
The ID of the volume.
Size (integer) --
The size of the volume, in GiBs.
SnapshotId (string) --
The snapshot from which the volume was created, if applicable.
AvailabilityZone (string) --
The Availability Zone for the volume.
State (string) --
The volume state.
CreateTime (datetime) --
The time stamp when volume creation was initiated.
Attachments (list) --
Information about the volume attachments.
(dict) --
Describes volume attachment details.
DeleteOnTermination (boolean) --
Indicates whether the EBS volume is deleted on instance termination.
AssociatedResource (string) --
The ARN of the Amazon ECS or Fargate task to which the volume is attached.
InstanceOwningService (string) --
The service principal of Amazon Web Services service that owns the underlying instance to which the volume is attached.
This parameter is returned only for volumes that are attached to Fargate tasks.
VolumeId (string) --
The ID of the volume.
InstanceId (string) --
The ID of the instance.
If the volume is attached to a Fargate task, this parameter returns null.
Device (string) --
The device name.
If the volume is attached to a Fargate task, this parameter returns null.
State (string) --
The attachment state of the volume.
AttachTime (datetime) --
The time stamp when the attachment initiated.
Encrypted (boolean) --
Indicates whether the volume is encrypted.
KmsKeyId (string) --
The Amazon Resource Name (ARN) of the KMS key that was used to protect the volume encryption key for the volume.
{'LaunchTemplateData': {'BlockDeviceMappings': {'Ebs': {'VolumeInitializationRate': 'integer'}}}}
{'BlockDeviceMappings': {'Ebs': {'VolumeInitializationRate': 'integer'}}}
Registers an AMI. When you're creating an instance-store backed AMI, registering the AMI is the final step in the creation process. For more information about creating AMIs, see Create an AMI from a snapshot and Create an instance-store backed AMI in the Amazon EC2 User Guide.
If needed, you can deregister an AMI at any time. Any modifications you make to an AMI backed by an instance store volume invalidates its registration. If you make changes to an image, deregister the previous image and register the new image.
Register a snapshot of a root device volume
You can use RegisterImage to create an Amazon EBS-backed Linux AMI from a snapshot of a root device volume. You specify the snapshot using a block device mapping. You can't set the encryption state of the volume using the block device mapping. If the snapshot is encrypted, or encryption by default is enabled, the root volume of an instance launched from the AMI is encrypted.
For more information, see Create an AMI from a snapshot and Use encryption with Amazon EBS-backed AMIs in the Amazon EC2 User Guide.
Amazon Web Services Marketplace product codes
If any snapshots have Amazon Web Services Marketplace product codes, they are copied to the new AMI.
In most cases, AMIs for Windows, RedHat, SUSE, and SQL Server require correct licensing information to be present on the AMI. For more information, see Understand AMI billing information in the Amazon EC2 User Guide. When creating an AMI from a snapshot, the RegisterImage operation derives the correct billing information from the snapshot's metadata, but this requires the appropriate metadata to be present. To verify if the correct billing information was applied, check the PlatformDetails field on the new AMI. If the field is empty or doesn't match the expected operating system code (for example, Windows, RedHat, SUSE, or SQL), the AMI creation was unsuccessful, and you should discard the AMI and instead create the AMI from an instance using CreateImage. For more information, see Create an AMI from an instance in the Amazon EC2 User Guide.
If you purchase a Reserved Instance to apply to an On-Demand Instance that was launched from an AMI with a billing product code, make sure that the Reserved Instance has the matching billing product code. If you purchase a Reserved Instance without the matching billing product code, the Reserved Instance will not be applied to the On-Demand Instance. For information about how to obtain the platform details and billing information of an AMI, see Understand AMI billing information in the Amazon EC2 User Guide.
See also: AWS API Documentation
Request Syntax
client.register_image(
ImageLocation='string',
BillingProducts=[
'string',
],
BootMode='legacy-bios'|'uefi'|'uefi-preferred',
TpmSupport='v2.0',
UefiData='string',
ImdsSupport='v2.0',
TagSpecifications=[
{
'ResourceType': 'capacity-reservation'|'client-vpn-endpoint'|'customer-gateway'|'carrier-gateway'|'coip-pool'|'declarative-policies-report'|'dedicated-host'|'dhcp-options'|'egress-only-internet-gateway'|'elastic-ip'|'elastic-gpu'|'export-image-task'|'export-instance-task'|'fleet'|'fpga-image'|'host-reservation'|'image'|'import-image-task'|'import-snapshot-task'|'instance'|'instance-event-window'|'internet-gateway'|'ipam'|'ipam-pool'|'ipam-scope'|'ipv4pool-ec2'|'ipv6pool-ec2'|'key-pair'|'launch-template'|'local-gateway'|'local-gateway-route-table'|'local-gateway-virtual-interface'|'local-gateway-virtual-interface-group'|'local-gateway-route-table-vpc-association'|'local-gateway-route-table-virtual-interface-group-association'|'natgateway'|'network-acl'|'network-interface'|'network-insights-analysis'|'network-insights-path'|'network-insights-access-scope'|'network-insights-access-scope-analysis'|'outpost-lag'|'placement-group'|'prefix-list'|'replace-root-volume-task'|'reserved-instances'|'route-table'|'security-group'|'security-group-rule'|'service-link-virtual-interface'|'snapshot'|'spot-fleet-request'|'spot-instances-request'|'subnet'|'subnet-cidr-reservation'|'traffic-mirror-filter'|'traffic-mirror-session'|'traffic-mirror-target'|'transit-gateway'|'transit-gateway-attachment'|'transit-gateway-connect-peer'|'transit-gateway-multicast-domain'|'transit-gateway-policy-table'|'transit-gateway-route-table'|'transit-gateway-route-table-announcement'|'volume'|'vpc'|'vpc-endpoint'|'vpc-endpoint-connection'|'vpc-endpoint-service'|'vpc-endpoint-service-permission'|'vpc-peering-connection'|'vpn-connection'|'vpn-gateway'|'vpc-flow-log'|'capacity-reservation-fleet'|'traffic-mirror-filter-rule'|'vpc-endpoint-connection-device-type'|'verified-access-instance'|'verified-access-group'|'verified-access-endpoint'|'verified-access-policy'|'verified-access-trust-provider'|'vpn-connection-device-type'|'vpc-block-public-access-exclusion'|'route-server'|'route-server-endpoint'|'route-server-peer'|'ipam-resource-discovery'|'ipam-resource-discovery-association'|'instance-connect-endpoint'|'verified-access-endpoint-target'|'ipam-external-resource-verification-token',
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
]
},
],
DryRun=True|False,
Name='string',
Description='string',
Architecture='i386'|'x86_64'|'arm64'|'x86_64_mac'|'arm64_mac',
KernelId='string',
RamdiskId='string',
RootDeviceName='string',
BlockDeviceMappings=[
{
'Ebs': {
'DeleteOnTermination': True|False,
'Iops': 123,
'SnapshotId': 'string',
'VolumeSize': 123,
'VolumeType': 'standard'|'io1'|'io2'|'gp2'|'sc1'|'st1'|'gp3',
'KmsKeyId': 'string',
'Throughput': 123,
'OutpostArn': 'string',
'Encrypted': True|False,
'VolumeInitializationRate': 123
},
'NoDevice': 'string',
'DeviceName': 'string',
'VirtualName': 'string'
},
],
VirtualizationType='string',
SriovNetSupport='string',
EnaSupport=True|False
)
string
The full path to your AMI manifest in Amazon S3 storage. The specified bucket must have the aws-exec-read canned access control list (ACL) to ensure that it can be accessed by Amazon EC2. For more information, see Canned ACLs in the Amazon S3 Service Developer Guide.
list
The billing product codes. Your account must be authorized to specify billing product codes.
If your account is not authorized to specify billing product codes, you can publish AMIs that include billable software and list them on the Amazon Web Services Marketplace. You must first register as a seller on the Amazon Web Services Marketplace. For more information, see Getting started as a seller and AMI-based products in the Amazon Web Services Marketplace Seller Guide.
(string) --
string
The boot mode of the AMI. A value of uefi-preferred indicates that the AMI supports both UEFI and Legacy BIOS.
For more information, see Boot modes in the Amazon EC2 User Guide.
string
Set to v2.0 to enable Trusted Platform Module (TPM) support. For more information, see NitroTPM in the Amazon EC2 User Guide.
string
Base64 representation of the non-volatile UEFI variable store. To retrieve the UEFI data, use the GetInstanceUefiData command. You can inspect and modify the UEFI data by using the python-uefivars tool on GitHub. For more information, see UEFI Secure Boot in the Amazon EC2 User Guide.
string
Set to v2.0 to indicate that IMDSv2 is specified in the AMI. Instances launched from this AMI will have HttpTokens automatically set to required so that, by default, the instance requires that IMDSv2 is used when requesting instance metadata. In addition, HttpPutResponseHopLimit is set to 2. For more information, see Configure the AMI in the Amazon EC2 User Guide.
list
The tags to apply to the AMI.
To tag the AMI, the value for ResourceType must be image. If you specify another value for ResourceType, the request fails.
To tag an AMI after it has been registered, see CreateTags.
(dict) --
The tags to apply to a resource when the resource is being created. When you specify a tag, you must specify the resource type to tag, otherwise the request will fail.
ResourceType (string) --
The type of resource to tag on creation.
Tags (list) --
The tags to apply to the resource.
(dict) --
Describes a tag.
Key (string) --
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maximum of 127 Unicode characters. May not begin with aws:.
Value (string) --
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maximum of 256 Unicode characters.
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.
string
[REQUIRED]
A name for your AMI.
Constraints: 3-128 alphanumeric characters, parentheses (()), square brackets ([]), spaces ( ), periods (.), slashes (/), dashes (-), single quotes ('), at-signs (@), or underscores(_)
string
A description for your AMI.
string
The architecture of the AMI.
Default: For Amazon EBS-backed AMIs, i386. For instance store-backed AMIs, the architecture specified in the manifest file.
string
The ID of the kernel.
string
The ID of the RAM disk.
string
The device name of the root device volume (for example, /dev/sda1).
list
The block device mapping entries.
If you specify an Amazon EBS volume using the ID of an Amazon EBS snapshot, you can't specify the encryption state of the volume.
If you create an AMI on an Outpost, then all backing snapshots must be on the same Outpost or in the Region of that Outpost. AMIs on an Outpost that include local snapshots can be used to launch instances on the same Outpost only. For more information, Amazon EBS local snapshots on Outposts in the Amazon EBS User Guide.
(dict) --
Describes a block device mapping, which defines the EBS volumes and instance store volumes to attach to an instance at launch.
Ebs (dict) --
Parameters used to automatically set up EBS volumes when the instance is launched.
DeleteOnTermination (boolean) --
Indicates whether the EBS volume is deleted on instance termination. For more information, see Preserving Amazon EBS volumes on instance termination in the Amazon EC2 User Guide.
Iops (integer) --
The number of I/O operations per second (IOPS). For gp3, io1, and io2 volumes, this represents the number of IOPS that are provisioned for the volume. For gp2 volumes, this represents the baseline performance of the volume and the rate at which the volume accumulates I/O credits for bursting.
The following are the supported values for each volume type:
gp3: 3,000 - 16,000 IOPS
io1: 100 - 64,000 IOPS
io2: 100 - 256,000 IOPS
For io2 volumes, you can achieve up to 256,000 IOPS on instances built on the Nitro System. On other instances, you can achieve performance up to 32,000 IOPS.
This parameter is required for io1 and io2 volumes. The default for gp3 volumes is 3,000 IOPS.
SnapshotId (string) --
The ID of the snapshot.
VolumeSize (integer) --
The size of the volume, in GiBs. You must specify either a snapshot ID or a volume size. If you specify a snapshot, the default is the snapshot size. You can specify a volume size that is equal to or larger than the snapshot size.
The following are the supported sizes for each volume type:
gp2 and gp3: 1 - 16,384 GiB
io1: 4 - 16,384 GiB
io2: 4 - 65,536 GiB
st1 and sc1: 125 - 16,384 GiB
standard: 1 - 1024 GiB
VolumeType (string) --
The volume type. For more information, see Amazon EBS volume types in the Amazon EBS User Guide.
KmsKeyId (string) --
Identifier (key ID, key alias, key ARN, or alias ARN) of the customer managed KMS key to use for EBS encryption.
This parameter is only supported on BlockDeviceMapping objects called by RunInstances, RequestSpotFleet, and RequestSpotInstances.
Throughput (integer) --
The throughput that the volume supports, in MiB/s.
This parameter is valid only for gp3 volumes.
Valid Range: Minimum value of 125. Maximum value of 1000.
OutpostArn (string) --
The ARN of the Outpost on which the snapshot is stored.
This parameter is not supported when using CreateImage.
Encrypted (boolean) --
Indicates whether the encryption state of an EBS volume is changed while being restored from a backing snapshot. The effect of setting the encryption state to true depends on the volume origin (new or from a snapshot), starting encryption state, ownership, and whether encryption by default is enabled. For more information, see Amazon EBS encryption in the Amazon EBS User Guide.
In no case can you remove encryption from an encrypted volume.
Encrypted volumes can only be attached to instances that support Amazon EBS encryption. For more information, see Supported instance types.
This parameter is not returned by DescribeImageAttribute.
For CreateImage and RegisterImage, whether you can include this parameter, and the allowed values differ depending on the type of block device mapping you are creating.
If you are creating a block device mapping for a new (empty) volume, you can include this parameter, and specify either true for an encrypted volume, or false for an unencrypted volume. If you omit this parameter, it defaults to false (unencrypted).
If you are creating a block device mapping from an existing encrypted or unencrypted snapshot, you must omit this parameter. If you include this parameter, the request will fail, regardless of the value that you specify.
If you are creating a block device mapping from an existing unencrypted volume, you can include this parameter, but you must specify false. If you specify true, the request will fail. In this case, we recommend that you omit the parameter.
If you are creating a block device mapping from an existing encrypted volume, you can include this parameter, and specify either true or false. However, if you specify false, the parameter is ignored and the block device mapping is always encrypted. In this case, we recommend that you omit the parameter.
VolumeInitializationRate (integer) --
Specifies the Amazon EBS Provisioned Rate for Volume Initialization (volume initialization rate), in MiB/s, at which to download the snapshot blocks from Amazon S3 to the volume. This is also known as volume initialization. Specifying a volume initialization rate ensures that the volume is initialized at a predictable and consistent rate after creation.
This parameter is supported only for volumes created from snapshots. Omit this parameter if:
You want to create the volume using fast snapshot restore. You must specify a snapshot that is enabled for fast snapshot restore. In this case, the volume is fully initialized at creation.
You want to create a volume that is initialized at the default rate.
For more information, see Initialize Amazon EBS volumes in the Amazon EC2 User Guide.
This parameter is not supported when using CreateImage.
Valid range: 100 - 300 MiB/s
NoDevice (string) --
To omit the device from the block device mapping, specify an empty string. When this property is specified, the device is removed from the block device mapping regardless of the assigned value.
DeviceName (string) --
The device name (for example, /dev/sdh or xvdh).
VirtualName (string) --
The virtual device name ( ephemeral``N). Instance store volumes are numbered starting from 0. An instance type with 2 available instance store volumes can specify mappings for ``ephemeral0 and ephemeral1. The number of available instance store volumes depends on the instance type. After you connect to the instance, you must mount the volume.
NVMe instance store volumes are automatically enumerated and assigned a device name. Including them in your block device mapping has no effect.
Constraints: For M3 instances, you must specify instance store volumes in the block device mapping for the instance. When you launch an M3 instance, we ignore any instance store volumes specified in the block device mapping for the AMI.
string
The type of virtualization ( hvm | paravirtual).
Default: paravirtual
string
Set to simple to enable enhanced networking with the Intel 82599 Virtual Function interface for the AMI and any instances that you launch from the AMI.
There is no way to disable sriovNetSupport at this time.
This option is supported only for HVM AMIs. Specifying this option with a PV AMI can make instances launched from the AMI unreachable.
boolean
Set to true to enable enhanced networking with ENA for the AMI and any instances that you launch from the AMI.
This option is supported only for HVM AMIs. Specifying this option with a PV AMI can make instances launched from the AMI unreachable.
dict
Response Syntax
{
'ImageId': 'string'
}
Response Structure
(dict) --
Contains the output of RegisterImage.
ImageId (string) --
The ID of the newly registered AMI.
{'SpotFleetRequestConfig': {'LaunchSpecifications': {'BlockDeviceMappings': {'Ebs': {'VolumeInitializationRate': 'integer'}}}}}
{'LaunchSpecification': {'BlockDeviceMappings': {'Ebs': {'VolumeInitializationRate': 'integer'}}}}
Response {'SpotInstanceRequests': {'LaunchSpecification': {'BlockDeviceMappings': {'Ebs': {'VolumeInitializationRate': 'integer'}}}}}
{'BlockDeviceMappings': {'Ebs': {'VolumeInitializationRate': 'integer'}}}