Fjall Docs — deploy AWS infrastructure into your own account

Overview

The Ecr construct provisions an AWS Elastic Container Registry repository for your container images. It extends the CDK Repository construct and applies Fjall defaults: vulnerability scanning on push, immutable tags, an untagged-image reclaim rule, and an environment-aware removal policy. Every Fjall application already has one. app.getDefaultContainerRegistry() creates a repository in the network stack on first call, named after the kebab-cased application name. Generated compute resources reference it directly, so most applications never instantiate Ecr by hand.

Resource Class

import {
  Ecr,
  EcrFactory,
} from "@fjall/components-infrastructure/lib/resources/aws/storage/ecr";

The default repository

// In fjall/api/infrastructure.ts, emitted by `fjall add compute`
app.addCompute(
  ComputeFactory.build("ApiService", {
    type: "ecs",
    ecrRepository: app.getDefaultContainerRegistry(),
    // ...
  }),
);

Aspect	Value
Construct id	`<PascalCaseAppName>Ecr`
Repository name	Kebab-cased application name, so `WebApp` becomes `web-app`
Stack	The application’s network stack
CFN export	`<PascalCaseAppName>EcrRepositoryName`

fjall build and fjall deploy read that CloudFormation export to find the repository before pushing. Deriving the name yourself risks drifting from the construct.

Basic Usage

const repository = new Ecr(this, "AppRepository", {
  repositoryName: "api",
});

Ecr accepts four props only. It does not forward arbitrary CDK RepositoryProps.

Default Configuration

Feature	Default	Description
`imageScanOnPush`	`true`	Vulnerability scanning runs on every push
`imageTagMutability`	`IMMUTABLE`	Tags cannot be overwritten, push a new tag per build
Lifecycle policy	Untagged images expire after 7 days	One rule at priority 1, `tagStatus: UNTAGGED`
`removalPolicy`	Environment-aware, `RETAIN` in production	Every other environment resolves `DESTROY`
`emptyOnDelete`	Paired with the removal policy	`false` under `RETAIN`, `true` under `DESTROY`

Tags are immutable by default. You cannot re-push :latest over an existing image. Push a unique tag per build, or pass tagMutability: TagMutability.MUTABLE for a repository that deliberately repushes the same tag (a dev slot, or a buildx cache repository).

Outside production, the repository and every image in it are deleted with the stack. A redeploy after that teardown pulls “not found” for any tag the old repository held. Pass removalPolicy: "RETAIN" on repositories whose images must outlive the stack.

Configuration Options

Property	Type	Description	Default
`repositoryName`	`string`	Physical repository name	CDK-generated
`tagMutability`	`TagMutability`	`IMMUTABLE` or `MUTABLE`	`IMMUTABLE`
`removalPolicy`	`"DESTROY" \| "RETAIN"`	Overrides the environment-aware default	Environment-aware, see below
`lifecycle`	`EcrLifecycle \| false`	Image-reclaim policy, `false` removes the built-in rules entirely	`ECR_LIFECYCLE_DEFAULTS`

EcrLifecycle

Property	Type	Description	Default
`untaggedRetentionDays`	`number`	Days an untagged image survives before expiry	`7`
`maxImageCount`	`number`	Opt-in cap on newest tagged images to keep	Not applied

Removal Policy

The default resolves from the deploy environment, which Fjall derives from the target account’s record and passes to CDK synth. It is not a flag you set on fjall deploy.

Environment	Removal policy	`emptyOnDelete`
`production`	`RETAIN`	`false`
`staging`, `development`, `platform`, `compliance`, `root`	`DESTROY`	`true`

CloudFormation refuses to delete a repository that still holds images, so DESTROY always ships with emptyOnDelete: true. The pair is deliberate, not a gentler DESTROY.

// Keep release images in a staging account
const repository = new Ecr(this, "ReleaseRepository", {
  repositoryName: "api-releases",
  removalPolicy: "RETAIN",
});

An unrecognised ENVIRONMENT value fails at synth rather than guessing. A typo such as ENVIRONMENT=prod would otherwise resolve DESTROY and delete images on teardown. Valid values are production, staging, development, platform, compliance and root.

Lifecycle Policy

The built-in rule

Every Ecr repository ships one lifecycle rule: expire untagged images after 7 days, at rulePriority: 1, tagStatus: UNTAGGED. Each CI push is an image. Without a reclaim rule a repository grows without bound. Fjall’s own web-app repository reached 1,473 images and roughly 55 GB before this default existed. Untagged expiry is safe for buildx provenance and SBOM pushes. ECR never expires an image still referenced by a live manifest list, so the untagged attestation and platform children of a tagged index become reclaimable only once the index goes.

Changing the retention window

const repository = new Ecr(this, "AppRepository", {
  repositoryName: "api",
  lifecycle: { untaggedRetentionDays: 3 },
});

Capping the image count

const repository = new Ecr(this, "ToolingRepository", {
  repositoryName: "tooling",
  lifecycle: { untaggedRetentionDays: 7, maxImageCount: 30 },
});

maxImageCount emits a second rule at priority 2 with tagStatus: ANY.

