> ## Documentation Index > Fetch the complete documentation index at: https://ravion-b90c0359-devin-1788408180-cross-module-output-refs.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # AMI > Creates the EC2 Image Builder infrastructure an AMI is baked on. Each deploy builds an AMI from a parent image and ordered components, copies it to every region, publishes it when asked, and retires older images. **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: 1. 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. 2. Copies the new AMI to every additional region. 3. Tags every image and snapshot it created. 4. Grants launch permission `all` on the images in every region when Publish is on. 5. 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. ```yaml theme={null} - 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 `. 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 * [EC2 Image Builder](https://docs.aws.amazon.com/imagebuilder/latest/userguide/what-is-image-builder.html) * [Component documents](https://docs.aws.amazon.com/imagebuilder/latest/userguide/toe-use-documents.html) * [Make an AMI public](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/sharingamis-intro.html) * [Source module](https://github.com/ravionhq/modules/tree/rvn-aws-ami@0.1.0/compute/ami) ## 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 **AWS account.** * Immutable after creation **Region.** * Immutable after creation ### General **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: `<>-<>-<>` * 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. **Description.** Description stored on the infrastructure and distribution configurations. * Pattern: `^.{0,1024}$` — 1024 characters or fewer. ### Parent image **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) **Parent image.** AMI ID, Image Builder image ARN, or SSM parameter written as ssm:\. * 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:\. * Shown when: `{"parent_image_source":"image"}` **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"}` **Image name pattern.** AMI name pattern. Use \* as a wildcard. * Shown when: `{"parent_image_source":"lookup"}` **Architecture.** * Default: `x86_64` * Allowed values: `x86_64`, `arm64` * Shown when: `{"parent_image_source":"lookup"}` ### Image **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: `[]` **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. **Source.** Where this component's document comes from. * Default: `steps` * Allowed values: `steps` (Steps), `document` (Component document), `arn` (Existing component ARN) **Description.** What this component does. Shown on the component in the Image Builder console. * Shown when: `{"source":["steps","document"]}` **Component document.** Image Builder component document in YAML. Changing it creates a new component, which the next deploy builds with. * Shown when: `{"source":"document"}` **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"}` **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"}` **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. **Type.** * Default: `string` * Allowed values: `string` (String), `integer` (Integer), `boolean` (Boolean), `stringList` (List of strings) **Value.** Value each deploy passes unless the deploy overrides it. Leave blank to use the default. **Default.** Value used when a deploy passes none. **Description.** What this parameter controls. **Build steps.** Steps that build the image, in order. * Default: `[]` * Shown when: `{"source":"steps"}` **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. **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) **Commands.** Commands run in order. The step fails on the first one that exits non-zero. * Default: `[]` * Shown when: `{"action":["ExecuteBash","ExecutePowerShell"]}` **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"]}}` **On failure.** What happens when this step fails. * Default: `Abort` * Allowed values: `Abort`, `Continue`, `Ignore` **Timeout.** Seconds this step may run before it is stopped. Leave blank for the Image Builder default. * Min: `1` **Max attempts.** Times this step is retried before the phase fails. * Min: `1` **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"}` **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. **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) **Commands.** Commands run in order. The step fails on the first one that exits non-zero. * Default: `[]` * Shown when: `{"action":["ExecuteBash","ExecutePowerShell"]}` **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"]}}` **On failure.** What happens when this step fails. * Default: `Abort` * Allowed values: `Abort`, `Continue`, `Ignore` **Timeout.** Seconds this step may run before it is stopped. Leave blank for the Image Builder default. * Min: `1` **Max attempts.** Times this step is retried before the phase fails. * Min: `1` **Test steps.** Steps that check an instance launched from the finished image, after the build. * Default: `[]` * Shown when: `{"source":"steps"}` **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. **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) **Commands.** Commands run in order. The step fails on the first one that exits non-zero. * Default: `[]` * Shown when: `{"action":["ExecuteBash","ExecutePowerShell"]}` **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"]}}` **On failure.** What happens when this step fails. * Default: `Abort` * Allowed values: `Abort`, `Continue`, `Ignore` **Timeout.** Seconds this step may run before it is stopped. Leave blank for the Image Builder default. * Min: `1` **Max attempts.** Times this step is retried before the phase fails. * Min: `1` **Platform.** Operating system the component runs on. * Allowed values: `Linux`, `Windows`, `macOS` * Shown when: `{"source":["steps","document"]}` **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"]}` **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` **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}` **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}` **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}` **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"]}` **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 **Instance types.** Instance types a build may run on, in order of preference. They must match the parent image's architecture. * Default: `["m7i.large"]` **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. **Security group IDs.** Security groups for the build instance. Required with a subnet ID. * Default: `[]` * Shown when: `{"subnet_id":{"not":""}}` **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. **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. **Terminate instance on failure.** Terminate the build instance when a build fails. Turn off to keep it for debugging. * Default: `true` **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. **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 **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 }}. **AMI description.** Description stored on each image built, in the build region. * Pattern: `^.{0,1024}$` — 1024 characters or fewer. **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: `{}` **Additional regions.** Regions each deploy copies the finished image to, beyond the build region. * Default: `[]` ### Retention **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` **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 **Tags.** A map of tags to assign to all resources. Default tags are `Owner`, `ProjectGivenId`, `EnvironmentGivenId`, `ModuleGivenId`, `ModuleId` ### Terraform settings **OpenTofu version override.** Override the environment's default version for this module **Ravion Terraform workspace name.** Override Terraform state backend workspace name. Defaults to project + environment + module given ids. * Immutable after creation **Advanced Terraform variables.** Optional raw Terraform variable overrides for advanced module inputs or one-off overrides. Values here override the generated variables above. * Default: `{}` **Terraform execution environment.** Override the execution environment for Terraform runners. Must use the same AWS account as selected above.