Multi-Region Deployments

Stacktape deploys each stack to a single AWS region. To serve users across multiple continents with low latency — or to satisfy data-residency regulations — deploy the same configuration to multiple regions as independent stacks. Each region runs its own CloudFormation stack with its own compute, databases, and networking.

When to use multi-region

Multi-region deployments solve two distinct problems: latency and compliance. If your users are concentrated on one continent and API response time is acceptable from a single region, a CDN gives you global static-asset performance without the operational overhead of multiple regions. Multi-region is the right choice when:

  • Your API or database latency is unacceptable for users far from the primary region (a CDN only helps static or cacheable responses).
  • Regulations (GDPR, data sovereignty) require data to physically reside in a specific jurisdiction.
  • You need active-active redundancy where a regional outage should not take down your product.

When NOT to use multi-region

Most applications do not need multi-region. The additional cost and operational complexity are substantial:

  • You pay for duplicate compute, databases, and networking in every region.
  • Cross-region data consistency requires DynamoDB global tables, Aurora Global Database, or application-level replication — none of which Stacktape configures automatically.
  • Monitoring, debugging, and incident response multiply per region.
  • DNS-based routing (failover, latency, geo) must be configured outside Stacktape.

For most teams, a single region plus a CDN for static content is the right starting point. Revisit multi-region when latency data or compliance requirements force the issue.

How it works

To deploy the same application to two regions, run stacktape deploy twice — once per target region — passing --region each time.

Deploy to the primary region:

stacktape deploy --stage production --region eu-west-1

Deploy to the secondary region:

stacktape deploy --stage production --region us-east-1

Each command creates an independent CloudFormation stack in its target region. The two stacks have no automatic relationship to each other — Stacktape does not configure cross-region replication, failover, or shared state on your behalf.

Choosing regions

Deploy each stack to the AWS region you target. Pick regions close to your users and verify that every AWS service your stack uses is available in that region — service availability varies by region and is published by AWS. For multi-region setups, the most common pattern is one region per continent your users live on (for example eu-west-1 for Europe and us-east-1 for North America).

Sharing configuration across regions

A single stacktape.ts file typically works unchanged across regions. The same resource definitions produce the same infrastructure regardless of where they are deployed:

export default defineConfig(() => {
  const api = new WebService({
    packaging: new DockerfilePackaging({
      buildContextPath: '.',
      dockerfilePath: './Dockerfile'
    }),
    resources: {
      cpu: 1,
      memory: 2048
    }
  });

  return { resources: { api } };
});

The resources property sets the CPU (in vCPUs) and memory (in MB) for the container — see Web Service for all configuration options including scaling. This example uses DockerfilePackaging; Stacktape also supports js-bundle, buildpack and prebuilt-image packaging.

The defineConfig callback receives a params object containing deploy-time context. The available properties — defined in the GetConfigParams type — are region, stage, projectName, command, awsProfile, cliArgs (all CLI arguments passed to the command), and user (an object with id, name, and email). Destructure what you need (e.g., defineConfig(({ region, stage }) => { ... })) to write conditional logic — different scaling targets, instance sizes, or feature flags per region — all from a single stacktape.ts file. For simpler cases where only one or two values differ, deploy-time parameters or directives may be a cleaner approach than conditional logic.

Multi-region patterns

Active-active

Both regions serve production traffic simultaneously. On the AWS side, you configure a DNS routing policy (latency-based, geo-location, or weighted) through Route 53 to direct users to the nearest region. Both regions run identical infrastructure and each must handle its share of traffic independently.

Data strategy: Use DynamoDB global tables for eventually-consistent multi-region access, Aurora Global Database for read replicas with single-writer, or application-level replication for custom sync logic. Each approach involves tradeoffs between consistency, latency, and cost — see the cross-region data section below.

DNS routing: Configure Route 53 latency-based or geo-location routing policies outside Stacktape (directly in the AWS Console or via overrides). Stacktape creates per-region resources but does not manage cross-region routing policies.

When to choose: Active-active suits products with a global user base where both latency and availability matter — real-time collaboration tools, trading platforms, global SaaS. The cost is roughly 2x (or Nx for N regions) since every region runs full infrastructure.

Active-passive (failover)

One region handles all traffic. The passive region stays deployed and ready but receives no requests until the primary fails. On the AWS side, Route 53 failover routing can redirect traffic when health checks detect the primary is down — this routing is configured outside Stacktape.

This pattern is simpler than active-active because only one region processes writes at any time, eliminating cross-region consistency challenges. The tradeoff is that failover introduces downtime equal to the DNS TTL plus health-check detection time — the exact duration depends on your Route 53 health-check interval and DNS TTL settings.

When to choose: Active-passive works when you need disaster-recovery capability but can tolerate brief downtime. The passive region costs compute and database resources even while idle, though you can reduce this with smaller instance sizes or scaling to minimum capacity.

Region per audience

Deploy separate stages to regions matching your user base segments — for example, EU customers hit eu-west-1 and US customers hit us-east-1. Each region operates independently with its own data, and customers are routed by geography or explicit selection.

When to choose: This works well for SaaS products with regional data-residency requirements (GDPR, HIPAA) or where data isolation between regions is a feature, not a bug. There is no cross-region replication needed because each region is a separate data silo by design.

Cross-region data considerations

