Migrating from cloud-native registries

This is the field guide for moving from one of the three big-cloud artifact-registry products — AWS CodeArtifact, Azure Artifacts, and Google Artifact Registry — to OrbitalReg. The three share enough operational characteristics that a single playbook covers their common ground; source-specific sections below cover the differences.

Why one combined guide?

All three are SaaS-only with no on-prem option. Migration strategies converge around lazy proxy because you don't control the source's lifecycle, rate-limits, or maintenance windows. The auth mechanisms differ (STS vs PAT vs service-account), but the cutover shape is identical. Reading this once gives you the migration model for any of the three.

What stays the same

For your developers, almost nothing visible changes:

• Push and pull commands stay format-native (mvn deploy, npm publish, docker push, etc.)
• CI pipeline scripts only need their registry URL updated
• Existing artifact identifiers (group:artifact:version, image tags) carry through unchanged
• Cloud-IAM-based federated auth keeps working — OrbitalReg's OIDC trust policies accept tokens minted by AWS STS / Azure AD / Google Workload Identity natively

What changes

Concept	Cloud-native registries	OrbitalReg
Hosting model	SaaS, vendor-controlled	Self-hosted, you control
Pricing model	Usage-metered (storage + bandwidth + requests)	Per-deployment annual flat-rate
Egress cost	Per-GB bandwidth charges out of the cloud	Zero — runs on your infrastructure
Sovereignty	Your artifacts sit in the vendor's account	Your artifacts sit in your S3 bucket
Air-gapped operation	Not possible (SaaS)	Default-on
Format coverage	Vendor-specific subset (~5-7 formats per vendor)	40+ formats, all in one binary
Cross-region	Vendor-specific replication products	Built-in geo-sync feature
Audit	CloudTrail / Activity Log / Cloud Audit Logs	Structured JSON audit log, SIEM-ready

Why these three together

All three cloud-native registries share three operational characteristics that drive a common migration shape:

1. You don't control the source's lifecycle. AWS, Microsoft, and Google decide when to upgrade, deprecate, change rate-limits, or shut down regions. Big-bang and blue-green strategies become risky because cutover-window timing is partly out of your hands.

2. Network egress is a metered cost. Bulk-exporting 14 TB out of AWS CodeArtifact triggers EC2-to-Internet egress charges (roughly $0.09/GB → $1,260 for that single migration window). A multi-week lazy-proxy approach amortises this against actual pull traffic.

3. Authentication is federated. All three integrate tightly with their cloud's IAM. OrbitalReg's OIDC-trust-policy story translates naturally — your CI workflows that mint cloud-IAM-tokens today can continue minting them, OrbitalReg accepts them via trust policies.

For all three, the lazy-proxy strategy is the recommended migration path. Big-bang is feasible for tiny registries (under 100 GB), but the metered-egress cost and the lack of source-side control make it the wrong default.

Pre-migration audit

The first step is always inventory. The orbital migrate plan command walks the source registry, catalogues what it finds, and writes a plan file the apply step consumes.

The CLI surface is identical across the three sources; only the --source flag and the credential mechanism differ:

# AWS CodeArtifact
orbital migrate plan \
  --source aws-codeartifact \
  --domain my-domain \
  --aws-account-id 123456789012 \
  --aws-region eu-central-1 \
  --output migration-plan.json
# (Authentication via the AWS credential chain — env, profile, instance role)

# Azure Artifacts
orbital migrate plan \
  --source azure \
  --organization https://dev.azure.com/my-org \
  --token "$AZURE_DEVOPS_PAT" \
  --output migration-plan.json

# Google Artifact Registry
orbital migrate plan \
  --source gar \
  --project my-gcp-project \
  --service-account-key /path/to/sa-key.json \
  --output migration-plan.json
# (or via Workload Identity, ADC, OIDC — see GCP source section)

What gets discovered (across all three):

• Repositories / Feeds / Repositories — the source's first-class artifact-container concept. Names, formats, regions, upstream-source configurations.
• Artifacts — counted per repository, sha256 sampled.
• Permissions / IAM bindings — flagged for translation to OrbitalReg roles + scoped tokens.
• Cross-region or cross-account configurations — flagged separately; these often need manual reconciliation during cutover.

Format coverage

Format	AWS CodeArtifact	Azure Artifacts	Google Artifact Registry	OrbitalReg
Maven	✓	✓	✓	✓
npm	✓	✓	✓	✓
NuGet	✓	✓	generic	✓
PyPI / Python	✓	✓	✓	✓
Generic / Universal	✓	✓	via apt/yum	✓
Docker	✗ (use ECR)	✗ (use ACR)	✓	✓
Helm	✗	✗	✓ via OCI	✓
Apt	✗	✗	✓	✓
Yum	✗	✗	✓	✓
Cargo	✗	✗	✗	✓
RubyGems	✗	✗	✗	✓
Go modules	✗	✗	✗	✓
25+ more formats	✗	✗	✗	✓

