AMI

Type: rvn-aws-ami · Latest version: 0.1.0

Readme

Creates the EC2 Image Builder infrastructure an AMI is baked on, and releases a new AMI with every deploy.

Overview

Use this module to turn a manual image build into a repeatable release. Applying the module creates what every build shares: the components, the build instance role, the infrastructure configuration a build runs on, and a distribution configuration that names and tags each image in the build region. It creates no image recipe, pipeline, or image. The only way to make a new AMI is a deploy. Each deploy is one release. It:

Creates an image recipe from the parent image, the components in order, and this deploy’s component parameters, then builds it in the build region on a temporary build instance and runs the components’ test phases on an instance launched from the new image.
Copies the new AMI to every additional region.
Tags every image and snapshot it created.
Grants launch permission all on the images in every region when Publish is on.
Retires older images in each region past the retention counts.

A redeploy or a rollback releases an earlier deploy’s images again without rebuilding them.

Use cases

Scenario	Benefit
Golden images	Bake packages, agents, and hardening into an AMI so instances boot ready to work.
Release images	Bake one application release per image and roll it out by changing a launch template.
Multi-region fleets	Build once and copy the image to every region that launches it.
Distributed software	Publish an image for any AWS account to launch.

Components and parameters

A component is an Image Builder document with build, validate, and test phases. Components run in the order listed, and each one names where its document comes from.

Source	What you fill in	When it fits
Steps	Named steps under Build steps, Validate steps, and Test steps	Most components. The module writes the document.
Component document	The YAML document itself	A document you already have, or an action this form does not offer
Existing component ARN	The ARN	An AWS-managed component, or one another module created

A step names an action and what that action needs. Run bash commands and Run PowerShell commands take a list of commands, run in order, and the phase stops at the first one that exits non-zero. Every other action takes Inputs, the JSON its AWS documentation describes. Declare the values that change between releases, such as a release version, under Parameters. A step reads one as {{ ParameterName }}. A parameter’s value is passed by each deploy’s image recipe rather than written into the document, so a deploy can override it without creating a new component. Image Builder components are immutable. This module names each by a hash of its content, so a changed document is a new component beside the old one, and the next deploy builds with it. There is no version to bump.

Deploying

Start a deploy from a pipeline with a deploy step, from the dashboard, or with ravion deploy create. A build commonly takes 20-60 minutes, and the deploy finishes once every copy is available.

- id: release_image
  name: Release image
  type: deploy
  module_instance: << pipeline.variant.id >>.app-image
  input:
    component_parameters:
      provision:
        ReleaseVersion: << steps.build_app.output.version >>
    extra_tags:
      release: << steps.build_app.output.version >>
    publish: true

Input	Default	What it does
Component parameters	None	Parameter values for this deploy, as `{component: {parameter: value}}`. Each overrides the value the component sets here, key by key.
Extra tags	None	Tags added to every AMI and snapshot this deploy creates, in every region.
Publish	Off	Grants launch permission `all` on this deploy’s AMIs in every region. Off keeps them private.

Image Builder drives the build instance through the Systems Manager agent, and installs it on the distributions it supports. Build on a parent image that ships the agent or that Image Builder can install it on.

Retention

Each deploy keeps the newest Published images to keep (5 by default) public in each region, and the next Private images to keep (10 by default) private. Older published images are made private, and images past both counts are deregistered along with their snapshots. AWS allows 5 public AMIs per region by default, and the quota counts every public AMI the account owns in that region, not only the images this module releases. A deploy with Publish on fails in a region at its quota, so keep Published images to keep within what the account allows, and request a higher quota before raising it.

Public images

New AWS accounts block public AMI sharing in every region, and a deploy with Publish on fails in a region that still blocks it. Turning the block off is a change to the account rather than to one image: it covers every image the account owns in that region. Turn it off per region with aws ec2 disable-image-block-public-access --region <region>. A public image cannot be backed by an encrypted snapshot. Publish images built on an unencrypted parent image, in regions where EBS encryption by default is off. AMI tags are visible only to the account that owns the image, even when the image is public.

Configuration

