For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /docs/infrastructure/service-configuration.md.

Service Configuration

Customize how your services run in the cloud using infrastructure.json.

Overview

The .tsdevstack/infrastructure.json file lets you override default settings per environment:

{
  "$schema": "./infrastructure.schema.json",
  "version": "1.0.0",
  "dev": {
    "auth-service": {
      "minInstances": 1,
      "maxInstances": 5
    }
  },
  "prod": {
    "auth-service": {
      "minInstances": 1,
      "maxInstances": 20,
      "cpu": "2",
      "memory": "1Gi"
    }
  }
}

Creating infrastructure.json

If you don't have an infrastructure.json file yet, create it in your .tsdevstack directory:

touch .tsdevstack/infrastructure.json

Then add the minimum required content:

{
  "$schema": "./infrastructure.schema.json",
  "version": "1.0.0"
}

IDE Autocomplete

The $schema property enables intelligent autocomplete and validation in VS Code and other editors that support JSON Schema.

What you get:

  • Autocomplete for all configuration options (CPU, memory, database tiers, etc.)
  • Inline validation for invalid values
  • Hover documentation for each property

How it works:

  1. Add "$schema": "./infrastructure.schema.json" as the first property in your infrastructure.json
  2. The framework includes infrastructure.schema.json in the .tsdevstack directory
  3. Your IDE automatically provides suggestions and validation
Tip

If autocomplete isn't working, ensure the infrastructure.schema.json file exists in your .tsdevstack directory. Run npx tsdevstack infra:init --env <environment> to generate it.

Service Options

OptionDefaultDescription
minInstances1Minimum running instances (0 = scale to zero, GCP and Azure only). See minInstances
maxInstances10 (GCP, AWS), 5 (Azure)Maximum instances for auto-scaling
cpu"1" (GCP), "0.25" (AWS, see below), "0.5" (Azure)CPU allocation (valid values vary by provider, see below)
memory"512Mi" (GCP, AWS, see below), "1Gi" (Azure)Memory allocation (valid values vary by provider, see below)
timeout"300s"Request timeout (30s-3600s)
concurrency80Max concurrent requests per instance
logLevel"info"Log level of a NestJS service or worker: trace, debug, info, warn, error, fatal. See Cloud Logs

The JSON schema is provider-aware — IDE autocomplete will only show values valid for your cloud provider.

On AWS, a service, Next.js app or worker without cpu and memory runs at 0.25 vCPU / 512 MiB, the smallest Fargate size. If you set only one of the two, the other comes from 0.5 vCPU / 1 GiB. Fargate runs only certain pairs (0.25 vCPU with 512Mi, 1Gi or 2Gi; 0.5 with 1Gi to 4Gi; 1 with 2Gi to 8Gi; 2 with 4Gi to 16Gi; 4 with 8Gi to 30Gi), and infra:generate stops at a pair it can't run, the merged one included.

On Azure, Next.js apps run on App Service, not Container Apps: cpu and memory don't apply to them, and their instance counts follow the plan's SKU. See Azure App Service plans.

Cloud Run limits (GCP)

Cloud Run rejects some combinations, so infra:generate, infra:plan, the deploy commands and infra:status check them first:

  • cpu below 1 needs "concurrency": 1 (each instance then serves one request at a time). Workers and Kong need cpu 1 or more.
  • A NestJS service with minInstances 1 or more needs cpu 1 or more: its CPU stays on between requests (see minInstances), which Cloud Run allows from 1 vCPU.
  • Memory per CPU: up to 512Mi below 0.5 vCPU, 1Gi below 1, 4Gi at 1, 8Gi at 2. 4 vCPU needs at least 2Gi, 8 vCPU at least 4Gi. :::

Scaling Configuration

minInstances

Controls the minimum number of instances always running.

ValueBehaviorCostStartup
0Scale to zero when idle (GCP and Azure only)Pay only when usedCold start (see below)
1+ (default)Always runningContinuous costNo cold start

