Behavior & Limits
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 (as images are built and deployed) creates repositories within the registry:
| Platform | What creating a repository 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 carry the specified permission level (pull or push-pull) and expire after the requested TTL — they cannot be used after expiry. On AWS they are scoped to one repository; on GCP they reach the whole GAR repository, since every name is an image path inside it.
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.
No per-name grants on GCP. GAR has no IAM below a repository, so a grant on one name would reach every name's images. Alien refuses it with OPERATION_NOT_SUPPORTED instead of widening it; only the registry's own pull and push service accounts can be named. To give tenants separate access, use a separate artifact registry per tenant.
Repository Naming
When a repository named my-app is created, the name is transformed per platform to fit cloud naming constraints. A project ID like prj_abc123 works on every provider. On GCP the name must already be a valid image path; other names fail with INVALID_INPUT instead of being rewritten.
| 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}. Each /-separated part uses lowercase letters, numbers, dots, underscores, and hyphens, and starts and ends with a letter or number. |
| 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). |
Each repository is addressed by its routable name — the full, platform-specific path used for credential generation and cross-account grants.
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. On GCP a grant covers the whole repository; per-name grants to other accounts are refused. |
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. Names are not sanitized: an uppercase name, or a part that starts or ends with punctuation, fails with
INVALID_INPUT. 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 GAR repository, so a grant covers every name in it. A grant or revoke on one name to anyone other than the registry's own pull and push service accounts fails with
OPERATION_NOT_SUPPORTED(not retryable): "per-repository access grants aren't supported on GCP; use a separate artifact-registry binding per tenant". - 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 Alien.
- 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 model. 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, so Alien keeps cross-account grants platform-specific (aws vs gcp) rather than forcing a lowest-common-denominator abstraction.
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.