Cloud deployment with Terraform

The Terraform distribution is a root module plus one thin module per cloud. You pick the cloud with a single variable; the module provisions the network, the managed data services, the container platform, secrets, and the load balancer — then deploys the same InsightXtract images you ran under Compose.

The workflow (any cloud)

1. Authenticate to your cloud CLI (aws / az / gcloud / oci).
2. Set terraform.tfvars — the target cloud, region, sizing, and your model provider.
3. terraform init && terraform apply. Outputs include the console URL and API endpoint.

cloud       = "aws"          # aws | azure | gcp | oci
region      = "us-east-1"
environment = "prod"

# sizing
api_min          = 2
api_max          = 6
worker_min       = 2
worker_max       = 20       # autoscale target for bursty submissions
db_instance      = "db.r6g.large"
db_multi_az      = true
db_read_replicas = 1

# model — managed on-cloud, or bring your own key
llm_provider = "bedrock"       # bedrock | azure_openai | vertex | oci_genai | anthropic | openai | custom
llm_model    = "claude-sonnet-5"

terraform init
terraform apply -auto-approve
# outputs:
#   console_url = https://insightxtract.yourco.com
#   api_url     = https://api.insightxtract.yourco.com/api

Pick your cloud

The module maps each dependency to the cloud’s managed service, uses workload identity (no long-lived keys), and stores secrets in the native vault.

module "insightxtract" {
  source       = "insightxtract/platform/aws"
  region       = var.region
  environment  = "prod"
  compute      = "fargate"      # or "eks"
  db_engine    = "aurora-mysql"
  db_multi_az  = true
  llm_provider = "bedrock"
  worker_autoscale = { min = 2, max = 20, target_queue_depth = 30 }
}

module "insightxtract" {
  source       = "insightxtract/platform/azure"
  location     = "eastus"
  compute      = "container_apps"   # or "aks"
  db_ha        = "zone_redundant"
  llm_provider = "azure_openai"
  worker_autoscale = { min = 2, max = 20, target_queue_depth = 30 }
}

module "insightxtract" {
  source       = "insightxtract/platform/gcp"
  project      = var.project_id
  region       = "us-central1"
  compute      = "cloud_run"       # or "gke_autopilot"
  db_ha        = "regional"
  llm_provider = "vertex"
  worker_autoscale = { min = 2, max = 20, max_concurrency = 4 }
}

module "insightxtract" {
  source          = "insightxtract/platform/oci"
  compartment_id  = var.compartment_ocid
  region          = "us-ashburn-1"
  compute         = "oke"              # or "container_instances"
  db_shape        = "MySQL.HeatWave"
  llm_provider    = "oci_genai"
  worker_autoscale = { min = 2, max = 20, target_cpu = 65 }
}

Scaling & operations

InsightXtract is built to scale the part that does the work — the extraction workers — independently of everything else, and to keep the durable tiers highly available.

Autoscaling the workers

Extraction is the compute-heavy, bursty workload: a batch of submissions arrives, workers spike, then drain. Workers are stateless and pull from a work queue, so the platform autoscaler adds replicas on queue depth (preferred) or CPU, up to worker_max, and scales back to worker_min when idle.

High availability

• API and worker replicas spread across availability zones; the LB routes around a failed instance or zone.
• The database runs Multi-AZ / zone-redundant with automatic failover; read replicas offload reporting.
• Object store and secrets are regionally redundant managed services.

Zero-downtime upgrades

Bump the image tag and terraform apply. The platform does a rolling deploy — new replicas come up healthy before old ones drain — and database migrations are backward-compatible, so the API stays available throughout. Roll back by re-applying the previous tag.

Backups & disaster recovery

• Database: automated daily backups + point-in-time recovery (retention is a variable); optional cross-region replica for DR.
• Documents & artifacts: object-store versioning + lifecycle rules; optional cross-region replication.
• Config: your Terraform state is the source of truth — a region is reproducible from code.

Observability

• Health/readiness endpoints on every service (/api/health) for LB and orchestrator probes.
• Structured logs and metrics ship to the cloud-native stack (CloudWatch / Azure Monitor / Cloud Logging / OCI Logging).
• Per-run traces record classify → extract → resolve timings, cache hits, and model latency for capacity planning.

Security & secrets

• Everything runs inside your VPC/VNet; the model is reached over a private endpoint or service gateway where the cloud supports it.
• Credentials come from the cloud vault via workload identity — no long-lived keys in images or env files.
• SSO via OIDC/SAML; role-based access control and per-field audit inside the app.