OrbitalReg's biggest practical advantage in cloud-registry migrations is format-consolidation: your CI today probably uses CodeArtifact for Maven/npm/Python, ECR or ACR for Docker, and a third tool for whatever isn't covered. After migration, all formats live behind a single URL in OrbitalReg.

Pick your strategy

For all three cloud-native sources, the recommendation is:

Your situation	Recommended strategy
Registry under 100 GB, can take 4 h downtime	Big bang (rare; egress cost still applies)
Production-critical, registry under 5 TB	Lazy proxy
Huge registry (over 10 TB)	Lazy proxy (basically required)
Cross-region or cross-account source	Lazy proxy (DNS flip per region)
Cost-conscious migration	Lazy proxy (egress amortised over weeks)

Blue-green parallel-run is technically possible but rarely worth the complexity vs lazy-proxy when the source is SaaS — you can't easily control the source's caching, rate-limits, or maintenance windows during the parallel-run period.

Lazy proxy cutover (canonical for cloud sources)

Here is the canonical lazy-proxy sequence that works across all three cloud sources.

Phase 1: Install OrbitalReg (Day -14)

Install OrbitalReg in the same cloud (or any cloud) where most of your developer egress lands. Co-locating with your CI runners minimises egress cost during the cache-fill phase.

helm repo add orbitalreg https://charts.orbitalreg.com
helm install orbitalreg orbitalreg/orbitalreg \
  --namespace orbitalreg --create-namespace \
  --values your-values.yaml

Phase 2: Configure remote-proxy mode (Day -14)

Run the migration plan with the lazy-proxy strategy. The plan registers OrbitalReg repositories as remote-mode pointing at the source. No bulk export happens at this step — pulls fill the cache on demand.

orbital migrate plan --source <aws-codeartifact|azure|gar> \
  ... --strategy lazy-proxy \
  --output migration-plan.json

orbital migrate apply --plan migration-plan.json

Phase 3: Soak on dev / staging (Day -14 to Day -7)

Switch dev and staging environments to point at OrbitalReg. Monitor:

• Cache-hit rate per repository (target: 60% within 7 days)
• p99 pull latency vs cloud baseline (acceptable: same or better — intra-cloud OrbitalReg often beats cross-cloud SaaS pulls)
• Error rate (acceptable: under 0.1%)
• Egress cost from source — this is what you're optimising against; the amortised egress over the soak period replaces what would have been a single bulk-export bill

Phase 4: Production DNS flip (Day -7)

# Update DNS — registry.example.com → OrbitalReg ingress

Pulls now flow through OrbitalReg in production. Writes still target the source registry directly.

Phase 5: Switch CI to push to OrbitalReg (Day 0)

Update CI to push to OrbitalReg directly. New artifacts now land in OrbitalReg first; the proxy fills the cache for old artifacts on demand.

Phase 6: Convert remote-mode to local-mode (Day +14 to +60)

Once cache-hit rates exceed 95% per repository, convert that repository from remote-mode to local-mode.

orbital migrate finalize --plan migration-plan.json

For 14 TB / 30M-artifact deployments across all three sources combined, expect 30-60 days of elapsed migration time. Active operator hours: ~10-20 spread across that period.

Phase 7: Decommission source registry (Day +60)

After 30 days of stable local-mode operation:

• AWS CodeArtifact — delete domains via aws codeartifact delete-domain
• Azure Artifacts — delete feeds via Azure DevOps UI or REST API
• Google Artifact Registry — delete repositories via gcloud artifacts repositories delete

In all three cases, the source-side data is deleted; OrbitalReg's local-mode now holds the canonical copies.

AWS CodeArtifact specifics

Authentication

AWS CodeArtifact uses STS-assumed-role authentication. The orbital migrate CLI picks up the AWS credential chain in the standard AWS-SDK order:

1. Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN)
2. Profile from ~/.aws/credentials (use --aws-profile flag)
3. EC2 instance metadata service / ECS task role / Pod Identity

For cross-account migration, configure an STS assume-role chain with read-only CodeArtifact permissions:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "codeartifact:Describe*",
      "codeartifact:Get*",
      "codeartifact:List*",
      "codeartifact:ReadFromRepository"
    ],
    "Resource": "*"
  }]
}

Concept mapping

AWS CodeArtifact	OrbitalReg
Domain	OrbitalReg project (top-level container)
Repository	OrbitalReg repo
External Connection (e.g. to public npm)	OrbitalReg virtual repo with upstream-source
Upstream Repository (CodeArtifact-to-CodeArtifact)	OrbitalReg virtual repo
Domain encryption key	(no equivalent — OrbitalReg uses S3 SSE)
Resource policy	Mapped to OrbitalReg permission scopes per project/repo

