AWS, Google Cloud and Azure
Install twins on AWS, Google Cloud or Azure with Terraform modules built on each cloud's managed services.
Install twins on AWS, Google Cloud or Azure with Terraform modules built on each cloud's managed services.
Runs on
AWS (ECS on Fargate or EC2) · Google Cloud (GKE) · Azure (AKS)
You need
Terraform 1.11 or later, and the cloud's Terraform provider
Modules
deploy/terraform/aws, deploy/terraform/gcp, deploy/terraform/azure, deploy/terraform/release
Watch out
On Google Cloud and Azure, Terraform's state holds the cache's key. Keep it encrypted and access-controlled.
Prerequisites
Terraform 1.11 or later, so that no password a module makes is kept in its plan or state.
AWS: the AWS provider 6.62 or later, and the Session Manager plugin for ECS Exec.
Google Cloud: the google provider 7.11 or later, before 8.0,
gke-gcloud-auth-plugin, and the roles and APIs in "Permissions and APIs the apply needs".Azure:
kubelogin, and the resource providers and roles in Before you start.
What each module builds
AWS
deploy/terraform/aws
ECS on Fargate (or EC2)
RDS
ElastiCache (Valkey)
EFS
Google Cloud
deploy/terraform/gcp + deploy/terraform/release
GKE
Cloud SQL
Memorystore for Redis
Persistent disk
Azure
deploy/terraform/azure + deploy/terraform/release
AKS
Azure Database for PostgreSQL
Azure Managed Redis, or Azure Cache for Redis
Azure managed disk
On AWS, one module does everything. On Google Cloud and Azure, the cloud module makes the infrastructure and the release module installs twins on the cluster from the Helm chart.
AWS
deploy/terraform/aws puts twins in your AWS account in one terraform apply:
The twins server as a one-task ECS service on Fargate, behind an application load balancer.
RDS Postgres, ElastiCache (Valkey) and EFS for the worlds.
Every world copied continuously to S3.
Passwords in Secrets Manager, logs in CloudWatch.
The web console as an opt-in.
It needs Terraform 1.11 or later and the AWS provider 6.62 or later.
Copy this
The first key
Sign-in is off by default. Make the first person and their key in the admin task:
The server's root filesystem is read-only, and ECS Exec needs one the SSM agent can write. So these commands run in an admin task: the same image, settings, secrets and database CA as the server, but no port, no worlds volume and a writable root. It runs only while you use it. Its task role alone holds ECS Exec.
The key goes to your session alone: the cluster logs no ECS Exec session. CloudTrail still records each ExecuteCommand, who ran it and on which task. The admin_task output gives the same for scripts. ECS Exec needs the Session Manager plugin.
Inputs that matter
vpc_id
Required
The VPC twins runs in.
public_subnet_ids
Required
Subnets the load balancer faces the network from: at least two, in different zones.
private_subnet_ids
Required
Subnets the server, database, cache and storage sit in: at least two, in different zones.
allowed_cidrs
Required
Who reaches the load balancer. No default, so who reaches it is always a decision. ["0.0.0.0/0"] for anyone.
internal
false
Puts the load balancer on the private network only.
certificate_arn
Empty
ACM certificate for HTTPS. Empty means HTTP only, which allow_insecure_http = true must then say outright.
worlds_base
The load balancer's name
The address agents reach twins at, written into every URL a world hands out.
twins_image
ghcr.io/drizzdev/twins:0.1.0
The twins image. Change it to upgrade.
repository_credentials_secret_arn
Empty
A Secrets Manager secret with {"username", "password"} for a private registry. Empty: the images are public or in ECR.
capacity
Fargate
{ type = "EC2" } runs the same tasks on an Auto Scaling group the module makes.
cpu, memory
1024, 2048
The server task's CPU units and memory in MiB.
model_secret_arn
Empty
A secret holding an OpenAI API key, for worlds founded from a written brief.
replication
true
Copies every world to an S3 bucket with Litestream.
backup
true
AWS Backup's daily backup of the worlds' file system, kept 35 days.
db_multi_az
—
A Postgres standby in a second zone.
db_backup_retention_days
35
Days of RDS backups.
cache_engine
valkey
valkey or redis.
console
Off
{ enabled = true, host = "console.twins.acme.com" }. The console reaches twins at worlds_base, which must then be https.
waf_acl_arn, access_logs_bucket
Empty
An AWS WAF web ACL and an access-log bucket for the load balancer.
deletion_protection
true
Refuses to delete the database and the worlds' storage. Turn it off only to tear a trial down.
Outputs: url, load_balancer_dns_name, first_key, admin_task, restore, restore_task.
What it creates
Twins server
An ECS service of one task. ECS replaces it where it fails. A new task waits for the old one's lock before it serves.
Worlds' data
EFS, encrypted, with an access point owned by the image's user (999). Backed up daily by AWS Backup and kept 35 days (backup).
Worlds' copies
S3 (replication, on by default): Litestream streams every world there. Public access blocked, encrypted, TLS only, versioned.
Accounts, keys, records
RDS Postgres, encrypted, TLS checked by name against the RDS CA. Backups kept db_backup_retention_days (35).
Request allowance
ElastiCache Valkey 8.1, encrypted at rest and in transit, with a token.
Passwords
The database password, the cache token and the console secret, drawn at apply and written write-only to Secrets Manager. None is in a task definition, a plan, the state or an output.
Traffic
An application load balancer: HTTPS with your certificate, allowed_cidrs only, a 300 s idle timeout. Health checked at /ready.
Logs and alarms
CloudWatch logs (log_retention_days, 30) and, with alarm_topic_arn, CloudWatch alarms.
Admin and restore tasks
Task definitions run only by hand: one for twins enroll, issue, role and organization; one to put the worlds back.
Every task runs as its image's own non-root user with a read-only root filesystem. The admin task alone, started by hand, has a writable root.
Google Cloud
deploy/terraform/gcp makes the infrastructure: a GKE cluster, Cloud SQL for PostgreSQL and Memorystore for Redis on a private network. The release module then installs twins on it from the chart.
The twins server runs as a StatefulSet of one on a persistent disk.
Cloud SQL has a private IP only. Memorystore is reached over the VPC with an AUTH string. Both use TLS with the server's certificate checked.
The database password is kept in Secret Manager and out of Terraform's state.
The cluster's control plane answers only the ranges you list.
It needs Terraform 1.11 or later and the google provider 7.11 or later, before 8.0.
Copy this
The providers sign in with gke-gcloud-auth-plugin (gcloud components install gke-gcloud-auth-plugin). It fetches a fresh token whenever one is needed, as Google's guide advises.
The first key
terraform output on the release gives first_key: the two kubectl exec commands that make the first person and their key on the server.
Inputs that matter
project, region
Required
Where it runs.
api_allowed_cidrs
Required
The ranges the control plane answers. Include wherever Terraform and kubectl run from. ["0.0.0.0/0"] opens it to the internet, behind Google's sign-in alone.
control_plane_dns_endpoint
On
The control plane's DNS name, which lets in only Google identities that hold container.clusters.connect. false keeps it to Google's own services.
location
europe-west1-b (a zone)
Set it to the region rather than a zone for a regional cluster that survives a zone's outage. Changing it replaces the cluster.
postgres_high_availability
On (REGIONAL)
A Cloud SQL standby in a second zone. Keep ZONAL for a trial.
redis_tier
BASIC
STANDARD_HA adds a Memorystore replica in a second zone.
node_min_count, node_max_count
—
node_max_count turns on the cluster autoscaler.
database_encryption_key
Optional
A Cloud KMS key that encrypts the cluster's Secrets.
memorystore
On
false runs the chart's own cache inside the cluster instead.
cloud_nat
On
Gives private nodes their way out to pull images from outside Google. false leaves them Google's APIs and Artifact Registry alone.
create_service_networking
On
false takes the peering with Google's service producers as already made (a shared VPC).
backup_retain_days
14
Days of Backup for GKE's nightly backups.
maintenance_window, cluster_maintenance_window
Sunday 04:00 UTC; weekends 00:00–06:00 UTC
When Google may restart Cloud SQL and Memorystore, and upgrade the cluster.
database_password_version
—
Raise it by one and apply to rotate the database password.
deletion_protection
On
Set it to false and apply before terraform destroy.
The chart's values go in the release's values. See Kubernetes.
Azure
deploy/terraform/azure makes the infrastructure: an AKS cluster, Azure Database for PostgreSQL and Azure Managed Redis on a private network. The release module then installs twins on it from the chart.
The twins server runs as a StatefulSet of one on an Azure managed disk.
Postgres takes connections from the virtual network only, over TLS 1.3 with its certificate checked.
Redis is reached through a private endpoint, over TLS.
redis_service = "cache"uses Azure Cache for Redis instead.People and Terraform sign in to the cluster through Entra ID. It has no local accounts.
The database password is kept in Key Vault and never written to Terraform's state.
Before you start
Terraform 1.11 or later.
The subscription's resource providers registered once:
az provider register --namespace <name>forMicrosoft.ContainerService,Microsoft.KubernetesConfiguration,Microsoft.DataProtection,Microsoft.PolicyInsights,Microsoft.KeyVault,Microsoft.DBforPostgreSQLandMicrosoft.Cache(Azure Backup for AKS prerequisites).The identity running Terraform may assign roles (Owner, or User Access Administrator beside Contributor). Where it may not, turn
cluster_network_contributor,terraform_secrets_officerandterraform_cluster_adminoff and have the roles granted beforehand.Azure Policy assignments that reach the cluster leave out the
dataprotection-microsoftnamespace, where the backup extension runs.Terraform's state in an encrypted remote backend (see below).
Copy this
The providers sign in as whoever ran az login, through kubelogin (az aks install-cli installs it). 6dae42f8-4368-4678-94ff-3960e28e3630 is the AKS server application, the same in every tenant. In CI, change --login azurecli to msi, spn or workloadidentity, or sign the Azure CLI in as the pipeline.
A new role takes minutes to take effect, so the module waits after each role it grants (role_propagation_seconds). Should a first apply still stop at Forbidden or 403, apply again.
For kubectl, run az aks get-credentials with the resource_group and cluster_name outputs.
The first key
terraform output on the release gives first_key: the two kubectl exec commands that make the first person and their key on the server.
Inputs that matter
name, location
twins, westeurope
Resource name prefix and Azure region.
api_allowed_cidrs
Required
Where Terraform and kubectl reach the API server and Key Vault from. Public addresses only: Key Vault takes no private range.
admin_group_object_ids
Optional
Entra ID groups whose members administer the cluster.
node_count, node_size, zones
2 nodes across zones 1, 2, 3
The node pool. Across zones, the worlds' disk is zone-redundant (Premium_ZRS).
sku_tier
Standard
The AKS tier. "Free" for the free tier.
redis_service
Azure Managed Redis
"cache" uses Azure Cache for Redis.
postgres_high_availability
false
A Postgres standby in another zone.
geo_redundant_backup
false
Geo-redundant Postgres backups. Set only when the server is made.
backup_retention_days, backup_retain_days
30, 30
Days of Postgres backups and of the disk's nightly backups. Keep them equal.
outbound_type
Load balancer
userDefinedRouting (with route_table_id, egress_cidrs) or userAssignedNATGateway (with nat_gateway_id) for hub and spoke.
monitoring
On
Container Insights into a Log Analytics workspace.
defender
false
Installs Microsoft Defender for Containers' sensor.
acr_id
—
Lets the nodes pull a private copy of the twins image from Azure Container Registry.
database_password_version
—
Raise it to rotate the database password.
deletion_protection
On
A lock against deleting the database.
Chart values (ingress, console, sign-in through your own provider, a private image registry) go in the release's values. See Kubernetes.
The release module
deploy/terraform/release installs twins on a cluster from the chart, pointed at a managed Postgres and Redis. The Google Cloud and Azure modules use it.
namespace
twins
The namespace twins is installed in.
database_dsn
Required
The managed Postgres's address: without its password where database_password gives it, else with it.
database_password
null
The Postgres password, kept out of the address and out of Terraform's state. The server reads it as a file on every connection.
database_password_version
0
The version of database_password. Raise it whenever the password changes.
redis_url
Empty
The managed cache's address, key included. Empty runs a Valkey inside the release.
database_ca
Empty
The CA the Postgres certificate is checked against, PEM (Cloud SQL's server CA).
database_ca_system
false
Check the Postgres certificate against the image's public CAs (Azure Database for PostgreSQL).
redis_ca
Empty
The CA the cache's certificate is checked against, PEM (Memorystore's). Empty: the image's public CAs.
storage_class
Required
The storage class of the server's disk: the cloud's block storage.
chart
The repository's chart
The chart, or an OCI reference to a published one.
pod_security_version
v1.35
The Kubernetes version whose "restricted" pod security standard the namespace enforces.
values
[]
Further chart values, as YAML documents applied in order (ingress, console, identity, images).
Outputs: namespace and first_key.
Next
Upgrades: change the image and apply.
Backups: what each module backs up, and how to restore.
Monitoring: CloudWatch, Cloud Monitoring and Azure Monitor alerts.
Last updated: 27 October 2026
Was this helpful?