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 tab for your deployment path.

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

  region                = "us-east-1"
  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  = "1.5.0"

    llm_worker = {
      image_tag = "1.0.0"
    }
  }
}

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

Dedicated ClickHouse node group

On the new-cluster path, the module automatically creates a dedicated single-AZ EKS managed node group for ClickHouse (when helm.deploy_charts = true). It is a single node, tainted dedicated=clickhouse:NoSchedule, and the module wires the ClickHouse pod's nodeSelector/tolerations to target it — no manual configuration required. This isolates ClickHouse from the OpenTelemetry Collector and other workloads, which run on the main node group.

On the existing-cluster path, the module does not manage this node group — attach a tainted single-AZ node group yourself and pass matching clickhouse.nodeSelector/clickhouse.tolerations via your Helm values.

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.

Next steps

Continue to Deploy the agent and connect to Monte Carlo.