Docs

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:

Bring these ECS services to Alien
Install the Alien skills: npx skills add alienplatform/skills Use the alien-integration skill to bring our ECS services to Alien as a whole-product deployment in the customer's AWS account, following https://alien.dev/docs/guide/existing-app/ecs.md. Read the final task definitions (terraform show -json, cdk synth, or aws ecs describe-task-definition; read-only). Map containers, port mappings, the load balancer, health checks, dependsOn, secrets referenced by ARN, autoscaling, task roles, and scheduled tasks to alien.ts. Show me the mapping before writing alien.ts. Give every stateful service and setup step a health check that proves it's ready. Verify with alien dev, including a real login and the product's main action. Don't publish a release, create a customer deployment, or apply any infrastructure change without asking.

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 taskDefinition

The 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:

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

ECSalien.ts
Container definitionA 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 commandHealth 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 SSMInputs 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 SUCCESSThe dependency is a setup step: a command, or the start of the service's command
Sidecar with essential: false that keeps runningFold it into the main process, or drop it
Service desiredCount.replicas(n)
Application Auto Scaling policy.autoScale({ min, desired, max, targetCpuPercent })
Task roleOne 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 taskA periodic task in a service, or a Worker with a schedule trigger
Capacity provider, instance typeA 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 valueFrom names 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.Postgres is 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-x64 and 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.

On this page