From ECS
A product that runs on Amazon ECS, on Fargate or EC2, moves onto Alien with the same images. Each container in a task definition becomes a container in alien.ts, and the stack deploys into each customer's AWS account, or into Google Cloud, Azure, Kubernetes, or Linux servers.
From the repository that defines your task definitions, in Terraform, CloudFormation, CDK, or Copilot:
Read the task definitions
Map the final task definitions, with every variable resolved. Each of these only reads:
# Terraform: read container_definitions in the plan
terraform plan -out tf.plan && terraform show -json tf.plan > plan.json
# CDK: read the AWS::ECS::TaskDefinition resources
cdk synth > template.yaml
# A running service
aws ecs describe-task-definition --task-definition acme-api --query taskDefinitionThe load balancer, scaling policies, and service discovery are separate resources. Find every resource that refers to the service or its target group.
An example
An api task with a port behind an ALB, a secret from Secrets Manager, a task role that reads one bucket, and target-tracking autoscaling:
import * as alien from "@alienplatform/core"
const config = alien.inputs({
// Was a Secrets Manager secret referenced by ARN in the task definition.
sessionSecret: alien.secret({
providedBy: "developer",
required: true,
label: "Session secret",
description: "Signs user sessions.",
generate: { length: 64 },
env: { name: "SESSION_SECRET", targetResources: ["api"] },
}),
})
// Was the S3 bucket the task role could read.
const uploads = new alien.Storage("uploads").build()
// Was the api container: cpu 1024, memory 2048, port 8080 behind an ALB,
// and a target-tracking policy at 60% CPU.
const api = new alien.Container("api")
.code({ type: "image", image: "123456789012.dkr.ecr.us-east-1.amazonaws.com/acme-api:2.3.0" })
.cpu(1)
.memory("2Gi")
.port(8080)
.publicEndpoint("app", 8080, "http")
.healthCheck({ path: "/healthz", failureThreshold: 10 })
.autoScale({ min: 2, desired: 2, max: 10, targetCpuPercent: 60 })
.link(uploads)
.permissions("api")
.build()
export default new alien.Stack("acme")
.inputs(config)
.add(uploads, "frozen")
.add(api, "live")
.permissions({ profiles: { api: { uploads: ["storage/data-read"] } } })
.build()alien release pulls the image from your ECR with your credentials and copies it into your project's registry. Customer accounts never pull from your ECR.
Mapping
| ECS | alien.ts |
|---|---|
| Container definition | A Container with .code({ type: "image", image }) |
cpu (1024 = 1 vCPU), memory (MiB) | .cpu(1), .memory("2Gi") |
portMappings | .port(containerPort) |
| ALB listener and target group | .publicEndpoint(name, port, "http") |
| NLB | .publicEndpoint(name, port, "tcp") |
| Target group health check | .healthCheck({ path, port, failureThreshold }) |
Container healthCheck that fetches a local URL | .healthCheck({ path, port }) with the same path |
Any other healthCheck command | Health checks are HTTP. Serve a small readiness endpoint from a launcher. |
entryPoint, command | .command([...]): the entrypoint first, then the command |
environment, environmentFiles | .environment({...}) |
secrets from Secrets Manager or SSM | Inputs and secrets: generated, or entered by the customer's admin |
dependsOn with START or HEALTHY | .link() on that container, and retry on startup |
dependsOn with COMPLETE or SUCCESS | The dependency is a setup step: a command, or the start of the service's command |
Sidecar with essential: false that keeps running | Fold it into the main process, or drop it |
Service desiredCount | .replicas(n) |
| Application Auto Scaling policy | .autoScale({ min, desired, max, targetCpuPercent }) |
| Task role | One permission profile per service, granting only the resources it links |
| EBS volume on the task | .persistentStorage(size, { mountPath }) |
| Service Connect or Cloud Map name | <id>.svc. Name the container after the service. |
| EventBridge scheduled task | A periodic task in a service, or a Worker with a schedule trigger |
| Capacity provider, instance type | A ComputeCluster pool with requirements |
These have no counterpart, and you can drop them: the execution role (Alien pulls images and provides secrets), FireLens and other log routers (Alien collects container logs), once you've checked nothing in your product reads what they ship, and deployment circuit breaker settings.
Details to check
- Secrets by ARN. Each
valueFromnames a secret in your account, which doesn't exist in the customer's. Each one becomes an input, or comes from a linked resource. - Migrations and scheduled work with several replicas. Every replica runs its start command, and a periodic task fires once per replica. Guard both with a lock, such as a Postgres advisory lock.
- Health checks that query the database. On AWS,
alien.Postgresis Aurora Serverless v2, which pauses when idle. Point health checks at a path that doesn't touch the database. See Postgres. - Task roles with
*resources. Don't copy them. Grant permission sets on the resources each service links. - EFS. A volume belongs to one replica. Files that several replicas share belong in Storage.
- Architecture. Fargate tasks often run on x86, and Alien builds for Arm on AWS by default. Release with
alien release --targets linux-x64and set the pool's architecture to match. - Static frontends on S3 and CloudFront or Amplify. Keep them in your cloud, or serve the built files from a Container behind a public endpoint.
Next
- From Terraform: the databases, buckets, and queues your Terraform creates next to the services.
- Bring an existing app: images, launchers, and verification.
- AWS: what initial setup creates in the customer's account.
From Docker Compose
Move a product that ships as a Docker Compose file onto Alien, and see where volumes, healthchecks, depends_on, and one-shot setup services go.
From Terraform
Move the databases, buckets, queues, and keys your Terraform creates in your own cloud into alien.ts, so each customer's deployment gets its own.