Overview

The terraform-aws-ao-data-platform module provisions the EKS cluster and, by default (helm.deploy_charts = true), also deploys the ao-data-platform Helm chart — ClickHouse, the OpenTelemetry Collector, and the LLM worker — in the same terraform apply.

The kubernetes and helm providers are configured from the module's outputs, which lets Terraform defer the Kubernetes/Helm resources until after the EKS cluster exists. This is what enables a single-pass apply.

Work through the steps below in order. The required inputs are the same for both cluster paths: region, otel_collector_domain, clickhouse_domain, helm.chart_registry, and helm.chart_version.

1. Configure the providers

Your root module must configure the aws, kubernetes, and helm providers. The kubernetes and helm providers are wired from the module's outputs — substitute your region for us-east-1:

terraform {
  required_providers {
    aws        = { source = "hashicorp/aws", version = "~> 6.0" }
    kubernetes = { source = "hashicorp/kubernetes", version = "~> 2.0" }
    helm       = { source = "hashicorp/helm", version = "~> 2.0" }
  }
}

provider "aws" {
  region = "us-east-1"
}

provider "kubernetes" {
  host                   = module.ao_data_platform.eks_cluster_endpoint
  cluster_ca_certificate = module.ao_data_platform.eks_cluster_ca_certificate
  exec {
    api_version = "client.authentication.k8s.io/v1beta1"
    command     = "aws"
    args        = ["eks", "get-token", "--cluster-name", module.ao_data_platform.eks_cluster_name, "--region", "us-east-1"]
  }
}

provider "helm" {
  kubernetes {
    host                   = module.ao_data_platform.eks_cluster_endpoint
    cluster_ca_certificate = module.ao_data_platform.eks_cluster_ca_certificate
    exec {
      api_version = "client.authentication.k8s.io/v1beta1"
      command     = "aws"
      args        = ["eks", "get-token", "--cluster-name", module.ao_data_platform.eks_cluster_name, "--region", "us-east-1"]
    }
  }
}

2. Configure the module

Choose the section for your deployment path:

New cluster

The module creates the VPC and EKS cluster with sensible defaults (cluster name monte-carlo). The example below deploys the standard highly available topology — two ClickHouse replicas across two AZs, coordinated by a three-voter Keeper ensemble — substitute your region's AZ names:

module "ao_data_platform" {
  source  = "monte-carlo-data/ao-data-platform/aws"
  version = "2.3.0"

  region                = "us-east-1"
  otel_collector_domain = "otel.acme.com"
  clickhouse_domain     = "clickhouse.acme.com"
  hosted_zone_id        = "Z1234567890ABC"

  # Two ClickHouse replicas across two AZs, backed by a 3-voter Keeper ensemble.
  clickhouse_availability_zones = ["us-east-1a", "us-east-1b"]
  keeper_availability_zones     = ["us-east-1a", "us-east-1b", "us-east-1c"]
  clickhouse_replica_count      = 2

  helm = {
    chart_registry = "oci://registry-1.docker.io/montecarlodata"
    chart_version  = "4.0.0"

    llm_worker = {
      image_tag = "1.1.0-aws"
    }
  }
}

See examples/new_cluster/ for a complete, copy-paste starting point including the provider block.

Existing cluster

Set cluster.create = false and networking.create_vpc = false, and provide your cluster name, VPC ID, and private subnet IDs in different AZs (one subnet per AZ — three AZs for the default HA topology):

module "ao_data_platform" {
  source  = "monte-carlo-data/ao-data-platform/aws"
  version = "2.3.0"

  region = "us-east-1"

  cluster = {
    create                = false
    existing_cluster_name = "my-cluster"
  }

  networking = {
    create_vpc                  = false
    existing_vpc_id             = "vpc-0abc123"
    existing_private_subnet_ids = ["subnet-aaa", "subnet-bbb", "subnet-ccc"]
  }

  otel_collector_domain = "otel.acme.com"
  clickhouse_domain     = "clickhouse.acme.com"
  hosted_zone_id        = "Z1234567890ABC"

