Migrate from Amazon ECR to Harbor

Pull-based replication is the mechanism that keeps Harbor filled with images that still originate in ECR. A replication rule in Harbor pulls from an AWS ECR endpoint into a local Harbor project, so the Harbor copy stays current while Kubernetes clusters and pipelines keep working against ECR. Rules can filter by repository name, tag, label and resource type, which lets you start with one team or one application instead of the whole account.

• Trigger choice: Rules can run manually, on a cron schedule, or on push and retag events. Scheduled runs suit the early phase, while event triggers help once new images are flowing.
• Bandwidth limit: Each task can carry an optional bandwidth limit, which keeps large initial copies from saturating links that production traffic uses.
• Scope by filter: Start with a narrow repository filter, verify digests on the Harbor side, then widen the filter in steps.
• Credentials: Give the replication endpoint an IAM identity limited to pulling from the repositories in scope.
• Initial backfill: Plan a first full run before enabling event triggers, so older tags exist in Harbor before anything depends on them.

Confirm with your Harbor version's documentation how the replication endpoint handles ECR authorization tokens, since token refresh behavior determines whether long-running rules need attention.

A proxy cache project is a different tool with a narrower job. It is useful when a workload needs images from ECR during the window before replication has caught up, or when ECR becomes unreachable from a site. Harbor can cache from AWS ECR as an upstream, and cached content is served from Harbor's own storage on later pulls.

• Read-only for pushes: Proxy cache projects do not accept pushes, so they cannot become a place where teams publish new images.
• Fallback behavior: If the upstream is unreachable, Harbor serves the cached copy, which helps sites that lose their route to ECR.
• Default retention: Cached content gets a default 7-day retention policy, so set the policy explicitly if a longer read window is needed.
• Not a replica: A proxy cache only holds images that were pulled through it. Images nobody has requested will not be present, so it does not replace replication for a full copy.
• Separate project: Keep cache projects apart from the projects that hold replicated images, so their policies and access rules stay distinct.

Confirm how your ECR authentication is configured for the proxy cache upstream, and test a pull from a node in each site before depending on it.

Moving push targets is the step that changes where new images land. Doing it in stages means each pipeline or team moves once it has proven that builds push to Harbor, that deployments pull from the right place, and that rollback is possible. Because replication copies images between registries, a pipeline that still pushes to ECR keeps Harbor populated, which lets you move teams one at a time without a single cutover date.

• Dual push first: Some teams push to both registries for a period, so Harbor receives new images while ECR remains the fallback.
• Project naming: Harbor projects map to ECR repository namespaces, so write the mapping down before pipelines change.
• Pipeline by pipeline: Change one pipeline's push target, run a build, and confirm the image digest appears in Harbor before the next pipeline moves.
• Robot accounts: Create Harbor robot accounts with push permission only for the projects each pipeline uses.
• Rollback path: Keep the old ECR push target in a variable or configuration key so a pipeline can be reverted quickly.

Check that your CI system's registry credentials, image tags and build caches all point to the new target before retiring the old one.

A single account with a handful of repositories is the simplest starting point. Most of the work is in the replication rule and the cutover of image references, and the repository count keeps the filter list short. Harbor pulls from the ECR endpoint with a pull-based replication rule, so you can set the rule up, run it once manually and compare results before you touch any workload.

• Filter narrowly first: Start with one or two repository name filters and a tag filter, then widen the rule once the copies match.
• Use short-lived ECR credentials: Ask who will rotate the token used by the replication endpoint, because ECR authorization tokens expire and need a refresh mechanism.
• Cut over by workload: Update image references one deployment at a time, so a bad copy affects a single service.
• Recreate lifecycle rules: ECR lifecycle policies do not move with the images, so write the equivalent retention rules in Harbor's garbage collection and tag retention settings.
• Keep ECR running: Leave the source repositories in place until every consumer has pulled from Harbor at least once.

Confirm the replication endpoint configuration and token refresh method with your own AWS administrator before scheduling the first run.

Organizations with several AWS accounts or regional ECR repositories have more endpoints to replicate from, and often duplicate images across regions. The main question is whether one Harbor instance should collect everything, or whether each account's images should be consolidated by naming convention. Each source account needs its own endpoint and credential, and each region is a separate source.

• Map sources to projects: Create one Harbor project per account or team so access control follows your existing account boundaries.
• Deduplicate before copying: Identify images that exist in several regions and replicate only the canonical copy where possible.
• Plan cross-account access: Confirm which IAM roles the replication endpoints assume and that each one can only read the repositories it needs.
• Schedule staggered runs: Use cron schedules or manual triggers, and apply bandwidth limits so replication does not compete with production traffic.
• Audit the endpoint inventory: Record every ECR source, its owner and its credential so that the migration does not leave an orphaned pull path.

Ask your AWS platform team to produce a complete list of accounts, regions and repositories before you write any replication rule.

Clusters that run on premises and pull from ECR depend on outbound access to AWS, which many data centers restrict or meter. Moving those clusters to a local Harbor removes the outbound pull path for routine deployments, but the replication job still needs to reach ECR once to copy content. The network design, DNS and TLS certificates for the new registry hostname are the main effort on this path, and they are usually bigger than the replication work itself.

• Place Harbor close to the clusters: Run it in the same data center or network segment so image pulls stay local.
• Plan the hostname and certificates: Clusters must trust the Harbor certificate, so distribute the certificate authority to every node before cutover.
• Stage the pull path change: Point one cluster at Harbor, verify pulls and node behavior, then move the rest.
• Account for the replication window: Choose a schedule that keeps the initial copy within your egress allowance and bandwidth budget.
• Check Helm chart references: Charts pushed as OCI artifacts need the same hostname change as container images.

Verify the Harbor install prerequisites and high availability options against your own storage and database standards before you commit to a layout.

In air-gapped environments, the replication job cannot reach ECR at all, so the copy happens outside the network. Skopeo can sync images from an external registry to an internal registry or to a local directory, which then moves across the boundary by approved media. The copy step is a transfer process that your security team must approve, record and verify, and it adds effort that connected estates do not have.

• Export to a local directory: Use Skopeo on a connected host to sync the selected images into a directory that can be transferred.
• Import on the inside: Push the transferred content into the internal Harbor with Skopeo, which needs no special privileges.
• Verify digests on both sides: Compare image digests before and after transfer so the internal copy matches the source.
• Define the transfer procedure: Document who approves each batch, which media is used and how the transfer is logged.
• Plan for updates: Each security patch becomes another transfer, so agree the cadence with the owners of the cross-boundary process.

Confirm the transfer approval path and media rules with your security and compliance teams before the first batch leaves the connected side.