Setting	Required	Default	Notes
AWS account	Yes	None	Account that owns the build infrastructure and the images.
Region	Yes	None	Region images are built in.
Name	Yes	Project, environment, and module given IDs	Prefix of every resource created and of each AMI name.
Parent image	Yes	None	A specific image, or the newest AMI matching an owner and name pattern, looked up again by every deploy.
Components	Yes	None	Steps, documents, or component ARNs, in run order.
Custom root volume	No	Off	Gives the image its own root volume: device name, size, type, IOPS, and throughput.
Instance types	Yes	`m7i.large`	Must match the parent image’s architecture.
Subnet and security groups	No	Default VPC	The build needs outbound internet or VPC endpoints.
Build instance policies	No	Image Builder minimum	What the components need to reach.
Build log bucket and prefix	No	CloudWatch only	Build logs in S3, with write access scoped to the prefix.
AMI name, description, and tags	No	Name and build date	Applied to each image in the build region.
Additional regions	No	None	Regions each deploy copies the image to.
Published images to keep	Yes	5	Published images each region keeps.
Private images to keep	Yes	10	Private images each region keeps after the published ones.

Design decisions

The build instance role carries only the two policies Image Builder requires. Anything the components download or call is granted explicitly, so an image build cannot reach more than it was given. The build instance requires IMDSv2 and is terminated after a failed build unless you keep it for debugging. The distribution configuration covers the build region only and grants no launch permission. Each deploy copies, tags, and publishes the image itself, so an image is never public until a deploy asks for it. The root volume settings describe the image, not one instance. The size becomes the image’s snapshot size, so every instance launched from the image carries at least that much root storage.

Learn more

Inputs reference

All inputs for rvn-aws-ami version 0.1.0. Use the name shown for each field as the input key in module config.

AWS account & region

string

required

AWS account.

Immutable after creation

string

required

Region.

Immutable after creation

General

string

required

Name. Name of the build configurations, and the prefix of the components, the build instance role, each deploy’s image recipe, and the AMI names.

Default: <<project.given_id>>-<<environment.given_id>>-<<module.given_id>>
Immutable after creation
Pattern: ^[A-Za-z0-9][A-Za-z0-9_-]{1,63}$ — 2-64 letters, numbers, hyphens, or underscores. Start with a letter or number.

string

Description. Description stored on the infrastructure and distribution configurations.

Pattern: ^.{0,1024}$ — 1024 characters or fewer.

Parent image

string

required

Parent image source. Pin one parent image, or have every deploy build on the newest image an owner publishes under a name pattern.

Default: image
Allowed values: image (Specific image), lookup (Newest matching AMI)

string

required

Parent image. AMI ID, Image Builder image ARN, or SSM parameter written as ssm:<parameter name>.

Pattern: ^(ami-[0-9a-f]{8,17}|arn:aws[a-z-]*:imagebuilder:[a-z0-9-]+:(aws|[0-9]{12}):image/.+|ssm:.+)$ — Use an AMI ID, an Image Builder image ARN, or ssm:<parameter name>.
Shown when: {"parent_image_source":"image"}

string_array

required

Parent image owners. The accounts that publish the parent image. The lookup considers only images these accounts own. Enter AWS account IDs, such as 136693071363 for Debian or 099720109477 for Canonical’s Ubuntu, or the aliases amazon, aws-marketplace, or self for this account’s own images.

Default: []
Shown when: {"parent_image_source":"lookup"}

string

required

Image name pattern. AMI name pattern. Use * as a wildcard.

Shown when: {"parent_image_source":"lookup"}

string

required

Architecture.

Default: x86_64
Allowed values: x86_64, arm64
Shown when: {"parent_image_source":"lookup"}

Image

object_array

required

Components. Components each deploy’s image recipe runs, in order. Describe what a component does as ordered steps, write its document yourself, or reference an AWS-managed or existing component by ARN.

Default: []

Show item fields

string

required

Name. Short name for this component. Used in the created component’s name.

Pattern: ^[A-Za-z0-9][A-Za-z0-9_-]{0,39}$ — 1-40 letters, numbers, hyphens, or underscores. Start with a letter or number.

string

required

Source. Where this component’s document comes from.

Default: steps
Allowed values: steps (Steps), document (Component document), arn (Existing component ARN)

string

Description. What this component does. Shown on the component in the Image Builder console.

Shown when: {"source":["steps","document"]}

text

required

Component document. Image Builder component document in YAML. Changing it creates a new component, which the next deploy builds with.

Shown when: {"source":"document"}

string