Stacktape does not automatically replicate data between regions. Each region's databases, buckets, and caches are independent. You must choose a cross-region data strategy based on your consistency and latency requirements:

StrategyServiceConsistencyBest for
DynamoDB global tablesDynamoDBEventual consistencySession stores, user preferences, feature flags
Aurora Global DatabaseAurora PostgreSQL/MySQLAsync replicationRead-heavy workloads with single-region writes
S3 Cross-Region ReplicationS3Eventual consistencyStatic assets, backups, uploaded files
Application-level syncCustomYou controlComplex business logic, selective replication

Configure these AWS-native replication features through overrides or directly in the AWS Console. Stacktape resource definitions create per-region resources; replication links between regions are outside Stacktape's resource model.

Cross-region replication adds cost. DynamoDB global tables charge for replicated write capacity in each region. Aurora Global Database charges for the secondary cluster's reader instances. S3 CRR charges for PUT requests and cross-region data transfer. Factor these into your cost model before enabling replication.

Automating multi-region deploys

Multi-region automation means running one stacktape deploy invocation per target AWS region. Each regional stack is independent — there is no single command that deploys to all regions at once. Your CI/CD pipeline or GitOps workflow orchestrates the per-region deploys, either in parallel or sequentially.

CI/CD pipelines

The most common multi-region setup uses parallel CI/CD jobs — one per target region. In GitHub Actions, GitLab CI, or any pipeline tool, define a matrix of regions and run stacktape deploy for each. See Custom CI/CD for integration patterns.

Each job runs independently. A failure in one region does not affect others — when automatic rollback is enabled, CloudFormation rolls back the failed region while successful regions continue serving traffic.

GitOps with Console

If you use GitOps, the GitOps with Console documentation covers how to configure automated deployments, including region-specific triggers.

Restricting allowed regions

The region-restriction guardrail prevents deployments to unapproved regions — useful for compliance, cost control, or organizational policy. Configure an allowedRegions list on the guardrail and a deploy targeting a region outside the list is rejected.

export default defineConfig(() => {
  const api = new LambdaFunction({
    packaging: new JsBundleLambdaPackaging({
      entryfilePath: './src/api.ts'
    })
  });

  return {
    guardrails: [
      {
        type: 'region-restriction',
        properties: {
          allowedRegions: ['eu-west-1', 'eu-central-1', 'us-east-1']
        }
      }
    ],
    resources: { api }
  };
});

stacktape deploy validates configured guardrails before packaging and the CloudFormation deployment begins, so a forbidden region fails fast — no artifacts are uploaded and no stack operations run.

Other guardrail types (stage-restriction, command-restriction, resource-type-restriction) can further lock down your deployment posture. See Guardrails for the full set.

Monitoring multi-region stacks

Each region's stack is monitored independently. Use stacktape logs with the appropriate --region flag to view logs for a specific region:

stacktape logs api --stage production --region eu-west-1

For the secondary region:

stacktape logs api --stage production --region us-east-1

Since each region runs its own CloudFormation stack, logs, alarms, and metrics are scoped to that region. See Observability for monitoring and alerting options.

Deleting multi-region stacks

Delete each region's stack independently using stacktape delete:

stacktape delete --stage production --region eu-west-1
stacktape delete --stage production --region us-east-1

Order matters if you have DNS routing configured externally — remove DNS records pointing to a region before deleting the stack, or you will have DNS pointing to non-existent infrastructure during the deletion window.

Multi-Region Deployments FAQ

Common questions about running Stacktape stacks across multiple AWS regions.

How many regions can I deploy to?

You can deploy to any number of AWS regions your account supports — each region runs an independent CloudFormation stack. The practical limit is operational: more regions mean more stacks to monitor, more data replication to manage, and higher costs. Most multi-region setups use 2–3 regions.

Can I use the same stage name in multiple regions?

Yes. The same stage name (e.g., production) can be deployed to multiple regions. Each region creates its own independent CloudFormation stack, so resources in different regions do not collide.

How do I keep databases in sync across regions?

Stacktape does not manage cross-region data replication. Use AWS-native solutions: DynamoDB global tables for key-value data with eventual consistency, Aurora Global Database for relational data with async replication, or S3 Cross-Region Replication for object storage. Choose based on whether you need strong consistency (single-writer Aurora) or can tolerate eventual consistency (DynamoDB global tables).

Do I need multi-region, or is a single region plus a CDN enough?

Start with a single region and a CDN. CloudFront caches static and cacheable responses at edge locations worldwide without duplicating your core infrastructure, while multi-region duplicates compute, database, and networking costs in every active region. Move to multi-region only when (1) your dynamic, non-cacheable API latency is unacceptable for distant users, (2) compliance mandates in-region data residency, or (3) you need active-active redundancy for disaster recovery.

What happens if one region's deployment fails?

Each region deploys independently, so a failure in one region does not affect others. When automatic rollback is enabled, CloudFormation rolls back the failed region's stack to its previous state while successful regions keep serving traffic. Check stacktape logs with the failing region's --region flag to investigate.

How do custom domains and DNS routing work with multi-region?

Each region's stack can have its own custom domain, but Stacktape does not manage cross-region routing. To direct users to the nearest or healthiest region, configure Route 53 routing policies (latency-based, geo-location, weighted, or failover) outside Stacktape — directly in the AWS Console or via overrides. Because routing lives outside the stack, remove DNS records pointing to a region before you delete it.