  helm = {
    chart_registry = "oci://registry-1.docker.io/montecarlodata"
    chart_version  = "4.0.0"

    llm_worker = {
      image_tag = "1.1.0-aws"
    }

    # Set any controller already present in the cluster to false:
    # install_aws_load_balancer_controller = false
    # install_cert_manager                 = false
    # install_external_secrets_operator    = false
    # install_external_dns                 = false
  }
}

See examples/existing_cluster/ for the full configuration. If the cluster's OIDC provider was created outside Terraform, import it first.

3. Initialize Terraform

terraform init

This downloads the module and the aws, kubernetes, and helm providers.

4. Review the plan

terraform plan

Review the planned changes before applying. On the new-cluster path the plan creates a VPC, the EKS cluster and node groups — including one per listed ClickHouse and Keeper AZ — IAM/IRSA roles, a KMS key, Secrets Manager secrets, ACM certificates, and the Helm releases.

5. Apply

terraform apply

Review the plan once more, then confirm. The apply provisions the AWS infrastructure and (with helm.deploy_charts = true) deploys the chart in one pass. A full apply on the new-cluster path typically takes 15–25 minutes, most of it waiting on the EKS cluster and node groups.

6. Confirm what was created

When the apply completes, review the outputs:

terraform output

You should see (among others):

The AWS infrastructure is now provisioned and the chart is deploying. Verifying that the in-cluster components (ClickHouse, the Collector, the LLM worker) came up healthy is the first step of Deploy the agent and connect to Monte Carlo.

ClickHouse and Keeper node groups

Every ClickHouse replica and every Keeper voter is a stateful pod backed by an AZ-locked EBS volume, so each one runs on its own dedicated single-AZ EKS managed node group. On the new-cluster path (with helm.deploy_charts = true) the module creates them all automatically:

• Per-AZ ClickHouse node groups — one per entry in clickhouse_availability_zones (one node each, tainted dedicated=clickhouse:NoSchedule, instance type r6i.xlarge by default).
• Per-AZ Keeper node groups — one per entry in keeper_availability_zones (one node each, tainted dedicated=keeper:NoSchedule, instance type m6i.large by default).
• The legacy single-instance ClickHouse node group — retained by default (manage_legacy_clickhouse_node_group = true) as a migration aid for deployments that started on the older single-instance layout.

The module wires the matching nodeSelector/tolerations into the Helm release, so the ClickHouse and Keeper pods target their node groups exclusively — no manual configuration required. The OpenTelemetry Collector, LLM worker, and cluster controllers run on the main node group. These node groups pin their AMI version by default so routine applies never roll the stateful nodes implicitly — see High availability — node AMI updates.

On the existing-cluster path, the module does not manage these node groups — attach tainted per-AZ node groups yourself and take the self-managed Helm route (helm.deploy_charts = false) to pass the matching scheduling values, since the module-managed release doesn't expose them. See High availability — existing-cluster deployments.

Harden network access

The ClickHouse and OpenTelemetry Collector NLBs are internal, but their allowed-source ranges (clickhouse_nlb_allowed_source_ranges / otel_collector_nlb_allowed_source_ranges) default to unrestricted. Before relying on the deployment, scope them to the networks that should reach each endpoint — see Network access in the Configuration reference.

Two NLB behaviors are worth knowing about:

• Cross-zone routing is enabled on both NLBs, so an NLB address in any AZ forwards to healthy targets in every AZ — required for the HA topology, where a zone can briefly have no local target. Standard AWS inter-AZ data-transfer charges apply (negligible at typical telemetry volumes).
• NLB subnet placement is pinned to the module's private subnets (the created ones, or networking.existing_private_subnet_ids) rather than left to controller auto-discovery. The load balancer controller accepts at most one subnet per AZ, so keep existing_private_subnet_ids to one subnet per AZ. On deployments upgrading from module 2.0.0, the controller re-sets each NLB's subnets in place on the first apply; if that changes the NLB's AZ set, active connections through a removed AZ are terminated — a brief, one-time blip best scheduled in a quiet window.

Next steps

Continue to Deploy the agent and connect to Monte Carlo.