required

Component ARN. ARN of an AWS-managed component or one that already exists in this account. Use x.x.x for the latest version.

Pattern: ^arn:aws[a-z-]*:imagebuilder:[a-z0-9-]+:(aws|[0-9]{12}):component/.+$ — Use an Image Builder component ARN.
Shown when: {"source":"arn"}

object_array

Parameters. Values the steps read as {{ ParameterName }}. Each deploy passes the values to its image recipe and can override them, so changing a value leaves the component alone; changing a name or a default creates a new component.

Default: []
Shown when: {"source":"steps"}

Show item fields

string

required

Name. Name the steps refer to.

Pattern: ^[A-Za-z][A-Za-z0-9_-]{0,127}$ — 1-128 letters, numbers, hyphens, or underscores. Start with a letter.

string

required

Type.

Default: string
Allowed values: string (String), integer (Integer), boolean (Boolean), stringList (List of strings)

string

Value. Value each deploy passes unless the deploy overrides it. Leave blank to use the default.

string

Default. Value used when a deploy passes none.

string

Description. What this parameter controls.

object_array

required

Build steps. Steps that build the image, in order.

Default: []
Shown when: {"source":"steps"}

Show item fields

string

required

Name. Name of this step, unique within the phase.

Pattern: ^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$ — 1-128 letters, numbers, hyphens, or underscores. Start with a letter or number.

string

required

Action. What this step does. The shell actions run the commands below; every other action takes the inputs its AWS documentation describes.

Default: ExecuteBash
Allowed values: ExecuteBash (Run bash commands), ExecutePowerShell (Run PowerShell commands), ExecuteBinary (Run a binary), ExecuteDocument (Run another component document), S3Download (Download from S3), S3Upload (Upload to S3), WebDownload (Download from a URL), CreateFile (Create a file), CopyFile (Copy a file), MoveFile (Move a file), DeleteFile (Delete a file), AppendFile (Append to a file), ReadFile (Read a file), ListFiles (List files), CreateFolder (Create a folder), CopyFolder (Copy a folder), MoveFolder (Move a folder), DeleteFolder (Delete a folder), Reboot, UpdateOS (Update the operating system), Assert (Assert a condition), InstallMSI (Install an MSI), UninstallMSI (Uninstall an MSI), SetRegistry (Set a registry value)

string_array

required

Commands. Commands run in order. The step fails on the first one that exits non-zero.

Default: []
Shown when: {"action":["ExecuteBash","ExecutePowerShell"]}

text

Inputs. Inputs for this action as JSON, in the shape its AWS documentation describes. Leave blank for an action that takes none.

Shown when: {"action":{"not":["ExecuteBash","ExecutePowerShell"]}}

string

On failure. What happens when this step fails.

Default: Abort
Allowed values: Abort, Continue, Ignore

number

Timeout. Seconds this step may run before it is stopped. Leave blank for the Image Builder default.

Min: 1

number

Max attempts. Times this step is retried before the phase fails.

Min: 1

object_array

Validate steps. Steps that check the build instance before the image is created. Run in order after the build phase.

Default: []
Shown when: {"source":"steps"}

Show item fields

string

required

Name. Name of this step, unique within the phase.

Pattern: ^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$ — 1-128 letters, numbers, hyphens, or underscores. Start with a letter or number.

string

required

Action. What this step does. The shell actions run the commands below; every other action takes the inputs its AWS documentation describes.

Default: ExecuteBash
Allowed values: ExecuteBash (Run bash commands), ExecutePowerShell (Run PowerShell commands), ExecuteBinary (Run a binary), ExecuteDocument (Run another component document), S3Download (Download from S3), S3Upload (Upload to S3), WebDownload (Download from a URL), CreateFile (Create a file), CopyFile (Copy a file), MoveFile (Move a file), DeleteFile (Delete a file), AppendFile (Append to a file), ReadFile (Read a file), ListFiles (List files), CreateFolder (Create a folder), CopyFolder (Copy a folder), MoveFolder (Move a folder), DeleteFolder (Delete a folder), Reboot, UpdateOS (Update the operating system), Assert (Assert a condition), InstallMSI (Install an MSI), UninstallMSI (Uninstall an MSI), SetRegistry (Set a registry value)

string_array

required

Commands. Commands run in order. The step fails on the first one that exits non-zero.

