ECR Image Management

Simfra implements the full ECR API and a Docker Registry V2 HTTP endpoint. You can push, pull, and manage container images using standard Docker tools, and reference those images in Lambda functions and ECS task definitions.

Prerequisites

  • SIMFRA_DOCKER=true
  • Docker CLI installed

Create a Repository

aws --endpoint-url http://localhost:4599 ecr create-repository \
  --repository-name my-app

The response includes the repository URI:

{
  "repository": {
    "repositoryUri": "000000000000.dkr.ecr.us-east-1.localhost:4599/my-app",
    "repositoryName": "my-app"
  }
}

Authenticate Docker

Get an authorization token and pass it to docker login:

aws --endpoint-url http://localhost:4599 ecr get-login-password | \
  docker login --username AWS --password-stdin \
  000000000000.dkr.ecr.us-east-1.localhost:4599

The registry URL format is {accountId}.dkr.ecr.{region}.localhost:4599. Simfra's gateway routes requests matching this pattern to the built-in Registry V2 handler.

Auth tokens are valid for 12 hours by default. IAM ecr:GetAuthorizationToken permission is enforced.

Push an Image

Tag your local image with the ECR repository URI and push:

docker tag myimage:latest 000000000000.dkr.ecr.us-east-1.localhost:4599/my-app:latest
docker push 000000000000.dkr.ecr.us-east-1.localhost:4599/my-app:latest

Simfra stores layer blobs in memory by default. When SIMFRA_DATA_DIR is set, blobs are written to the filesystem under $SIMFRA_DATA_DIR/ecr/ for persistence across restarts.

Pull an Image

docker pull 000000000000.dkr.ecr.us-east-1.localhost:4599/my-app:latest

Using ECR Images in Other Services

Lambda

Reference an ECR image when creating a function with PackageType=Image:

aws --endpoint-url http://localhost:4599 lambda create-function \
  --function-name my-func \
  --package-type Image \
  --code ImageUri=000000000000.dkr.ecr.us-east-1.localhost:4599/my-app:latest \
  --role arn:aws:iam::000000000000:role/lambda-role

ECS

Reference ECR images in task definitions:

{
  "containerDefinitions": [
    {
      "name": "app",
      "image": "000000000000.dkr.ecr.us-east-1.localhost:4599/my-app:latest"
    }
  ]
}

ECS task execution roles are validated for ecr:GetAuthorizationToken and ecr:BatchGetImage permissions, matching real AWS behavior.

Lifecycle Policies

ECR lifecycle policies are supported. Define rules to expire images by age or count:

aws --endpoint-url http://localhost:4599 ecr put-lifecycle-policy \
  --repository-name my-app \
  --lifecycle-policy-text file://policy.json

Repository Policies

Resource-based policies control access to repositories:

aws --endpoint-url http://localhost:4599 ecr set-repository-policy \
  --repository-name my-app \
  --policy-text file://repo-policy.json

These policies are enforced for cross-account access and service-to-service pulls.

Multi-Architecture Images

The Registry V2 handler supports both Docker manifest V2 and OCI image manifests, including manifest lists for multi-architecture images. Push manifests with docker buildx or docker manifest commands.

KMS Encryption

ECR repositories can be encrypted with a KMS key:

aws --endpoint-url http://localhost:4599 ecr create-repository \
  --repository-name my-app \
  --encryption-configuration encryptionType=KMS,kmsKey=arn:aws:kms:us-east-1:000000000000:key/my-key

The KMS key is validated at creation time.

Next Steps