> ## Documentation Index
> Fetch the complete documentation index at: https://www.ravion.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# AWS ECR Repository

> Creates a private Amazon ECR repository for container images with scan on push, image cleanup, optional KMS encryption, and cross-account access.

**Type:** `rvn-aws-ecr` / **Latest version:** `1.0.0`

## Readme

Creates a private Amazon ECR repository for container images with scan on push, image cleanup, optional KMS encryption, and cross-account access.

### Overview

Use this module to keep container images in a private Amazon ECR repository for application services and CI pipelines. Images are scanned on push by default, and the repository can grant selected AWS principals pull or push access.

### Use cases

| Scenario | Benefit |
| - | - |
| Store application images | Keep images in a private repository for ECS, EKS, or other container workloads. |
| Share images across accounts | Grant selected IAM principals pull or push access to the repository. |
| Retain recent builds | Expire old images with the built-in lifecycle policy. |

### Image cleanup

Cleanup is enabled by default. The policy expires untagged images after 14 days and keeps the newest 100 images (tagged or untagged), matching the policy used by ECS and EKS service repositories. Change the two counts to suit your rollback needs.

Raw JSON lifecycle policies are available only through Advanced Terraform variables as `lifecycle_policy`; when set, that policy takes precedence over the built-in rules.

### Repository access

Pull principal ARNs grant image pull access, while push principal ARNs grant pull and push access. Both lists are empty by default. For principals in the same account, IAM policies can grant access without adding a repository policy.

Raw JSON repository policies are available only through Advanced Terraform variables as `repository_policy`; when set, that policy takes precedence over the principal lists.

### Encryption

Repositories use AES-256 encryption with an AWS-owned key by default. Choose AWS KMS to use a customer-managed key; leaving KMS key ARN empty uses the AWS-managed `aws/ecr` key. Encryption type and KMS key ARN are immutable because changing either replaces the repository.

### Configuration

| Setting | Required | Default | Notes |
| - | - | - | - |
| AWS account | Yes | None | Account where the repository is created. |
| Region | Yes | None | AWS Region for the repository. |
| Repository name | Yes | Project, environment, and module given IDs | Lowercase name; use slashes to group repositories. Cannot be changed later. |
| Image tag mutability | Yes | `MUTABLE` | Choose `IMMUTABLE` to prevent existing tags from being overwritten. |
| Scan images on push | No | `true` | Runs basic ECR scanning on each push. |
| Clean up old images | No | `true` | Enables the built-in lifecycle policy. |
| Expire untagged images after (days) | When cleanup is enabled | `14` | Minimum 1 day. |
| Images to keep | When cleanup is enabled | `100` | Minimum 1 image. |
| Pull principal ARNs | No | Empty list | Principals granted pull access. |
| Push principal ARNs | No | Empty list | Principals granted push and pull access. |
| Encryption | Yes | `AES256` | Choose `KMS` for customer-managed KMS encryption. |
| KMS key ARN | No | None | Shown for KMS encryption; blank uses the AWS-managed `aws/ecr` key. |
| Force delete repository | No | `false` | Allows deleting the repository when it contains images. |
| Tags | No | Standard Ravion tags | Additional tags assigned to resources. |
| Terraform execution environment | No | None | Optional runner environment override in the selected AWS account. |
| OpenTofu version override | No | Environment default | Optional version override for this module. |
| Ravion Terraform workspace name | No | Generated from project, environment, module, and stack IDs | Optional state workspace override. |
| Include default plan policies | No | `true` | Keeps the default read-only plan policies. |
| Terraform plan IAM policies | No | Empty list | Managed policy ARNs attached to the plan runner role. |
| Include default apply policies | No | `true` | Keeps the default apply policies. |
| Terraform apply IAM policies | No | Empty list | Managed policy ARNs attached to the apply runner role. |
| Advanced Terraform variables | No | Empty object | Overrides Terraform variables, including raw JSON lifecycle or repository policies. |

### Design decisions

The form defaults to mutable tags, scan on push, and image cleanup. The cleanup defaults preserve recent images while placing a time limit on untagged images.

Encryption type and KMS key ARN cannot be changed after creation because ECR replaces the repository when these settings change. Force deletion is off by default.

### Learn more