Default: []
Shown when: {"action":["ExecuteBash","ExecutePowerShell"]}

text

Inputs. Inputs for this action as JSON, in the shape its AWS documentation describes. Leave blank for an action that takes none.

Shown when: {"action":{"not":["ExecuteBash","ExecutePowerShell"]}}

string

On failure. What happens when this step fails.

Default: Abort
Allowed values: Abort, Continue, Ignore

number

Timeout. Seconds this step may run before it is stopped. Leave blank for the Image Builder default.

Min: 1

number

Max attempts. Times this step is retried before the phase fails.

Min: 1

object_array

Test steps. Steps that check an instance launched from the finished image, after the build.

Default: []
Shown when: {"source":"steps"}

Show item fields

string

required

Name. Name of this step, unique within the phase.

Pattern: ^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$ — 1-128 letters, numbers, hyphens, or underscores. Start with a letter or number.

string

required

Action. What this step does. The shell actions run the commands below; every other action takes the inputs its AWS documentation describes.

Default: ExecuteBash
Allowed values: ExecuteBash (Run bash commands), ExecutePowerShell (Run PowerShell commands), ExecuteBinary (Run a binary), ExecuteDocument (Run another component document), S3Download (Download from S3), S3Upload (Upload to S3), WebDownload (Download from a URL), CreateFile (Create a file), CopyFile (Copy a file), MoveFile (Move a file), DeleteFile (Delete a file), AppendFile (Append to a file), ReadFile (Read a file), ListFiles (List files), CreateFolder (Create a folder), CopyFolder (Copy a folder), MoveFolder (Move a folder), DeleteFolder (Delete a folder), Reboot, UpdateOS (Update the operating system), Assert (Assert a condition), InstallMSI (Install an MSI), UninstallMSI (Uninstall an MSI), SetRegistry (Set a registry value)

string_array

required

Commands. Commands run in order. The step fails on the first one that exits non-zero.

Default: []
Shown when: {"action":["ExecuteBash","ExecutePowerShell"]}

text

Inputs. Inputs for this action as JSON, in the shape its AWS documentation describes. Leave blank for an action that takes none.

Shown when: {"action":{"not":["ExecuteBash","ExecutePowerShell"]}}

string

On failure. What happens when this step fails.

Default: Abort
Allowed values: Abort, Continue, Ignore

number

Timeout. Seconds this step may run before it is stopped. Leave blank for the Image Builder default.

Min: 1

number

Max attempts. Times this step is retried before the phase fails.

Min: 1

string

Platform. Operating system the component runs on.

Allowed values: Linux, Windows, macOS
Shown when: {"source":["steps","document"]}

keyvalue

Parameters. Values for the parameters the component declares. Each deploy passes them to its image recipe unless the deploy overrides them.

Default: {}
Shown when: {"source":["document","arn"]}

boolean

Custom root volume. Give the image a root volume configured here. The volume becomes the image’s snapshot, and its size is the smallest root volume an instance can launch the image with.

Default: false

string

required

Root device name. Root device name of the parent image, for example /dev/xvda or /dev/sda1.

Pattern: ^/dev/[a-z0-9/]+$ — Use a device path, for example /dev/xvda.
Shown when: {"root_volume_override_enabled":true}

number

required

Root volume size (GiB). Size of the image’s root snapshot. Every instance launched from the image gets a root volume at least this large.

Default: 30
Min: 1
Max: 65536
Shown when: {"root_volume_override_enabled":true}

string

Root volume type. EBS volume type of the root volume.

Default: gp3
Allowed values: gp3, gp2, io1, io2
Shown when: {"root_volume_override_enabled":true}

number

Root volume IOPS. Provisioned IOPS for the root volume, 100 to 64,000. Required for io1 and io2. Leave blank on gp3 to take the volume type’s default.

Min: 100
Max: 64000
Shown when: {"root_volume_override_enabled":true,"root_volume_type":["gp3","io1","io2"]}

number

Root volume throughput (MiB/s). Throughput of the root volume in MiB/s. Leave blank to take the gp3 default of 125.

Min: 125
Max: 1000
Shown when: {"root_volume_override_enabled":true,"root_volume_type":"gp3"}

Build infrastructure

string_array

required

Instance types. Instance types a build may run on, in order of preference. They must match the parent image’s architecture.