maxImageCount is opt-in for a reason. Count expiry is release-blind, so it cannot know which images your retained releases still reference. On monitored accounts Fjall’s release-aware retention janitor treats any tagStatus: any + imageCountMoreThan rule as the retired shape it supersedes and strips it from release-referenced repositories. Reach for it only on repositories outside release monitoring.

Owning the rules yourself

ECR permits exactly one untagged-selecting rule per policy and requires unique priorities. Adding your own rules on top of the built-in policy fails the stack at deploy. Pass lifecycle: false first, then add every rule yourself.

import { TagStatus } from "aws-cdk-lib/aws-ecr";
import { Duration } from "aws-cdk-lib";

const repository = new Ecr(this, "AppRepository", {
  repositoryName: "api",
  lifecycle: false,
});

// Untagged selector carries the highest priority (lowest number)
repository.addLifecycleRule({
  description: "Expire untagged images after 3 days",
  tagStatus: TagStatus.UNTAGGED,
  maxImageAge: Duration.days(3),
  rulePriority: 1,
});

repository.addLifecycleRule({
  description: "Keep the last 50 release images",
  tagPrefixList: ["release"],
  maxImageCount: 50,
  rulePriority: 2,
});

// A tagStatus: ANY rule must carry the lowest priority (highest number)
repository.addLifecycleRule({
  description: "Keep the newest 200 images overall",
  tagStatus: TagStatus.ANY,
  maxImageCount: 200,
  rulePriority: 3,
});

Image Scanning

Scanning runs on every push. Results appear in the ECR console and on the CloudWatch event bus.

import { Rule } from "aws-cdk-lib/aws-events";
import { SnsTopic } from "aws-cdk-lib/aws-events-targets";
import { Topic } from "aws-cdk-lib/aws-sns";

const scanTopic = new Topic(this, "ScanAlerts");

new Rule(this, "ScanRule", {
  eventPattern: {
    source: ["aws.ecr"],
    detailType: ["ECR Image Scan"],
    detail: {
      "repository-name": [repository.repositoryName],
      "scan-status": ["COMPLETE"],
      "finding-severity-counts": {
        CRITICAL: [{ numeric: [">", 0] }],
      },
    },
  },
  targets: [new SnsTopic(scanTopic)],
});

Access Control

Ecr extends the CDK Repository, so every grant and policy method is available.

// Pull for an ECS task role
repository.grantPull(taskRole);

// Pull and push for a build role
repository.grantPullPush(buildRole);

// Anything else
repository.grant(auditRole, "ecr:DescribeImages", "ecr:ListImages");

Cross-account pulls

import { AccountPrincipal, PolicyStatement } from "aws-cdk-lib/aws-iam";

repository.addToResourcePolicy(
  new PolicyStatement({
    principals: [new AccountPrincipal("123456789012")],
    actions: [
      "ecr:GetDownloadUrlForLayer",
      "ecr:BatchGetImage",
      "ecr:BatchCheckLayerAvailability",
    ],
  }),
);

Building and Pushing Images

Fjall builds and pushes for you. Do not wire a separate CodeBuild or GitHub Actions push path unless you have a reason to.

# Build and push every service in the app
fjall build api

# Build one service, with a multi-stage target and a build arg
fjall build api web --target production --build-arg NODE_ENV=production

# Build and push from CI with a deploy token
fjall ci run build api

fjall deploy api builds and pushes as part of the deploy. Use --skip-build when the image is already in the repository.

Encryption

Ecr does not expose encryption or encryptionKey. Its four props are repositoryName, tagMutability, removalPolicy and lifecycle. For a customer-managed key, instantiate the CDK Repository construct directly and apply the defaults you want by hand.

import { Repository, RepositoryEncryption } from "aws-cdk-lib/aws-ecr";
import { Key } from "aws-cdk-lib/aws-kms";

const key = new Key(this, "RepoKey", {
  description: "ECR repository encryption key",
});

const repository = new Repository(this, "EncryptedRepo", {
  encryption: RepositoryEncryption.KMS,
  encryptionKey: key,
});

AES-256 is the ECR default. Pass RepositoryEncryption.KMS without a key for the AWS-managed KMS key.

Outputs

Each Ecr construct emits one CloudFormation output and export:

Output	Value
`<id>RepositoryName`	The repository name

The export name matches the output key, so the CLI resolves the repository for fjall build and fjall deploy without guessing at the name.

Factory Pattern

EcrFactory

const repositoryFactory = EcrFactory.build("AppRepository", {
  repositoryName: "api",
});

const repository = repositoryFactory(app, this);

EcrFactory.build registers the repository with the application’s manifest collector, which is how the CLI discovers it at build and push time. A bare new Ecr(...) skips that registration silently.

StackBuilder

const repository = Ecr.build("AppRepository", {
  repositoryName: "api",
})(stackBuilder);

Complete Example

import { Ecr } from "@fjall/components-infrastructure/lib/resources/aws/storage/ecr";
import { TagMutability } from "aws-cdk-lib/aws-ecr";
import {
  ContainerImage,
  FargateTaskDefinition,
  LogDrivers,
} from "aws-cdk-lib/aws-ecs";

