#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

#Service Options

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

#Scaling Configuration

#minInstances

Controls the minimum number of instances always running.

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

Recommendations:

• Dev on GCP or Azure: 0 - Save costs, cold starts are acceptable
• Prod critical paths: 1+ - Avoid cold starts for user-facing APIs
• 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

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

#Resource Configuration

#CPU

#Memory

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:

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

#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). 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.

On AWS, workers get auto-scaling resources (CPU-based target tracking at 70%), like services and Kong. On GCP and Azure, the container runtime handles scaling natively.

#Database

Configure managed PostgreSQL:

{
  "version": "1.0.0",
  "prod": {
    "database": {
      "tier": "db-n1-standard-1",
      "diskSize": 50,
      "ha": true,
      "backup": true
    }
  }
}

Database tiers by provider:

GCP (Cloud SQL):

• db-f1-micro - Development (shared CPU)
• db-g1-small - Small production
• 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)

AWS (RDS PostgreSQL):

• db.t3.micro - Development (~$15/mo)
• db.t3.small - Small production
• db.r6g.large - Standard production
• db.r6g.xlarge - High-traffic production

Azure (PostgreSQL Flexible Server):

• B_Standard_B1ms - Development (burstable, ~$14/mo)
• B_Standard_B2s - Small production (burstable)
• GP_Standard_D2s_v3 - Standard production (general purpose)
• GP_Standard_D4s_v3 - High-traffic production (general purpose)

#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. 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.

#Redis

Configure managed Redis:

{
  "version": "1.0.0",
  "prod": {
    "redis": {
      "tier": "STANDARD_HA",
      "memoryGb": 2
    }
  }
}

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 (~$13/mo, clustered)
• Balanced_B1 - Small production
• Balanced_B3 - Standard production

#Frontend Domains

Configure domains for frontend services:

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

#Load Balancer

Configure domain redirects and API domain:

{
  "version": "1.0.0",
  "prod": {
    "loadBalancer": {
      "redirectDomains": ["example.app", "example.io"]
    }
  }
}

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
    }
  }
}

#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
        }
      }
    }
  }
}

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
            }
          }
        ]
      }
    }
  }
}

#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"
            }
          }
        ]
      }
    }
  }
}

#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"]
              }
            ]
          }
        ]
      }
    }
  }
}

Match condition options:

#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"
    }
  }
}

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

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

#Cost Optimization

#Development environments

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

#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.