Skip to content

EcrBuilder

Purpose

The EcrBuilder class is a concrete implementation of the AbstractAWSResourceBuilder designed to create AWS Elastic Container Registry (ECR) repositories following organizational security and operational standards. This builder creates secure container image repositories with optional customer-managed KMS encryption, automatic vulnerability scanning, lifecycle management for image retention, and cross-account access policies for multi-environment deployments.

Dependencies

This builder requires the following AWS resources and permissions:

Required AWS Permissions

  • ECR: Repository creation, policy management, and lifecycle rule configuration
  • KMS: Key creation and management (when encryption is enabled)
  • IAM: Policy creation and cross-account access management
  • Parameter Store: Write access for storing repository references
  • Resource Tagging: Permissions to apply organizational tags

Foundation Dependencies

  • Multi-Account Setup: Account configurations for cross-environment access
  • Environment Configuration: Account mappings for all target environments
  • Naming Standards: Organizational resource naming conventions
  • Security Policies: Cross-account trust relationships for image sharing

Configuration

The builder uses the EcrConfig model for the validation of your configuration and becomes the authoritative source of all ecr settings.

CDK Configuration Structure

{
  "repository_name": {
    "use_kms_key": true,
    "images_retained": 10,
    "shareable_with_all_envs": true
  }
}

Configuration Parameters

Parameter Mandatory Type Default Description
Yes str The configuration key that becomes the repository base name
use_kms_key No bool false Enable customer-managed KMS encryption for images
images_retained No int None Maximum number of images to retain (enables lifecycle policy)
shareable_with_all_envs No bool false Enable cross-account access for all environments

Image Retention Behavior

  • When images_retained is set: Creates lifecycle rule to keep only the specified number of newest images
  • When images_retained is null: No lifecycle policy is applied (unlimited retention)
  • Retention Logic: Keeps the most recently pushed images, automatically deletes older ones

Cross-Account Sharing

  • When shareable_with_all_envs is set to true: Grants pull access to all configured environment accounts
  • When shareable_with_all_envs is set to false: Repository accessible only within the current account
  • Permissions Granted: Read-only access (pull images, describe repository, scan results)

Usage

Here’s an example of how to use the EcrBuilder to build an ECR repo in a CDK stack:

ecr_config = app_helper.get_from_env("secret_name")

ecr_builder = EcrBuilder()
ecr_repo = ecr_builder.set_application_helper(app_helper) \
                      .set_builder_config(ecr_config) \
                      .set_ecr_repo_base_name("repository_name") \
                      .build(scope_from_stack)

Behavior and Features

Automatic Repository Configuration

Security Features:

  • Image Scanning: Vulnerability scanning enabled on every image push
  • Encryption: Optional customer-managed KMS keys for enhanced security
  • Empty on Delete: Repositories automatically emptied when stack is destroyed
  • Cross-Account Policies: Fine-grained permissions for multi-account access

Lifecycle Management:

  • Retention Policies: Automatic cleanup of old images based on configuration
  • Priority-Based Rules: Latest images always preserved regardless of push frequency
  • Cost Optimization: Reduces storage costs by removing unused images

Naming Convention

Repository names follow the pattern: {organization-prefix}-{app-name}-{repo-base-name}

The builder automatically:

  • Applies organizational naming standards
  • Converts names to lowercase
  • Truncates names to respect AWS ECR limits (256 characters)
  • Ensures name uniqueness within the account

Parameter Store Integration

Each repository automatically creates Parameter Store entries for cross-stack references:

  • Repository ARN: ECR_{REPO_BASE_NAME_UPPER}_arn
  • Repository Name: ECR_{REPO_BASE_NAME_UPPER}_name
  • KMS Key ARN: ECR_{REPO_BASE_NAME_UPPER}_kms_key_arn (when KMS encryption is enabled)

Cross-Account Access Policies

Granted Permissions:

  • ecr:BatchCheckLayerAvailability - Check if image layers exist
  • ecr:BatchGetImage - Pull container images
  • ecr:BatchGetRepositoryScanningConfiguration - Access scan settings
  • ecr:Describe* - Access repository metadata
  • ecr:Get* - Read repository configurations
  • ecr:List* - List repository contents

KMS Permissions (when enabled):

  • kms:Decrypt - Decrypt image layers
  • kms:DescribeKey - Access key metadata
  • Full encrypt/decrypt grants through CDK methods

Security Features

Encryption Options:

  • AWS Managed: Default AES-256 encryption (no additional cost)
  • Customer Managed: KMS keys with rotation and audit trails
  • Cross-Account: KMS permissions automatically configured for sharing

Access Control:

  • Resource Policies: Repository-level access control
  • IAM Integration: Seamless integration with existing IAM roles
  • Principle of Least Privilege: Read-only cross-account access by default

Compliance Features:

  • Audit Trails: All access logged through CloudTrail
  • Vulnerability Scanning: CVE detection on image push
  • Tag-Based Security: Organizational tags for compliance tracking

Notes

  • The set_usage method from the abstract class should not be used in this builder.
  • The repository_name parameter of the set_ecr_repo_base_name method should be extracted from the cdk.json config key.
  • KMS key rotation is disabled by default for cost optimization
  • Cross-account sharing grants read-only access (no push permissions)