Behavior & Limits
Guarantees
Keeps running. A container keeps the configured number of replicas running until the resource is updated, deleted, or marked failed.
Direct execution. The container runs your image's entrypoint (or .command(...)) directly — there is no runtime wrapper process. Bindings run in-process via @alienplatform/bindings, and commands are received by an app-owned receiver from @alienplatform/commands.
Internal service name. Every container has an internal DNS name in its deployment environment. Linked services can use the container binding instead of hard-coding cloud-specific service names.
Single public backend port. A container can declare several named public endpoints, but they must all route to the same backend port. This keeps load-balancer ownership deterministic across AWS, GCP, Azure, Kubernetes, and Local.
Stable stateful identity. Stateful replicas get stable ordinals (api-0, api-1, …). Each ordinal keeps its persistent volume: the volume survives replica restarts and replacement, and the replica is placed where its volume lives.
Immutable placement shape. Resource ID, cluster, stateful mode, ports, and capacity pool are immutable for an existing container. Changing those fields requires replacing the resource.
Volume backups. On AWS, GCP, and Azure, every persistent volume is snapshotted on a schedule. See Volume backups.
Cloud scheduling. On AWS, GCP, and Azure, Alien tracks replica placement and health for containers. The cloud controllers manage surrounding provider resources such as load balancers and persistent disks.
Volume backups
Each replica's persistent volume is snapshotted on a schedule. The default is one snapshot every 24 hours, each kept for 7 days. Set backups on .persistentStorage() to change it, or backups: false to turn it off.
Turning backups off keeps the snapshots already taken. They are removed when the container is deleted.
Existing installations. Backups need management permissions that setup installs. An installation set up before volume backups existed keeps running without them, and the container's outputs show volumeBackups.state: setupRequired. Update the installation's setup (a CloudFormation stack update with the new template, or terraform apply with the new module) and the schedule is applied within an hour. Until then, deleting the container deletes its volumes without a final snapshot, as before.
The cloud's own snapshot scheduler takes the snapshots. They keep being taken when the deployment can't reach Alien.
Snapshots are crash-consistent. A restored volume looks like the disk after a sudden power loss. Databases that survive a power loss, such as Postgres, Redis with an append-only file, and ClickHouse, recover from it on start.
Deleting a container. Before the volumes are deleted, Alien takes one final snapshot of each and keeps it until you delete it. Scheduled snapshots of the deleted volumes are removed. With backups: false, the volumes are deleted without a final snapshot.
Restoring. A restore replaces one replica's volume with a new volume made from a snapshot. The snapshot must belong to the same deployment and be no larger than the configured volume size:
alien deployments restore-volume <deployment> --resource db --ordinal 0 --snapshot <snapshot-id>Alien stops that replica, creates the new volume in the same zone, and starts the replica on it. Before deleting the replaced volume, Alien snapshots it, so a restore can be undone. Other replicas keep running.
If a restore fails, the container shows the error. Retry the deployment to try again, or cancel the restore request. A restore cancelled after its replica's volume was already swapped still finishes, and is reported as completed.
The container's outputs list each volume with its latest snapshot and its latest restore.
| Platform | Scheduler | Snapshots |
|---|---|---|
| AWS | Amazon Data Lifecycle Manager | EBS snapshots |
| GCP | Compute Engine snapshot schedule | Persistent Disk snapshots |
| Azure | Azure Disk Backup | Incremental Managed Disk snapshots |
| Kubernetes | Not managed by Alien | Use the cluster's backup tooling, such as VolumeSnapshots or Velero |
Snapshots stay in the customer's cloud account, in the same region as the volume. Snapshot storage is billed by the cloud provider for the data that changed between snapshots.
Limits
| Limit | Value | Notes |
|---|---|---|
| Minimum ports | 1 | A container with no ports is invalid. |
| Public backend ports | 1 | All public endpoints on a container must route to the same backend port. Additional ports are internal-only. |
| Apex endpoints | 1 | Only one endpoint per resource can use hostLabel: "@". |
| Health check timeout default | 1 second | Configurable with timeoutSeconds. |
| Health check failure threshold default | 3 failures | Configurable with failureThreshold. |
Persistent storage mount from .persistentStorage(size) | /data | Override with the mountPath option. |
Platform Notes
AWS
- Cloud containers run on EC2-backed machines in the customer's AWS account.
- Public containers use load-balancing resources for the exposed port.
- Stateful containers can create EBS volumes for persistent storage.
- Alien tracks container scheduling and replica state.
GCP
- Cloud containers run on Compute Engine-backed machines in the customer's GCP project.
- Public containers use Google Cloud load-balancing resources.
- Stateful containers can create Persistent Disks.
- Alien tracks container scheduling and replica state.
Azure
- Cloud containers run on Azure Virtual Machines in the customer's subscription.
- Public containers use Azure load-balancing resources.
- Stateful containers can create Managed Disks.
- Alien tracks container scheduling and replica state.
Kubernetes / On-Prem
- Stateless containers map to Kubernetes Deployments.
- Stateful containers map to StatefulSets.
- Persistent storage maps to PersistentVolumeClaim templates.
- The build pipeline converts source-based Containers to runnable images before the Kubernetes controller sees them.
Local
- Containers run through the local container runtime.
- Linked filesystem-backed resources are bind-mounted into the container when applicable.
- The build pipeline converts source-based Containers to runnable images before the local controller sees them.
Design Decisions
One public backend port per container. The current controllers create one load-balancer path per container; named endpoints share it. Keeping this limit universal prevents cloud-specific behavior from leaking into the resource model.
Cluster and ports are immutable. Changing cluster placement or public ports changes networking and load-balancer shape. Alien treats those as replacement-level changes instead of in-place edits.
Alien places cloud replicas. Provider controllers create the cloud resources around the container. Alien decides where replicas run on the customer's machines.