Behavior & Limits
Guarantees, limits, and platform-specific behavior for Alien Artifact Registry.
What Gets Provisioned vs What Happens at Runtime
An ArtifactRegistry has two phases:
Provisioning (when your stack deploys) creates the registry itself — the container that holds repositories:
| Platform | What provisioning creates |
|---|---|
| AWS | IAM roles for pull/push access. ECR itself is implicit — no discrete resource to create. |
| GCP | A GAR repository (the container), plus service accounts for pull/push access. |
| Azure | An ACR resource (the container), which holds repositories created at runtime. |
| Local | Connects to the running local container image registry. |
Runtime (when your application calls createRepository) creates repositories within the registry:
| Platform | What createRepository("my-app") does |
|---|---|
| AWS | Creates an ECR repository named {prefix}-my-app via the CreateRepository API. |
| GCP | No-op — GAR creates image paths implicitly on first push. Returns the routable name. |
| Azure | Creates a scope map for access control. The image repository is created implicitly on first push. |
| Local | Pushes a marker manifest to create the repository in the local container image registry. |
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.
Repository Naming
When you call createRepository("my-app"), the name is transformed per platform to fit cloud naming constraints. You can pass any reasonable string (e.g., a project ID like prj_abc123) and each provider adapts it.
| Platform | How the repository name is constructed |
|---|---|
| AWS (ECR) | Prefixed: {registry_prefix}-{name} (e.g., alien-artifacts-my-app). Underscores allowed. |
| GCP (GAR) | Nested under the GAR repository: {project}/{gar_repo}/{name}. Image paths allow lowercase letters, numbers, dots, underscores, and hyphens. |
| Azure (ACR) | Used directly: {name}. Hash-based fallback if scope map name exceeds Azure constraints. |
| Local | Namespaced: {binding_name}/{name} (e.g., artifacts/my-app). |
The returned RepositoryResponse.name is the routable name — the full, platform-specific path used for subsequent operations like generateCredentials and addCrossAccountAccess. Always use this returned name, not the input name.
Limits
| Limit | Value | Notes |
|---|---|---|
| Images per repository | 100,000 (ECR) | GCP and Azure have higher or no documented limits. |
| Credential TTL | Platform-dependent | ECR: 12 hours max. ACR: varies by token type. |
| Cross-account access | AWS and GCP only | Azure does not support cross-account access through Alien. |
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
replicationRegionsstack option. This ensures Lambda workers in any region can pull images from a nearby ECR endpoint. - Image pull for Lambda workers in other accounts requires explicit repository policy + Lambda execution role permissions.
- Rate limits: Pull rates are generous and significantly higher than Docker Hub. No per-repository throttling for authenticated requests.
GCP (Artifact Registry)
- Repository creation is a no-op — GAR creates image paths implicitly on first push. The GAR repository itself (the container) is created at provisioning time by alien-infra.
- Repository naming: image paths within a GAR repository allow lowercase letters, numbers, dots, underscores, and hyphens. No sanitization needed — underscores are valid.
- Credential generation uses service account impersonation — generates a short-lived access token. Max TTL is 1 hour (3,600 seconds) — higher values are silently capped.
- 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 through the registry 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 a stateless AAD OAuth2 token exchange (AAD token → refresh token → scoped access token). Credentials are short-lived (~5 minutes, controlled by Azure). No persistent resources are created.
- 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 container image 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.
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.