Behavior & Limits

Guarantees

Temporary Credentials. Generated credentials are scoped to a single repository with the specified permission level (pull or push-pull). Credentials expire after the requested TTL — they cannot be used after expiry.

Cross-Account Isolation. Cross-account access grants are scoped to specific accounts, service accounts, and service types. Granting pull access to one account does not affect other accounts.

Limits

Platform Notes

AWS (ECR)

• Credential generation uses GetAuthorizationToken — returns a base64-encoded username:password pair valid for 12 hours.
• Cross-account access is implemented via ECR repository policies (IAM-style JSON policies). Grants are scoped to specific AWS account IDs and IAM role ARNs.
• Replication: Images can be automatically replicated to additional regions via the replicationRegions stack option. This ensures Lambda functions in any region can pull images from a nearby ECR endpoint.
• Image pull for Lambda functions in other accounts requires explicit repository policy + Lambda execution role permissions.
• Blob download URLs: ECR supports pre-signed S3 URLs for direct blob downloads (generateBlobDownloadUrl).
• Rate limits: Pull rates are generous and significantly higher than Docker Hub. No per-repository throttling for authenticated requests.

GCP (Artifact Registry)

• Credential generation uses service account impersonation — generates a short-lived access token.
• Cross-account access is implemented via IAM bindings on the repository. Grants are scoped to GCP project numbers and service account emails.
• No pre-signed URLs — image layers are fetched via the OCI distribution API with bearer token authentication.
• Multi-format support: Artifact Registry supports Docker images, Maven, npm, Python packages, and more — though Alien only uses Docker image support.
• Max artifact size: 5 TB.

Azure (ACR)

• Credential generation uses scope maps and tokens — creates a scoped token with specific repository permissions.
• cleanupCredentials() is required on Azure to delete the scope map after use. Other platforms do not require cleanup.
• No cross-account access through Alien. Azure ACR supports cross-subscription access via Azure RBAC, but this is not exposed through the Alien binding.
• Tier-based limits:
  • Basic: 10 GB storage, 10 write ops/min, 1,000 read ops/min
  • Standard: 100 GB storage, 100 write ops/min, 3,000 read ops/min
  • Premium: 500 GB storage, 2,000 write ops/min, 10,000 read ops/min
• Admin credentials are used during initial setup.

Local

• Runs an in-process OCI-compatible registry.
• Basic auth support for credential generation.
• No cross-account access (not applicable).
• Suitable for development and testing.

Design Decisions

No unified cross-account API. AWS uses IAM policies with account IDs and role ARNs. GCP uses IAM bindings with project numbers and service account emails. These are fundamentally different models that can't be cleanly unified. The CrossAccountAccess type uses a discriminated union (type: "aws" | "gcp") to keep the API honest about platform differences.

Explicit credential cleanup on Azure. ACR scope maps are persistent resources that must be deleted. Rather than silently leaking resources, Alien requires explicit cleanupCredentials() calls. This is a platform quirk that we document rather than hide.

Replication is AWS-only. ECR supports native cross-region replication. GCP Artifact Registry supports multi-region repositories but through different mechanisms. Rather than building a lowest-common-denominator abstraction, replication is exposed as an AWS-specific option.