Default: ["m7i.large"]

string

Subnet ID. Subnet the build instance launches in. It needs outbound access to Systems Manager, Image Builder, S3, and whatever the components download. Leave blank to use the default VPC.

Pattern: ^$|^subnet-[0-9a-f]{8,17}$ — Use a subnet ID.

string_array

Security group IDs. Security groups for the build instance. Required with a subnet ID.

Default: []
Shown when: {"subnet_id":{"not":""}}

string_array

Build instance managed policy ARNs. Managed policies attached to the build instance’s role, beyond the two Image Builder requires.

Default: []
Pattern: ^arn:aws(-cn|-us-gov)?:iam::(aws|\d{12}):policy/.+$ — Use a valid IAM managed policy ARN.

text

Build instance policy JSON. Inline IAM policy for the build instance’s role. Grant what the components need to reach, such as read access to a release bucket.

Pattern: ^\s*$|^\s*\{[\s\S]*"Version"[\s\S]*"Statement"[\s\S]*\}\s*$ — Include a JSON object with Version and Statement properties.

boolean

Terminate instance on failure. Terminate the build instance when a build fails. Turn off to keep it for debugging.

Default: true

string

Build log bucket. S3 bucket the build logs are written to. The build instance is granted write access under the log prefix. Leave blank to keep the logs in CloudWatch only.

Pattern: ^$|^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$ — Use an S3 bucket name.

string

Build log prefix. Key prefix the build logs are written under. An empty prefix writes them at the bucket root.

Default: image-builder
Shown when: {"log_bucket":{"not":""}}

Distribution

string

AMI name. Name of each image built. Include {{ imagebuilder:buildDate }} so that every build gets its own name. Defaults to the name followed by the build date.

Pattern: ^$|\{\{\s*imagebuilder:build(Date|Version)\s*\}\} — Include {{ imagebuilder:buildDate }} or {{ imagebuilder:buildVersion }}.

string

AMI description. Description stored on each image built, in the build region.

Pattern: ^.{0,1024}$ — 1024 characters or fewer.

keyvalue

AMI tags. Tags written on each image built, in the build region. A deploy’s extra tags go on every image and snapshot in every region. Tags are visible only to the owning account, even on a public image.

Default: {}

string_array

Additional regions. Regions each deploy copies the finished image to, beyond the build region.

Default: []

Retention

number

required

Published images to keep. Published images each region keeps. Each deploy makes older published images private. AWS allows 5 public AMIs per region by default, counting every public AMI the account owns there.

Default: 5
Min: 1
Max: 100

number

required

Private images to keep. Private images each region keeps after the public ones. Each deploy deregisters older images and deletes their snapshots.

Default: 10
Min: 0
Max: 1000

Misc

keyvalue

Tags. A map of tags to assign to all resources. Default tags are Owner, ProjectGivenId, EnvironmentGivenId, ModuleGivenId, ModuleId

Terraform settings

string

OpenTofu version override. Override the environment’s default version for this module

string

Ravion Terraform workspace name. Override Terraform state backend workspace name. Defaults to project + environment + module given ids.

Immutable after creation

object

Advanced Terraform variables. Optional raw Terraform variable overrides for advanced module inputs or one-off overrides. Values here override the generated variables above.

Default: {}

string

Terraform execution environment. Override the execution environment for Terraform runners. Must use the same AWS account as selected above.

Introduction

Concepts

Config as code

Migrate

Modules

Pipelines

Guides

Troubleshooting

Agent setup

Module definitions

Readme

Overview

Use cases

Components and parameters

Deploying

Retention

Public images

Configuration

Design decisions

Learn more

Inputs reference

AWS account & region

General

Parent image

Image

Build infrastructure

Distribution

Retention

Misc

Terraform settings

​Readme

​Overview

​Use cases

​Components and parameters

​Deploying

​Retention

​Public images

​Configuration

​Design decisions

​Learn more

​Inputs reference

​AWS account & region

​General

​Parent image

​Image

​Build infrastructure

​Distribution

​Retention

​Misc

​Terraform settings

Readme

Overview

Use cases

Components and parameters

Deploying

Retention

Public images

Configuration

Design decisions

Learn more

Inputs reference

AWS account & region

General

Parent image

Image

Build infrastructure

Distribution

Retention

Misc

Terraform settings