aws-cloudformation / aws-cloudformation/cloudformation-coverage-roadmap

`AWS::EC2::Snapshot` + `AWS::EC2::Image` - New Resource - Support Snapshot + Image Import and AMI Management

Open
#2,175 1 comment 0 reactions 0 assignees View on GitHub
other
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.