Egress-cost considerations

CodeArtifact bandwidth out to the public internet is metered at standard EC2 outbound rates (~$0.09/GB in eu-central-1). For 14 TB of artifacts during a single bulk export, that's ~$1,260 in egress alone. The lazy-proxy strategy spreads this over your normal pull traffic, which is typically 5-10% of total artifact volume per month.

VPC endpoints for CodeArtifact (com.amazonaws.region.codeartifact.api and com.amazonaws.region.codeartifact.repositories) reduce in-region inter-VPC traffic to zero cost; if OrbitalReg runs in the same AWS region as the CodeArtifact domain, configure the VPC endpoint and the migration cost drops to near-zero.

What's not migrated

• AWS-native package-policy mechanisms (CodeArtifact resource policies) translate to OrbitalReg permissions but require a manual review pass.
• ECR images are NOT covered by this playbook — ECR is a separate AWS service. For ECR migration, use OrbitalReg's Docker adapter and point it at the ECR endpoint as a remote-proxy.

Azure Artifacts specifics

Authentication

Azure Artifacts uses Azure DevOps Personal Access Tokens (PAT) for API access. Create a PAT with Packaging (read) scope at minimum; add Packaging (read & write) if you want re-push verification during the migration.

orbital migrate plan \
  --source azure \
  --organization https://dev.azure.com/my-org \
  --project my-project \
  --token "$AZURE_DEVOPS_PAT"

For service-principal-based auth (preferred for production migration), use Azure DevOps service connections with workload-identity federation.

Concept mapping

Azure Artifacts	OrbitalReg
Organization	(top-level scope, not directly mapped)
Project	OrbitalReg project
Feed	OrbitalReg repo (or set of repos if multi-format feed)
Universal Package	OrbitalReg generic format
Upstream Sources (e.g. nuget.org passthrough)	OrbitalReg virtual repo with upstream
Permissions: Project-scoped	OrbitalReg project-membership
Permissions: Organization-scoped	OrbitalReg system-admin role

Universal Packages

Azure Artifacts has a unique format called "Universal Packages" — a generic blob store with versioning. OrbitalReg's generic adapter covers the same use case with sha256-verified pass-through. The migration translator maps Universal Packages 1:1 to generic-format repositories.

What's not migrated

• Azure DevOps Pipelines integration — out of scope, OrbitalReg is registry-only. Pipeline definitions stay on Azure DevOps.
• ACR (Azure Container Registry) is NOT covered by this playbook; use OrbitalReg's Docker adapter as a remote-proxy to ACR.

Google Artifact Registry specifics

Authentication

Google Artifact Registry supports three auth mechanisms; OrbitalReg accepts all three:

1. Service-account key (JSON) — simplest for migration

   orbital migrate plan \
     --source gar \
     --project my-gcp-project \
     --service-account-key /path/to/sa-key.json

2. Application Default Credentials (ADC) — preferred for production

   gcloud auth application-default login
   orbital migrate plan --source gar --project my-gcp-project

3. Workload Identity Federation (OIDC) — preferred for CI runners

   # CI runners with workload-identity-federation already authenticated;
   # orbital picks up the federated token automatically
   orbital migrate plan --source gar --project my-gcp-project

The minimum IAM role for the migration is roles/artifactregistry.reader. For verification with re-push, add roles/artifactregistry.writer temporarily.

Concept mapping

Google Artifact Registry	OrbitalReg
GCP Project	OrbitalReg project (project-per-project mapping)
Repository	OrbitalReg repo
Region (e.g. europe-west3)	Preserved as a label on the OrbitalReg repo
Format (Docker / Maven / npm / Python / Apt / Yum / Kubeflow)	Direct format-adapter mapping
Remote / Virtual repository	OrbitalReg remote-mode / virtual-mode repo
IAM binding (roles/artifactregistry.reader etc.)	OrbitalReg role with scoped tokens
gcr.io legacy registries	Migrated via the Docker adapter

Multi-region considerations

GAR repositories are region-scoped. A typical enterprise setup has the same logical repository in multiple regions (e.g. docker-prod in europe-west3, us-central1, and asia-east1). OrbitalReg's geo-sync feature replaces this — one logical repository, geographically replicated, with consistent permissions and a single audit log.

The migration translator preserves region information as labels during the lazy-proxy phase. After all regions are migrated, geo-sync can be configured to provide the same multi-region availability with a unified surface.

gcr.io legacy registries

The deprecated gcr.io Container Registry is fully supported as a migration source via the Docker adapter:

