Architecture

How evm-cloud's Terraform modules fit together to deploy a complete EVM indexing stack.

High-Level Overview

Data Flow at Runtime

Layer Model

evm-cloud separates concerns into two layers. The workload_mode variable controls how much Terraform manages.

Layer 1: Infrastructure

Everything needed before workloads can run.

Layer 2: Workloads

The actual containers and configuration that run on top of infrastructure.

Workload Modes

variable "workload_mode" {
  type    = string
  default = "terraform"  # or "external"
}

workload_handoff output (available when workload_mode = "external"):

output "workload_handoff" {
  value = {
    runtime = {
      ec2 = { public_ip, private_ip, ssh_user, ssh_key_name }
      eks = { cluster_name, cluster_endpoint, kubeconfig_cmd }
      k3s = { kubeconfig, node_ip }
    }
    database = {
      host, port, username, password_secret_arn, database_name
    }
    networking = {
      vpc_id, private_subnet_ids, security_group_ids
    }
    config = {
      erpc_config_path, rindexer_config_path, abi_dir_path
    }
  }
}

Module Map

Module Dependency Graph

root module (main.tf)
  │
  ├── modules/core/capabilities/          # Capability contracts
  │
  ├── modules/providers/aws/              # AWS adapter
  │   ├── networking/                     # VPC, subnets, SGs
  │   ├── ec2/                            # EC2 + Docker Compose
  │   ├── eks/                            # EKS cluster
  │   ├── k3s-host/                       # EC2 + k3s
  │   │   └── modules/core/k8s/k3s-bootstrap/
  │   └── postgres/                       # RDS PostgreSQL
  │
  └── modules/providers/bare_metal/       # Bare metal adapter
      └── modules/core/k8s/k3s-bootstrap/ (optional)

Compute Engine Comparison

• Just want it to work -- EC2 + Docker Compose. Simplest path, lowest cost.
• Need Kubernetes but not the EKS bill -- k3s. Same K8s API, $0 control plane.
• Production K8s with managed upgrades -- EKS. AWS handles the control plane.
• No AWS account / own hardware -- Bare Metal. SSH to any box with Docker installed.

Data Flow

See Data Flow at Runtime above for the full pipeline diagram.

Provider Abstraction

The root module is provider-neutral. The infrastructure_provider variable routes to the correct adapter.

variables.tf (root)
  │
  │  infrastructure_provider = "aws"    ──→  modules/providers/aws/
  │  infrastructure_provider = "bare_metal" ──→  modules/providers/bare_metal/
  │
  └── Every adapter implements the same output contract:
        - networking: { vpc_id, subnet_ids, security_group_ids }
        - compute:    { host_ip, ssh_user, connection_type }
        - database:   { host, port, credentials_arn }
        - workload:   { deploy_method, config_paths }

How It Works

1. Root module declares provider-neutral variables (instance_type, database_engine, compute_engine, etc.)
2. infrastructure_provider selects which adapter directory to use
3. Adapter module translates generic variables into provider-specific resources (e.g., instance_type = "medium" becomes t3.medium on AWS)
4. Adapter outputs conform to the capability contract defined in modules/core/capabilities/
5. Workload deployment reads adapter outputs to place containers on the provisioned infrastructure

Adding a New Provider

Adding support for a new cloud provider (GCP, Azure, Hetzner, etc.) requires:

1. Create modules/providers/<provider>/ with networking, compute, and database sub-modules
2. Implement the output contract from modules/core/capabilities/
3. Add the provider option to infrastructure_provider validation in variables.tf
4. No changes to root module logic, workload deployers, or existing providers

Related Pages

• Getting Started -- Deploy your first indexer
• Core Concepts -- Providers, compute engines, workload modes in depth
• Variable Reference -- All configuration options
• Examples -- 7 runnable deployment patterns