aws-cloudformation / aws-cloudformation/cloudformation-coverage-roadmap
`AWS::EC2::Snapshot` + `AWS::EC2::Image` - New Resource - Support Snapshot + Image Import and AMI Management
- Dominant language
- No language data
- Stars
- 1.1k
- Forks
- 62
- PR merge metrics
- No merged PRs in 30d
Description
## Feature Request
Natively support creation of AMIs through [snapshot import](https://docs.aws.amazon.com/vm-import/latest/userguide/vmimport-import-snapshot.html) + [image import](https://docs.aws.amazon.com/vm-import/latest/userguide/vmimport-image-import.html) and managing them through CloudFormation.
This should be owned by the EC2 team that owns the [`ec2:ImportSnapshot`](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ImportSnapshot.html) + [`ec2:RegisterImage`](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_RegisterImage.html) (for snapshot import) and [`ec2:ImportImage`](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ImportImage.html) APIs.
These don't belong under the existing [`AWS::ImageBuilder::Image`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-imagebuilder-image.html) resource ([feature request](https://github.com/aws/ec2-image-builder-roadmap/issues/103)) because:
1. The snapshot + image import APIs are [not owned by EC2 Image Builder](https://github.com/aws/ec2-image-builder-roadmap/issues/103#issuecomment-2439724036).
2. Image Builder comes up late in AWS region build which means `AWS::ImageBuilder::Image` will be available late in region build.
* AMIs are a foundational resource, so `AWS::EC2::Snapshot` and `AWS::EC2::Image` must be usable early.
Snapshot import should be prioritized over image import because the latter has significantly more limitations (only supports i386 and x86-64 images, doesn't support the `uefi-preferred` boot mode, requires Linux OSes to follow the filesystem hierarchy standard).
Users should be able to have a CloudFormation template like this for `ec2:ImportSnapshot` + `ec2:RegisterImage`:
```yaml
Resources:
ImportedSnapshot:
Type: AWS::EC2::Snapshot
Properties:
# Snapshot source (i.e. how it's created).
#
# Can use ec2:Import/Copy/CreateSnapshot. Mutually exclusive.
Source:
# ec2:ImportSnapshot request parameters.
Import:
DiskContainer:
UserBucket:
S3Bucket: cdk-{qualifier}-assets-${AWS::AccountId}-${AWS::Region}
S3Key: {content hash}-vm-image-aarch64.raw
# ec2:ModifySnapshotAttribute request parameters.
Attributes:
CreateVolumePermissions:
- Group: all
# ec2:Create/DeleteTags request parameters.
Tags:
- key: value
ImportedAMI:
Type: AWS::EC2::Image
Properties:
# Image source (i.e. how it's created).
#
# Can use ec2:Register/Import/Copy/CreateImage. Mutually exclusive.
Source:
# ec2:RegisterImage request parameters.
Register:
Architecture: arm64
BootMode: uefi
BlockDeviceMappings:
- Ebs:
SnapshotId: !Ref ImportedSnapshot
# ec2:ModifyImageAttribute request parameters.
Attributes:
Description: My imported image.
ImdsSupport: v2.0
LaunchPermissions:
- Group: all
- OrganizationId: o-000000000000
# ec2:Create/DeleteTags request parameters.
Tags:
- key: value
```
Users should be able to have a CloudFormation template like this for `ec2:ImportImage`:
```yaml
Resources:
ImportedAMI:
Type: AWS::EC2::Image
Properties:
# Image source (i.e. how it's created).
#
# Can use ec2:Register/Import/Copy/CreateImage. Mutually exclusive.
Source:
# ec2:ImportImage request parameters.
Import:
Architecture: arm64
BootMode: uefi
ImageDiskContainers:
- UserBucket:
S3Bucket: cdk-{qualifier}-assets-${AWS::AccountId}-${AWS::Region}
S3Key: {content hash}-vm-image-aarch64.raw
# ec2:ModifyImageAttribute request parameters.
Attributes:
Description: My imported image.
ImdsSupport: v2.0
LaunchPermissions:
- Group: all
- OrganizationId: o-000000000000
# ec2:Create/DeleteTags request parameters.
Tags:
- key: value
```
The resources should support the following return values:
* `AWS::EC2::Snapshot`
* `Ref`
* Returns the snapshot ID (e.g. `snap-000000000000`). For use in most places (e.g. block device mappings).
* `GetAtt`
* `Arn`
* Returns the snapshot ARN (e.g. `arn:aws:ec2:us-west-2::snapshot/snap-000000000000`). For [use in IAM policies](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonec2.html#amazonec2-snapshot).
* `ImportTaskId`
* Returns the `ec2:ImportSnapshot` import task ID or `null`.
* `AWS::EC2::Image`
* `Ref`
* Returns the AMI ID (e.g. `ami-000000000000`). For use in most places (e.g. launch templates).
* `GetAtt`
* `Arn`
* Returns the AMI ARN (e.g. `arn:aws:ec2:us-west-2::image/ami-000000000000`). For [use in IAM policies](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonec2.html#amazonec2-image).
* `ImportTaskId`
* Returns the `ec2:ImportImage` import task ID or `null`.
Deleting the resource should delete:
* The EBS snapshot.
* The AMI.
## Use Cases
Let users declaratively import and manage EC2 AMIs with CloudFormation. For example:
- Creating NixOS AMIs from NixOS raw disk images produced by the [NixOS systemd-repart helper](https://nixos.org/manual/nixos/stable#sec-image-repart).
- Useful for the [AWS official NitroTPM examples for attestable NixOS AMIs](https://github.com/aws/nitrotpm-attestation-samples/tree/main/nix) (cc: @agraf @iorlov-dev @mariusknaust).
- Creating Linux AMIs from raw disk images produced by [mkosi](https://github.com/systemd/mkosi).
- Creating macOS AMIs from raw disk images produced by `diskutil` + `hdiutil`.
- Creating Windows AMIs from raw disk images produced by QEMU and converted with [qemu-img](https://www.mankier.com/1/qemu-img).
This helps support the AMI baking and immutable infrastructure pattern.
See https://github.com/aws-cloudformation/cloudformation-coverage-roadmap/issues/2119 for more details.
With this, users will be able to import an AMI and then:
1. Reference it in an [`AWS::ImageBuilder::ImageRecipe`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-imagebuilder-imagerecipe.html) for custom image builds and cross-account + cross-region image distribution pipelines.
2. Reference it in an [`AWS::EC2::LaunchTemplate`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ec2-launchtemplate.html) for use with an [`AWS::EC2::Instance`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ec2-instance.html) or [`AWS::AutoScaling::AutoScalingGroup`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-autoscaling-autoscalinggroup.html).
Contributor guide
Research direction
Start with the referenced ec2:ImportSnapshot, ec2:RegisterImage, and ec2:ImportImage API documentation, then compare the requested behavior with the existing AWS::ImageBuilder::Image resource. Review the example CloudFormation templates and required Ref/GetAtt values. Done means declarative snapshot and AMI import and management, including attributes, tags, return values, and deletion behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- aws
- Domain
- cloud, infrastructure
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 30/100