1 or more: the service always runs. It answers requests, and it keeps working between them: message handlers (@OnMessage), timers, anything that waits on Redis. On GCP, a NestJS service with minInstances 1 or more keeps its CPU between requests (Cloud Run's instance-based billing). Cloud Run otherwise gives a service CPU only while it handles a request, so its message handlers would wait for the next request. That costs more: about $50 a month instead of about $10 for one instance at 1 vCPU and 512 MiB (list prices). Next.js apps get CPU only during requests.

0: the service scales to zero when idle. A good fit for dev and staging, which sit idle most of the time. Problematic for production:

  • Messages for the service wait in Redis until a request starts it. Nothing is lost, but the work happens late: a user signs up, and the service that gives them their plan does it on its next request.
  • The first request after an idle period waits for a cold start.
  • Between requests the service has no CPU. Work a request started and didn't finish pauses until the next request, and its traces arrive late.

Every service that subscribes to messages should keep minInstances at 1 or more. Workers always run.

Scale-to-zero is a platform feature of Cloud Run and Container Apps, and cold start times vary:

ProviderTypical Cold Start
GCP (Cloud Run)~2-5s
Azure (Container Apps)~5-15s

On Azure, scale-to-zero covers the services on Container Apps. Kong and Next.js apps run on App Service, which cannot scale to zero: minInstances: 0 runs one instance there.

:::warning AWS has no scale-to-zero On AWS every ECS service (NestJS services, Next.js frontends, workers and Kong) runs at least one task. minInstances: 0 fails validation in infra:generate, infra:plan, infra:deploy and infra:status, with a hint to set 1 or more. Backend services on AWS are reachable only inside the VPC, so there is no public entry point that could wake a stopped service. See AWS Cost Estimation for what always-on costs.

Recommendations:

  • Dev and staging on GCP or Azure: 0 saves money. Messages and background work wait for the next request, and cold starts are acceptable
  • Production: 1+ (the default) for every service
  • Detached workers: 1+ - Workers must always be running to poll Redis queues. On GCP and Azure the framework raises 0 to 1 for workers; on AWS it fails validation like any other service

maxInstances

Limits how many instances can run during high traffic.

  • Higher values handle more concurrent users
  • Each instance costs money while running
  • The container runtime auto-scales based on CPU utilization and request queue. On AWS, NestJS services, Next.js frontends, workers and Kong scale on CPU (target tracking at 70%) between minInstances and maxInstances
  • On Azure, Kong and Next.js apps only autoscale on a Standard or Premium App Service plan. See Azure App Service plans

Example: If each instance handles 80 concurrent requests and you expect 800 peak concurrent users, set maxInstances: 10 minimum.

Resource Configuration

CPU

ValueGCPAWSAzure
"0.25"YesYesYes
"0.5"YesYes (default)Yes (default)
"1"Yes (default)YesYes
"2"YesYesYes
"4"YesYesYes
"8"Yes——

Memory

ValueGCPAWSAzure
"256Mi"Yes——
"512Mi"Yes (default)Yes—
"0.5Gi"Yes—Yes
"1Gi"YesYes (default)Yes (default)
"2Gi"YesYesYes
"4Gi"YesYesYes
"8Gi"YesYes—
"16Gi"—Yes—

GCP has the widest range (256Mi–8Gi). AWS supports larger instances (up to 16Gi). Azure is the most constrained (0.5Gi–4Gi, no sub-Gi values).

Kong Gateway

Configure the API gateway separately:

{
  "version": "1.0.0",
  "prod": {
    "kong": {
      "minInstances": 1,
      "maxInstances": 10,
      "cpu": "2",
      "memory": "1Gi"
    }
  }
}

Kong defaults:

OptionGCPAWSAzure
minInstances111
maxInstances10105 (Standard or Premium plan only)
cpu"1""0.25" (see below)Set by appService.kongSku
memory"1Gi""1Gi" (see below)Set by appService.kongSku

Keep Kong at minInstances: 1 or more: every API request goes through it. On AWS, 0 fails validation.

On AWS, Kong without cpu and memory runs at 0.25 vCPU / 1 GiB. Its task also holds the trace collector, which takes 256 MiB of it. If you set only one of the two, the other comes from 1 vCPU / 2 GiB.

On Azure, leave out cpu and memory: Kong runs on an App Service plan, and the plan's SKU sets them (setting them fails validation). Kong's maxInstances only takes effect on a Standard or Premium plan. See Azure App Service plans.

Azure App Service plans

On Azure, Kong and the Next.js apps run on App Service: Kong on its own plan, and every Next.js app on a second, shared plan. The plan's SKU sets CPU and memory per instance, and decides what minInstances and maxInstances do.

{
  "version": "1.0.0",
  "prod": {
    "appService": {
      "kongSku": "S1",
      "nextjsSku": "B1"
    },
    "kong": { "minInstances": 1, "maxInstances": 4 },
    "frontend": { "minInstances": 2, "maxInstances": 2 }
  }
}

Here Kong autoscales between 1 and 4 instances, and the frontend Next.js app runs a fixed 2.

SKUTierInstancesMost instances per plan
B1 (default), B2, B3BasicFixed at minInstances3
S1, S2, S3StandardCPU autoscale from minInstances to maxInstances10
P1v3, P2v3, P3v3PremiumCPU autoscale from minInstances to maxInstances30
  • At least one instance. A plan runs minInstances instances. App Service cannot scale to zero, so minInstances: 0 runs one.
  • Autoscale needs Standard or Premium. When maxInstances is above minInstances, the plan gets an autoscale rule: one more instance when average CPU stays above 70% for 5 minutes, one fewer when it stays below 30% for 10 minutes. A redeploy keeps the current count.
  • Basic plans run a fixed count. A maxInstances above minInstances on a Basic plan fails validation. With the defaults (Kong maxInstances: 5 on B1), infra:generate notes the fixed count and names the SKU that autoscales.
  • Next.js apps share one plan. It uses the largest minInstances and maxInstances among them.
  • Health checks with more than one instance. App Service pings Kong's /status and each Next.js app's /health every minute. An instance that fails for 2 minutes leaves rotation; one that stays unhealthy for an hour is replaced. At most half of an app's instances leave rotation at a time.
  • No sticky sessions. Requests spread across instances. Kong and the Next.js apps keep no session state.
  • Limits are checked before deploy. Counts above the tier's maximum, and cpu or memory on Kong or a Next.js app, fail validation in infra:generate, infra:plan and infra:deploy. For more CPU or memory per instance, pick a bigger SKU (B2, S2, P1v3 and up).

App Service bills per instance, so every instance a plan runs costs as much as the first. Make sure your subscription's App Service quota covers the largest count a plan can reach: see Azure account setup and Azure cost estimation.

Detached Workers

Configure BullMQ worker scaling and resources:

{
  "version": "1.0.0",
  "dev": {
    "auth-worker": {
      "minInstances": 1,
      "maxInstances": 3,
      "cpu": "0.25",
      "memory": "512Mi"
    }
  },
  "prod": {
    "auth-worker": {
      "minInstances": 2,
      "maxInstances": 10,
      "cpu": "1",
      "memory": "1Gi"
    }
  }
}

Workers support the same options as services (minInstances, maxInstances, cpu, memory). On GCP, workers need cpu 1 or more: they keep their CPU allocated between requests, which Cloud Run allows from 1 vCPU (the 0.25 above is for AWS). The framework enforces minInstances >= 1 because workers must always be running to poll Redis queues: on GCP and Azure 0 is overridden to 1, on AWS it fails validation.

A worker adds instances when its average CPU goes above a target, up to maxInstances, and removes them when it drops: 70% on AWS and Azure, and Cloud Run's own 60% on GCP (workers there keep their CPU allocated, so Cloud Run counts their CPU even between requests).

Workers scale on CPU, not on the number of jobs waiting. So match the job to the knob:

  • A job that waits on the network (sending an email, calling an API) barely uses the CPU, so adding workers never triggers. Let one worker run several at once with the processor's concurrency. If the API has a rate limit, add a limiter: it holds the whole queue, across every worker, and jobs over it wait.
  • A job that uses the CPU (resizing images, building reports) keeps the default of one at a time per worker, and more work adds workers.

The auth template's email processor does the first:

@Processor('notifications', {
  concurrency: 5,                       // up to 5 emails in flight per worker
  limiter: { max: 10, duration: 1000 }, // Resend's default: 10 requests per second per team
})

If a queue still falls behind, raise concurrency (within the API's limit) or minInstances.

Note

Changing a worker's maxInstances affects the database connection pool calculation. After changing scaling config, redeploy all services and workers to rebalance pool sizes.

Database

Configure managed PostgreSQL:

{
  "version": "1.0.0",
  "prod": {
    "database": {
      "tier": "db-n1-standard-1",
      "diskSize": 50,
      "ha": true,
      "backup": true
    }
  }
}
OptionDefaultDescription
tier"db-f1-micro"Instance size
diskSizeGCP 10, AWS 20, Azure 32Storage in GB. GCP: 10 to 1000. AWS: 20 to 1000. Azure: 32, 64, 128, 256 or 512
hafalseHigh availability, see below
backupGCP and AWS true, Azure falseAutomated backups, see below
deletionProtectiontrueStops the database server from being deleted, see below
serverName{project}-{env}-postgres-{suffix}Azure only. PostgreSQL server name, see Custom server name (Azure)

High availability (ha) keeps a standby that takes over when the primary fails. It roughly doubles the database cost.

  • GCP: regional Cloud SQL instance. Needs backup: true.
  • AWS: Multi-AZ, with the standby in another Availability Zone.
  • Azure: zone-redundant standby. Only on General Purpose (GP_) and Memory Optimized (MO_) tiers, and only in regions with availability zones. infra:deploy checks the region before it starts.

Backups (backup):

  • GCP: false turns automated backups and point-in-time recovery off.
  • AWS: false turns automated backups and point-in-time recovery off. The final snapshot on infra:destroy is still taken.
  • Azure: backups can't be turned off. true keeps them for 35 days, false for 7 (the minimum).

Deletion protection (deletionProtection):

  • GCP and AWS: the provider's own deletion protection on the instance. infra:destroy turns it off before it deletes anything.
  • Azure: a delete lock on the PostgreSQL server (tsdevstack-database-delete-lock), put on by infra:deploy. The lock also covers the databases on the server. infra:remove-service lifts it while it deletes a service's database and puts it back after. infra:destroy lifts it first, and stops before deleting anything if it can't. With false, the next deploy takes the lock off before it applies.
  • Azure: with the lock on, a deploy that would delete a database (a service whose hasDatabase you turned off, or a service you took out of config.json without infra:remove-service) fails at that step. To drop the database on purpose, set deletionProtection to false for that deploy, then back to true.
Note

On AWS, changes to ha, backup and tier on a running database are applied in the next maintenance window (Mondays 04:00 to 05:00 UTC). Turning backups on or off causes a short outage.

Database tiers by provider (the full list each provider accepts; deploys size the connection pool from each tier's connection limit, and infra:generate and the deploy commands reject other values):

GCP (Cloud SQL):

  • db-f1-micro - Development (shared CPU)
  • db-g1-small - Small production (shared CPU)
  • db-n1-standard-1 - Standard production (1 vCPU)
  • db-n1-standard-2 - Larger production (2 vCPU)
  • db-n1-standard-4 - High-traffic production (4 vCPU)
  • db-n1-standard-8, db-n1-standard-16 - 8 and 16 vCPU

AWS (RDS PostgreSQL):

  • db.t3.micro - Development (~$15/mo)
  • db.t3.small, db.t3.medium - Small production (burstable)
  • db.t4g.micro, db.t4g.small, db.t4g.medium - Burstable, ARM (Graviton)
  • db.r6g.large - Memory optimized, ARM (Graviton)

Azure (PostgreSQL Flexible Server):

  • B_Standard_B1ms - Development (burstable, ~$14/mo)
  • B_Standard_B2s, B_Standard_B2ms - Small production (burstable)
  • GP_Standard_D2s_v3, GP_Standard_D2ds_v5 - Standard production (general purpose)
  • GP_Standard_D4s_v3, GP_Standard_D4ds_v5 - High-traffic production (general purpose)
  • MO_Standard_E4s_v3, MO_Standard_E4ds_v5 - Memory optimized

The _v5 sizes are Azure's current generation, with the same vCores, memory and connection limits as their _v3 twins. A region can offer one generation to your subscription and not the other (see PostgreSQL Region Access).

Data of a removed service

infra:remove-service saves the service's database before it drops it. The file goes to a private bucket of the environment, made by infra:deploy, and is deleted after 7 days. infra:destroy deletes the bucket with the environment. Keeping a file costs less than a cent per GB.

The bucket is a Cloud Storage bucket on GCP, an S3 bucket on AWS, and a container in a storage account of its own on Azure. Only the database job reads and writes the files.

To bring the data back, deploy the service again (cloud-secrets:push, then infra:deploy), then run:

npx tsdevstack infra:restore-database <service> --env <env>

See infra:restore-database.

Without that file (removed with --skip-export, or more than 7 days ago), the data is only in the database server's automated backups (see backup above). Each backup covers the whole server, not one database. Restore a backup into a new server, at a time just before the removal. Then copy the service's database from it into the live server, and delete the new one:

  • GCP: clone the Cloud SQL instance with point-in-time recovery.
  • AWS: a point-in-time restore of the RDS instance. It creates a new instance.
  • Azure: a point-in-time restore of the Flexible Server. It creates a new server.

On GCP, don't restore a backup onto the live instance: that rolls back every service's database to the backup's time.

Custom server name (Azure)

On Azure the PostgreSQL Flexible Server name is a global DNS name (<name>.postgres.database.azure.com), so it has to be unique across all of Azure, not only in your subscription. tsdevstack names it {project}-{env}-postgres-{suffix}, the suffix 6 characters from the subscription ID (environments set up with v0.12.0 or earlier: {project}-{env}-postgres). If someone else already holds that name, the deploy fails with ServerNameAlreadyExists. Typical causes: another project uses the same project name, or a server with that name still exists in a subscription you deleted.

Pick a different name for that environment with serverName:

{
  "version": "1.0.0",
  "dev": {
    "database": {
      "serverName": "myapp-dev-postgres-2"
    }
  }
}

Rules: 3 to 63 characters, lowercase letters, digits and hyphens, no hyphen at the start or the end. Set it per environment; environments without it keep the default name. Your services' connection strings follow on their own, since the deploy builds them from the server address Terraform reports.

The field is Azure only. On GCP and AWS the schema flags it in your editor and infra:status reports it as an error.

Warning

Set serverName before the first deploy of an environment. Changing it on an environment that is already running makes Terraform replace the server: the old server and every database on it are destroyed and a new, empty one is created. With deletionProtection on (the default), the delete lock makes that deploy fail instead. If you really need to rename a live server, back up first (pg_dump) and check npx tsdevstack infra:plan before you deploy.

Redis

Configure managed Redis:

{
  "version": "1.0.0",
  "prod": {
    "redis": {
      "tier": "STANDARD_HA",
      "memoryGb": 2
    }
  }
}
OptionDefaultDescription
tier"BASIC""BASIC" or "STANDARD_HA"
memoryGb1GCP only. Memory in GB (1-300). AWS and Azure size Redis by tier

GCP (Memorystore):

  • BASIC - Single instance, no failover
  • STANDARD_HA - High availability with automatic failover

AWS (ElastiCache):

  • cache.t3.micro - Development (~$12/mo)
  • cache.t3.small - Small production
  • cache.r6g.large - Standard production

Azure (Managed Redis):

  • Balanced_B0 - Development (~$26/mo for two nodes, clustered)
  • Balanced_B1 - Small production
  • Balanced_B3 - Standard production
Info

Azure Managed Redis uses EnterpriseCluster policy. BullMQ requires a {bull} prefix to avoid CROSSSLOT errors — see Azure Architecture for details.

Frontend Domains

Configure domains for frontend services:

{
  "version": "1.0.0",
  "prod": {
    "frontend": {
      "domain": "example.com"
    },
    "admin-app": {
      "domain": "admin.example.com"
    }
  }
}
OptionDescription
domainFull domain for the frontend

Load Balancer

Configure domain redirects and API domain:

{
  "version": "1.0.0",
  "prod": {
    "loadBalancer": {
      "redirectDomains": ["example.app", "example.io"]
    }
  }
}
OptionDescription
redirectDomainsDomains to 301 redirect to canonical domain (apex and subdomains)
apiDomainOverride API domain (defaults to api.{DOMAIN})

When you own multiple domains (e.g., .com, .io, .app), add alternates to redirectDomains. All traffic to those domains redirects to your canonical domain set in the DOMAIN secret.

Access Control

Keep non-production environments out of search engines:

{
  "version": "1.0.0",
  "dev": {
    "accessControl": {
      "noIndex": true
    }
  }
}
OptionDefaultDescription
noIndexfalseAdd X-Robots-Tag: noindex, nofollow header
Warning

Environment password protection was removed. The accessControl.protected and accessControl.cookieTtlHours fields are no longer accepted, and a config that still sets them fails validation. Remove them from infrastructure.json.

Scheduled Jobs

Configure cron-based scheduled jobs in the scheduledJobs array. See the Scheduled Jobs guide for full configuration, service-side implementation, authentication, and provider architecture.

With the auth template, every environment needs the sync-api-key-usage job; infra:generate warns and prints the entry when it is missing. See API Keys.

WAF Rules

The framework includes default WAF rules for common attacks (SQL injection, XSS, path traversal, command injection, SSRF, scanner fingerprints, and more). You can customize the global rate limit and add custom rules per provider.

Global rate limit

Override the default rate limit (1000 requests per 60 seconds per IP) across all providers:

{
  "version": "1.0.0",
  "prod": {
    "security": {
      "waf": {
        "rateLimit": {
          "count": 500,
          "intervalSec": 60
        }
      }
    }
  }
}
OptionRequiredDescription
countYesRequests allowed per interval
intervalSecYesInterval in seconds (1-3600)

The framework translates this to each provider's native format:

  • GCP: Direct pass-through to Cloud Armor throttle rule
  • AWS: Scaled to 5-minute window (AWS minimum). 1000/60s becomes 5000 per 5 minutes
  • Azure: Scaled to per-minute buckets. 500/30s becomes 1000 per 1 minute

Custom rules (GCP)

GCP uses CEL expressions for custom rules:

{
  "version": "1.0.0",
  "prod": {
    "security": {
      "waf": {
        "customRules": [
          {
            "name": "block-bad-ips",
            "priority": 800,
            "action": "deny(403)",
            "expression": "inIpRange(origin.ip, '192.0.2.0/24')",
            "description": "Block known bad IP range"
          },
          {
            "name": "rate-limit-api",
            "priority": 850,
            "action": "throttle",
            "expression": "request.path.matches('/api/.*')",
            "description": "Rate limit API calls",
            "rateLimit": {
              "count": 100,
              "intervalSec": 60
            }
          }
        ]
      }
    }
  }
}
OptionRequiredDescription
nameYesUnique identifier for the rule
priorityYesEvaluation order (lower = first). Use 800-899 for custom rules
actionYes"allow", "deny(403)", "deny(404)", "deny(429)", or "throttle"
expressionYesCEL expression to match requests
descriptionNoHuman-readable description
rateLimitFor throttleRequired when action is "throttle"

Custom rules (AWS)

AWS uses statement-based rules with byte match, rate-based, and geo match types:

{
  "version": "1.0.0",
  "prod": {
    "security": {
      "waf": {
        "awsCustomRules": [
          {
            "name": "block-country",
            "priority": 100,
            "action": "block",
            "matchType": "geo_match",
            "geoMatch": {
              "countryCodes": ["CN", "RU"]
            },
            "description": "Block traffic from specific countries"
          },
          {
            "name": "block-bad-path",
            "priority": 200,
            "action": "block",
            "matchType": "byte_match",
            "byteMatch": {
              "searchString": "/internal",
              "fieldToMatch": "uri_path",
              "positionalConstraint": "STARTS_WITH"
            }
          }
        ]
      }
    }
  }
}
OptionRequiredDescription
nameYesUnique identifier
priorityYes100-899 (managed rules use 1-99)
actionYes"block", "allow", or "count"
matchTypeYes"byte_match", "rate_based", or "geo_match"
byteMatchFor byte_matchSearch string, field, and positional constraint
geoMatchFor geo_matchISO 3166-1 alpha-2 country codes
rateLimitFor rate_basedRequests per 5-minute window (minimum 100)

Custom rules (Azure)

Azure uses match conditions with operators and transforms:

{
  "version": "1.0.0",
  "prod": {
    "security": {
      "waf": {
        "azureCustomRules": [
          {
            "name": "BlockBadBot",
            "type": "MatchRule",
            "priority": 1000,
            "action": "Block",
            "matchConditions": [
              {
                "matchVariable": "RequestHeader",
                "operator": "Contains",
                "matchValues": ["bad-bot", "scraper"],
                "selector": "User-Agent",
                "transforms": ["Lowercase"]
              }
            ],
            "description": "Block known bad bots"
          },
          {
            "name": "RateLimitExpensiveAPI",
            "type": "RateLimitRule",
            "priority": 1001,
            "action": "Block",
            "rateLimitDurationInMinutes": 5,
            "rateLimitThreshold": 100,
            "matchConditions": [
              {
                "matchVariable": "RequestUri",
                "operator": "Contains",
                "matchValues": ["/api/expensive"]
              }
            ]
          }
        ]
      }
    }
  }
}
OptionRequiredDescription
nameYesUnique name (alphanumeric only)
typeYes"MatchRule" or "RateLimitRule"
priorityYesUse 1000+ to avoid conflicts with framework rules
actionYes"Block", "Allow", or "Log"
matchConditionsYesArray of match conditions (all must match)
rateLimitDurationInMinutesFor RateLimitRuleWindow in minutes
rateLimitThresholdFor RateLimitRuleRequest threshold

Match condition options:

OptionRequiredDescription
matchVariableYes"RequestUri", "RequestMethod", "RequestHeader", "RequestBody", "SocketAddr", "QueryString"
operatorYes"Contains", "Equal", "IPMatch", "GreaterThan"
matchValuesYesValues to match against
selectorFor headersHeader name (e.g., "User-Agent")
transformsNo["Lowercase"], ["UrlDecode"], or ["Lowercase", "UrlDecode"]

Schema validation

The infrastructure.schema.json is provider-aware — it only shows the custom rule format relevant to your cloud provider. IDE autocomplete will guide you to the correct syntax.

Upload Size Limits

Configure the maximum traditional upload size through Kong:

{
  "version": "1.0.0",
  "prod": {
    "kong": {
      "maxUploadSize": "10m"
    }
  }
}
OptionDefaultDescription
maxUploadSize"10m"Maximum request body size. Uses nginx-style values: "10m", "50m", "1g", "0" for unlimited

This sets Kong's client_max_body_size. Requests exceeding this limit receive a 413 Content Too Large response.

Hard ceilings per provider (cannot be exceeded even with higher configuration):

ProviderCeilingReason
GCP32MBCloud Run request size limit
AWSNo documented limit—
Azure100MB (Standard Front Door)Front Door tier limit

For files larger than these limits, use presigned URL uploads which bypass the WAF/LB/Kong chain entirely. See Object Storage for details.

Tracing

Every request is traced by default. tracing.sampleRate sets the share of new traces each environment keeps:

{
  "version": "1.0.0",
  "prod": {
    "tracing": { "sampleRate": 0.1 }
  }
}
OptionDefaultDescription
sampleRate1Share of new traces kept, from 0 to 1. The first hop decides (the Next.js frontend for its calls, Kong for the others) and the rest follow; scheduled jobs and workers use the same rate

Trace volume drives the trace bill at high traffic. See Traces and Dashboards.

Cost Optimization

Development environments

{
  "dev": {
    "auth-service": { "minInstances": 0 },
    "offers-service": { "minInstances": 0 },
    "kong": { "minInstances": 1 },
    "database": { "tier": "db-f1-micro", "ha": false },
    "redis": { "tier": "BASIC", "memoryGb": 1 }
  }
}

A GCP example: the database and Redis tiers are GCP's. Kong stays at 1, because every API request goes through it. On AWS nothing scales to zero: minInstances: 0 fails validation there.

Production environments

{
  "prod": {
    "auth-service": { "minInstances": 1, "maxInstances": 20 },
    "offers-service": { "minInstances": 1, "maxInstances": 10 },
    "kong": { "minInstances": 1, "maxInstances": 10 },
    "database": { "tier": "db-n1-standard-1", "ha": true },
    "redis": { "tier": "STANDARD_HA", "memoryGb": 2 }
  }
}

Applying Changes

After modifying infrastructure.json:

npx tsdevstack infra:deploy --env <environment>

Changes are applied on the next deployment. Some changes (like database tier) may cause brief downtime.