Docs

From Terraform

Your Terraform describes one cloud account in detail: yours. In alien.ts you declare what the product needs, such as a database, a bucket, or a queue, and each customer's deployment gets its own in their AWS, Google Cloud, or Azure account.

This page is about Terraform you already use for your product. Customers can also run initial setup with a Terraform module that Alien generates; see Frozen and live.

From the repository with your Terraform:

Bring this Terraform to Alien
Install the Alien skills: npx skills add alienplatform/skills Use the alien-integration skill to bring the product our Terraform deploys to Alien, so each customer gets it in their own cloud account, following https://alien.dev/docs/guide/existing-app/terraform.md. Read the plan with terraform show -json (never apply). For each cloud resource, find the product feature that uses it and declare that in alien.ts: Postgres, Storage, Queue, Kv, Key, Vault. List what Alien provides instead (networks, DNS, logging) and what has no counterpart. Then map the workloads the Terraform runs. 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 plan

Map the planned resources, with variables resolved. Never apply:

terraform plan -var-file prod.tfvars -out tf.plan
terraform show -json tf.plan > plan.json

For CDK, read cdk synth. For Pulumi, read pulumi preview --json.

An example

An RDS Postgres, an S3 bucket, an SQS queue, and a KMS key, used by one service:

alien.ts
import * as alien from "@alienplatform/core"

// Was aws_kms_key. The customer can hold it and revoke it.
const key = new alien.Key("data-key").build()

// Was aws_rds_cluster: Aurora on AWS, Cloud SQL or Flexible Server elsewhere.
const db = new alien.Postgres("db").encryptionKey(key).build()

// Was aws_s3_bucket.
const files = new alien.Storage("files").build()

// Was aws_sqs_queue.
const jobs = new alien.Queue("jobs").build()

// Was the ECS service. See From ECS.
const api = new alien.Container("api")
  .code({ type: "image", image: "ghcr.io/acme/api:2.3.0" })
  .cpu(1)
  .memory("2Gi")
  .port(8080)
  .link(db)
  .link(files)
  .link(jobs)
  .permissions("api")
  .build()

export default new alien.Stack("acme")
  .add(key, "frozen")
  .add(db, "frozen")
  .add(files, "frozen")
  .add(jobs, "frozen")
  .add(api, "live")
  .permissions({
    profiles: {
      api: {
        db: ["postgres/data-access"],
        files: ["storage/data-read", "storage/data-write"],
        jobs: ["queue/data-read", "queue/data-write"],
      },
    },
  })
  .build()

The data stores are frozen: the customer's admin creates them once at initial setup, and later releases can't change or delete them. See Frozen and live.

Mapping

AWS names; Google Cloud and Azure resources map the same way.

Terraformalien.ts
aws_rds_cluster, aws_db_instance (Postgres)alien.Postgres
aws_s3_bucketalien.Storage
aws_sqs_queuealien.Queue. Its leases replace the visibility timeout; long jobs renew them.
aws_dynamodb_table read by key or key prefixalien.Kv
aws_kms_keyalien.Key
aws_secretsmanager_secret the product writesalien.Vault
aws_secretsmanager_secret set per customerInputs and secrets
aws_elasticache_*A stateful Container with the stock image, with one node
aws_lambda_functionA Worker
aws_ecs_*Containers: see From ECS
aws_eks_*, helm_releaseContainers: see From a Helm chart
aws_iam_role and policies for workloadsOne permission profile per workload
aws_vpc, subnets, NAT, security groupsNothing: the customer's admin picks the network at initial setup. See Networking.
aws_route53_record, aws_acm_certificatePublic endpoints, with custom domains chosen at initial setup
aws_cloudwatch_* alarms and log groupsNothing: Alien reports deployment status and collects logs
State buckets, CI rolesNothing: they belong to your account

Details to check

  • Per-environment variables. Each value in prod.tfvars becomes a constant, a value you set per deployment, or a choice the customer's admin makes. Most become constants.
  • DynamoDB queries. Kv has get, set, conditional writes, TTLs, and prefix scans. A table read through secondary indexes fits Postgres better.
  • MySQL, DocumentDB, OpenSearch. There's no managed resource for these. Run the stock image as a stateful Container.
  • Cross-account roles. A role that lets your account reach into the customer's is the wrong direction. Deployments connect out to your backend. See Backend connections.

Next

On this page