orbital migrate plan \
  --source gar \
  --include-gcr-legacy \
  --project my-gcp-project

Both gcr.io repositories and the newer GAR-hosted Docker repositories end up as OrbitalReg Docker repos. The same underlying adapter handles both.

What's not migrated

• Cloud Build / Cloud Run integration — out of scope, OrbitalReg is registry-only.
• Container Analysis (vulnerability scanning) — replaced by OrbitalReg's built-in Trivy + Grype scanning.
• Binary Authorization — Google's policy-based deployment-time check has no direct equivalent; OrbitalReg's pull-gate policies cover the registry-side enforcement.

Verification

Verification is what tells you it's safe to cut over. Same CLI across all three sources:

orbital migrate verify --sample 5000

What gets verified:

1. Sha256 sample comparison — pulls a random sample from OrbitalReg, compares against the source.
2. Metadata round-trip — for each format, verifies that format-specific metadata round-trips correctly.
3. Synthetic pull test — performs a real pull through the format-native client.
4. Cloud-IAM auth handshake — exercises the trust policy with a synthetic cloud-IAM token (STS / Azure AD / Workload Identity); reports any subject-pattern divergence.
5. Permission spot-check — re-runs each translated permission against a synthetic test user.

A clean run looks like this:

✓ 5000/5000 sha256 matches
✓ All metadata round-trips correctly (5 formats checked)
✓ Pull-test from random sample succeeded
✓ Cloud-IAM handshake: 23/23 trust policies authenticate correctly
✓ Permission spot-check: 47/47 IAM bindings translate correctly
→ Safe to flip DNS

Rollback

The lazy-proxy strategy makes rollback trivial: flip DNS back to the cloud source. The cloud source still holds canonical data during the remote-mode period — nothing was destructively migrated.

For the rare big-bang case: rollback requires re-importing from a local snapshot if the source was deleted prematurely. This is why big-bang is not recommended for cloud sources — you don't have a snapshot of the SaaS source on hand.

FAQ

Can we migrate without leaving the source's cloud?

Yes. OrbitalReg can run inside the same cloud as the source. For AWS-to-AWS migration, install OrbitalReg in the same VPC as your existing CodeArtifact domain — the migration becomes a same-cloud data move, no internet egress.

Will OrbitalReg work with cloud-IAM-federated CI?

Yes. OrbitalReg's OIDC trust policies accept tokens minted by AWS STS, Azure AD, Google Workload Identity, and any standard OIDC issuer. The migration translator emits trust policies for each existing CI workflow, mapped from the source registry's IAM bindings.

What about cross-cloud authentication?

OrbitalReg sits cloud-neutral by default. A CI runner in AWS can publish to an OrbitalReg deployment in GCP, authenticated via OIDC trust. The trust policy whitelists which AWS-IAM roles can publish to which OrbitalReg projects — the cross-cloud authentication path that today often requires brokered intermediate accounts becomes a one-line trust policy.

How long does a full cloud-source migration take?

Source	Strategy	Elapsed time
AWS CodeArtifact under 1 TB	Lazy proxy	14-21 days
AWS CodeArtifact 1-10 TB	Lazy proxy	21-45 days
Azure Artifacts under 1 TB	Lazy proxy	14-21 days
Azure Artifacts 1-10 TB	Lazy proxy	21-45 days
GAR under 1 TB	Lazy proxy	14-21 days
GAR 1-10 TB	Lazy proxy	21-45 days
All three combined, 14 TB total	Lazy proxy	30-60 days

Active operator hours: ~10-20 spread across the elapsed window. Most of the time is wait-for-cache-to-fill.

What's the cost difference?

Cloud-native registries charge usage-based: storage per GB-month, bandwidth out, and per-request fees. A 14 TB deployment with typical pull patterns runs $400-800 per month for AWS CodeArtifact alone, similar ranges for Azure Artifacts and GAR.

OrbitalReg is licensed per-deployment, annual flat-rate. For mid-sized deployments, the break-even point against any single cloud registry is typically 6-12 months. Against multiple cloud registries combined (which is the typical pre-migration state), break-even is closer to 3-6 months.

See the pricing overview — security features, multi-format support, and air-gapped operation are all included in every tier.

Can we keep the cloud registry as a hot fallback?

Yes — OrbitalReg can stay configured as a remote-proxy in front of the cloud source indefinitely. Some teams prefer that posture for the first 12 months as a zero-risk fallback. The metered cost on the source side becomes proportional to actual cache-miss traffic, which is typically 1-2% of total volume after the cache is warm.

Need a working session?

Email info@orbitalreg.com with subject "Cloud registry migration support" and we'll book a 60-minute working session. Include which cloud source you're moving from and roughly how big the registry is — we'll tailor the working session to your specific cutover plan.