// Release repository: images outlive the stack, tags stay immutable,
// untagged manifests reclaim after three days.
const repository = new Ecr(this, "ApiRepository", {
  repositoryName: "api",
  tagMutability: TagMutability.IMMUTABLE,
  removalPolicy: "RETAIN",
  lifecycle: { untaggedRetentionDays: 3 },
});

const taskDefinition = new FargateTaskDefinition(this, "ApiTask", {
  cpu: 256,
  memoryLimitMiB: 512,
});

taskDefinition.addContainer("api", {
  image: ContainerImage.fromEcrRepository(repository, "2026.09.04-1"),
  portMappings: [{ containerPort: 3000 }],
  logging: LogDrivers.awsLogs({ streamPrefix: "api" }),
});

ContainerImage.fromEcrRepository grants pull to the task execution role for you.

Monitoring

import { Alarm, Metric } from "aws-cdk-lib/aws-cloudwatch";

new Alarm(this, "RepoSizeAlarm", {
  metric: new Metric({
    namespace: "AWS/ECR",
    metricName: "RepositorySizeBytes",
    dimensionsMap: { RepositoryName: repository.repositoryName },
  }),
  threshold: 10 * 1024 * 1024 * 1024,
  evaluationPeriods: 1,
});

Cost Optimisation

Storage bills per GB-month. The untagged reclaim rule is the cheapest lever, shorten untaggedRetentionDays on repositories with heavy CI churn.
Data transfer is free within the same region and billed per GB across regions. Use VPC endpoints for in-VPC pulls.
Shrink images with multi-stage builds before reaching for retention limits.

Check the AWS ECR pricing page for current rates.

Troubleshooting

Symptom	Cause	Fix
`tag invalid: ... cannot be overwritten`	Tags are `IMMUTABLE`	Push a unique tag, or set `tagMutability: TagMutability.MUTABLE`
Pull fails “not found” after a teardown and redeploy	Non-production resolved `DESTROY`, the images went with the repository	Set `removalPolicy: "RETAIN"`, or rebuild with `fjall build <app>`
Untagged manifests vanish about a week after a failed push	The built-in 7-day untagged rule	Raise `lifecycle: { untaggedRetentionDays }`
Deploy fails on the lifecycle policy	A second untagged rule, or a duplicate priority	Pass `lifecycle: false` before adding your own rules
Synth fails with “Unrecognised environment”	`ENVIRONMENT` is a typo or is unset on a Fjall-driven deploy	Set the target account’s environment, or pass `-c environment=<value>`
Push denied	The pushing role lacks ECR permissions	`repository.grantPullPush(role)`

Inspecting a repository

Run AWS commands against a connected account with Fjall-minted credentials:

fjall target list
fjall aws exec --target production-use1 -- aws ecr describe-repositories --repository-names api
fjall aws exec --target production-use1 -- aws ecr list-images --repository-name api

Next Steps

Build Images

Build and push container images to the repository with fjall build.

ECS Cluster

Run containers from your ECR images on Fargate or EC2.

S3 Bucket

Store objects and static assets alongside your images.

CI/CD Deploys

Build, deploy and mint deploy tokens from a CI pipeline.

Compute Resources

Database Resources

Storage Resources

Networking Resources

Messaging Resources

Security Resources

ECR Repository

Overview

Resource Class

The default repository

Basic Usage

Default Configuration

Configuration Options

EcrLifecycle

Removal Policy

Lifecycle Policy

The built-in rule

Changing the retention window

Capping the image count

Owning the rules yourself

Image Scanning

Access Control

Cross-account pulls

Building and Pushing Images

Encryption

Outputs

Factory Pattern

EcrFactory

StackBuilder

Complete Example

Monitoring

Cost Optimisation

Troubleshooting

Inspecting a repository

Next Steps

Build Images

ECS Cluster

S3 Bucket

CI/CD Deploys

​Overview

​Resource Class

​The default repository

​Basic Usage

​Default Configuration

​Configuration Options

​EcrLifecycle

​Removal Policy

​Lifecycle Policy

​The built-in rule

​Changing the retention window

​Capping the image count

​Owning the rules yourself

​Image Scanning

​Access Control

​Cross-account pulls

​Building and Pushing Images

​Encryption

​Outputs

​Factory Pattern

​EcrFactory

​StackBuilder

​Complete Example

​Monitoring

​Cost Optimisation

​Troubleshooting

​Inspecting a repository

​Next Steps

Build Images

ECS Cluster

S3 Bucket

CI/CD Deploys

Overview

Resource Class

The default repository

Basic Usage

Default Configuration

Configuration Options

EcrLifecycle

Removal Policy

Lifecycle Policy

The built-in rule

Changing the retention window

Capping the image count

Owning the rules yourself

Image Scanning

Access Control

Cross-account pulls

Building and Pushing Images

Encryption

Outputs

Factory Pattern

EcrFactory

StackBuilder

Complete Example

Monitoring

Cost Optimisation

Troubleshooting

Inspecting a repository

Next Steps