* [Amazon ECR repositories](https://docs.aws.amazon.com/AmazonECR/latest/userguide/Repositories.html)
* [Amazon ECR lifecycle policies](https://docs.aws.amazon.com/AmazonECR/latest/userguide/LifecyclePolicies.html)
* [Amazon ECR repository policies](https://docs.aws.amazon.com/AmazonECR/latest/userguide/repository-policies.html)
* [Source module](https://github.com/ravionhq/modules/tree/rvn-aws-ecr@1.0.0/containers/ecr)

## Inputs reference

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

### AWS account & region

**aws\_account\_id** `string` *required*

**AWS account.**

* Immutable after creation

**aws\_region** `string` *required*

**Region.**

* Immutable after creation

### Repository

**name** `string` *required*

**Repository name.** Use slashes to group repositories, such as team/api.

* Default: `<<project.given_id>>-<<environment.given_id>>-<<module.given_id>>`
* Immutable after creation
* Pattern: `^(?:[a-z0-9]+(?:[._-][a-z0-9]+)*/)*[a-z0-9]+(?:[._-][a-z0-9]+)*$` — Lowercase letters, numbers, and . \_ - / separators. Start and end with a letter or number.
* Pattern: `^.{2,256}$` — 2-256 characters.

**image\_tag\_mutability** `string` *required*

**Image tag mutability.** Immutable tags can't be pushed again, so a tag always points at the same image.

* Default: `MUTABLE`
* Allowed values: `MUTABLE` (Mutable), `IMMUTABLE` (Immutable)

**image\_scan\_on\_push\_enabled** `boolean`

**Scan images on push.** Basic ECR vulnerability scan on every push. Turn off if another scanner covers it.

* Default: `true`

### Image cleanup

**default\_lifecycle\_policy\_enabled** `boolean`

**Clean up old images.** Expires untagged images after a set period and limits how many images (tagged or untagged) are retained.

* Default: `true`

**untagged\_image\_expiry\_days** `number` *required*

**Expire untagged images after (days).**

* Default: `14`
* Min: `1`
* Shown when: `{"default_lifecycle_policy_enabled":true}`

**max\_tagged\_image\_count** `number` *required*

**Images to keep.** Older images are expired once the repository holds more than this, tagged or untagged. Keep it above the number of images you may roll back to.

* Default: `100`
* Min: `1`
* Shown when: `{"default_lifecycle_policy_enabled":true}`

### Repository access

**allowed\_pull\_principal\_arns** `string_array`

**Pull principal ARNs.** Principals in this or other accounts that can pull images. Principals in this account can also be granted access through IAM policies alone.

* Default: `[]`
* Pattern: `^arn:aws(-us-gov|-cn|-iso|-iso-b|-iso-e|-iso-f)?:iam::[0-9]{12}:(root|(role|user)/[!-~]*[A-Za-z0-9+=,.@_-])$` — Invalid IAM principal ARN. Use an account root, role, or user ARN with a 12-digit account ID.

**allowed\_push\_principal\_arns** `string_array`

**Push principal ARNs.** Principals that can push and pull images, such as a CI role in another account.

* Default: `[]`
* Pattern: `^arn:aws(-us-gov|-cn|-iso|-iso-b|-iso-e|-iso-f)?:iam::[0-9]{12}:(root|(role|user)/[!-~]*[A-Za-z0-9+=,.@_-])$` — Invalid IAM principal ARN. Use an account root, role, or user ARN with a 12-digit account ID.

### Encryption

**encryption\_type** `string` *required*

**Encryption.**

* Default: `AES256`
* Allowed values: `AES256` (AES-256 (AWS owned key)), `KMS` (AWS KMS)
* Immutable after creation

**kms\_key\_arn** `string`

**KMS key ARN.** Leave empty to use the AWS managed aws/ecr key.

* Immutable after creation
* Pattern: `^arn:aws(-us-gov|-cn|-iso|-iso-b|-iso-e|-iso-f)?:kms:[a-z0-9-]+:[0-9]{12}:key/[A-Za-z0-9-]+$` — Invalid KMS key ARN.
* Shown when: `{"encryption_type":"KMS"}`

### Misc

**force\_delete\_enabled** `boolean`

**Force delete repository.** Allow the repository to be deleted even when it contains images. Use with care.

* Default: `false`

**tags** `keyvalue`

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

### Terraform settings

**opentofu\_version** `string`

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

**ravion\_state\_backend\_workspace** `string`

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

* Immutable after creation

**terraform\_plan\_default\_policies\_enabled** `boolean`

**Include default plan policies.** Turn off to plan with only the policies below instead of the default read-only policies. Requires at least one policy below.

* Default: `true`

**terraform\_plan\_iam\_policy\_arns** `string_array`

**Terraform plan IAM policies.** IAM managed policy ARNs for the Terraform plan runner role. Without default policies, allow s3:CreateBucket, s3:PutObject, s3:GetObject, and s3:ListBucket on the ravion-terraform-plans-\<AWS account number> bucket in this account.

* Default: `[]`

**terraform\_apply\_default\_policies\_enabled** `boolean`

**Include default apply policies.** Turn off to apply and destroy with only the policies below instead of AdministratorAccess. Requires at least one policy below.

* Default: `true`

**terraform\_apply\_iam\_policy\_arns** `string_array`

**Terraform apply IAM policies.** IAM managed policy ARNs for the Terraform apply runner role. Without default policies, allow s3:CreateBucket, s3:PutObject, s3:GetObject, and s3:ListBucket on the ravion-terraform-plans-\<AWS account number> bucket in this account.

* Default: `[]`

**advanced\_terraform\_variables** `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: `{}`

**execution\_environment\_id** `string`

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.