Skip to content

Resource: awsAmi

The AMI resource allows the creation and management of a completely-custom Amazon Machine Image (AMI).

If you just want to duplicate an existing AMI, possibly copying it to another region, it's better to use awsAmiCopy instead.

If you just want to share an existing AMI with another AWS account, it's better to use awsAmiLaunchPermission instead.

Example Usage

/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as aws from "./.gen/providers/aws";
new aws.ami.Ami(this, "example", {
  ebsBlockDevice: [
    {
      deviceName: "/dev/xvda",
      snapshotId: "snap-xxxxxxxx",
      volumeSize: 8,
    },
  ],
  imdsSupport: "v2.0",
  name: "terraform-example",
  rootDeviceName: "/dev/xvda",
  virtualizationType: "hvm",
});

Argument Reference

The following arguments are supported:

  • name - (Required) Region-unique name for the AMI.
  • bootMode - (Optional) Boot mode of the AMI. For more information, see Boot modes in the Amazon Elastic Compute Cloud User Guide.
  • deprecationTime - (Optional) Date and time to deprecate the AMI. If you specified a value for seconds, Amazon EC2 rounds the seconds to the nearest minute. Valid values: RFC3339 time string (yyyyMmDdthh:mm:ssz)
  • description - (Optional) Longer, human-readable description for the AMI.
  • enaSupport - (Optional) Whether enhanced networking with ENA is enabled. Defaults to false.
  • rootDeviceName - (Optional) Name of the root device (for example, /dev/sda1, or /dev/xvda).
  • virtualizationType - (Optional) Keyword to choose what virtualization mode created instances will use. Can be either "paravirtual" (the default) or "hvm". The choice of virtualization type changes the set of further arguments that are required, as described below.
  • architecture - (Optional) Machine architecture for created instances. Defaults to "x86_64".
  • ebsBlockDevice - (Optional) Nested block describing an EBS block device that should be attached to created instances. The structure of this block is described below.
  • ephemeralBlockDevice - (Optional) Nested block describing an ephemeral block device that should be attached to created instances. The structure of this block is described below.
  • tags - (Optional) Map of tags to assign to the resource. If configured with a provider defaultTags configuration block present, tags with matching keys will overwrite those defined at the provider-level.
  • tpmSupport - (Optional) If the image is configured for NitroTPM support, the value is v20. For more information, see NitroTPM in the Amazon Elastic Compute Cloud User Guide.
  • imdsSupport - (Optional) If EC2 instances started from this image should require the use of the Instance Metadata Service V2 (IMDSv2), set this argument to v20. For more information, see Configure instance metadata options for new instances.

When virtualizationType is "paravirtual" the following additional arguments apply:

  • imageLocation - (Required) Path to an S3 object containing an image manifest, e.g., created by the ec2UploadBundle command in the EC2 command line tools.
  • kernelId - (Required) ID of the kernel image (AKI) that will be used as the paravirtual kernel in created instances.
  • ramdiskId - (Optional) ID of an initrd image (ARI) that will be used when booting the created instances.

When virtualizationType is "hvm" the following additional arguments apply:

  • sriovNetSupport - (Optional) When set to "simple" (the default), enables enhanced networking for created instances. No other value is supported at this time.

Nested ebsBlockDevice blocks have the following structure:

  • deviceName - (Required) Path at which the device is exposed to created instances.
  • deleteOnTermination - (Optional) Boolean controlling whether the EBS volumes created to support each created instance will be deleted once that instance is terminated.
  • encrypted - (Optional) Boolean controlling whether the created EBS volumes will be encrypted. Can't be used with snapshotId.
  • iops - (Required only when volumeType is io1 or io2) Number of I/O operations per second the created volumes will support.
  • snapshotId - (Optional) ID of an EBS snapshot that will be used to initialize the created EBS volumes. If set, the volumeSize attribute must be at least as large as the referenced snapshot.
  • throughput - (Optional) Throughput that the EBS volume supports, in MiB/s. Only valid for volumeType of gp3.
  • volumeSize - (Required unless snapshotId is set) Size of created volumes in GiB. If snapshotId is set and volumeSize is omitted then the volume will have the same size as the selected snapshot.
  • volumeType - (Optional) Type of EBS volume to create. Can be standard, gp2, gp3, io1, io2, sc1 or st1 (Default: standard).
  • outpostArn - (Optional) ARN of the Outpost on which the snapshot is stored.

\~> Note: You can specify encrypted or snapshotId but not both.

Nested ephemeralBlockDevice blocks have the following structure:

  • deviceName - (Required) Path at which the device is exposed to created instances.
  • virtualName - (Required) Name for the ephemeral device, of the form "ephemeralN" where N is a volume number starting from zero.

Attributes Reference

In addition to all arguments above, the following attributes are exported:

  • arn - ARN of the AMI.
  • id - ID of the created AMI.
  • ownerId - AWS account ID of the image owner.
  • rootSnapshotId - Snapshot ID for the root volume (for EBS-backed AMIs)
  • usageOperation - Operation of the Amazon EC2 instance and the billing code that is associated with the AMI.
  • platformDetails - Platform details associated with the billing code of the AMI.
  • imageOwnerAlias - AWS account alias (for example, amazon, self) or the AWS account ID of the AMI owner.
  • imageType - Type of image.
  • hypervisor - Hypervisor type of the image.
  • ownerId - AWS account ID of the image owner.
  • platform - This value is set to windows for Windows AMIs; otherwise, it is blank.
  • public - Whether the image has public launch permissions.
  • tagsAll - Map of tags assigned to the resource, including those inherited from the provider defaultTags configuration block.

Timeouts

Configuration options:

  • create - (Default 40M)
  • update - (Default 40M)
  • delete - (Default 90M)

Import

awsAmi can be imported using the ID of the AMI, e.g.,

$ terraform import aws_ami.example ami-12345678