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.
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.
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.