All settings on this page are optional — the defaults produce a working deployment. Set them as inputs to the Terraform module.

Data retention (TTL)

ClickHouse retains trace data for a fixed window, after which old data is dropped automatically.

ClickHouse users

The platform provisions a least-privilege ClickHouse user model — one SQL user per access path, each scoped to exactly the operations it performs:

schema_owner, otel, llm_worker, monte_carlo, and probe are always provisioned. readonly_user and admin are opt-in.

Each user's password is generated by the module and stored in AWS Secrets Manager (KMS-encrypted), then synced into the cluster by the External Secrets Operator. Each user has its own secret, exposed as a clickhouse_<user>_credentials_secret_arn output. The exception is probe, which is deliberately passwordless — its consumer is the kubelet's readiness check, which can't read a Kubernetes secret — and so has no Secrets Manager entry. Like the other non-admin users, probe is network-facing rather than loopback-restricted; what it can read is limited to replication-health metadata and table names, with no row data exposed. clickhouse_nlb_allowed_source_ranges (see Network access) governs who can reach it.

Read-only user

To provision the optional readonly_user (SELECT-only, profile readonly_settings with readonly = 2 — SELECT plus per-session SET, so JDBC clients such as DataGrip connect cleanly):

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

  clickhouse = {
    readonly_user = {
      enabled = true
      # password = "..."  # optional; omit to auto-generate
    }
  }
}

Its password ARN is exposed as the clickhouse_readonly_user_credentials_secret_arn output.

Ingest user lock-down

otel defaults to read/write so the migration to the monte_carlo user is non-breaking. After Monte Carlo connects as monte_carlo (see Connect to Monte Carlo), set clickhouse.otel.restrict_grants = true to tighten otel to INSERT-only on the raw trace table (otel_traces.otel_traces). Normalization keeps working because the materialized views run as schema_owner, not otel.

Break-glass admin user

The admin superuser is opt-in and, by default, reachable only over loopback (pod-exec) — it is never on a network path. Enable it for break-glass DBA access:

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

  clickhouse = {
    admin = {
      enabled = true
      # password = "..."  # optional; omit to auto-generate
    }
  }
}

Its password ARN is exposed as the clickhouse_admin_credentials_secret_arn output (null when disabled). Requires chart version >= 2.0.0.

Resource sizing

Each managed workload exposes optional Kubernetes resource requests/limits via helm.<workload>.resources. Omit a workload (or a requests/limits map) to use the chart defaults — start modest in development and tune up for production.

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

  clickhouse = {
    resources = {
      requests = { cpu = "2", memory = "8Gi" }
      limits   = { cpu = "4", memory = "16Gi" }
    }
  }
  opentelemetry_collector = {
    resources = {
      requests = { memory = "2Gi" }
      limits   = { memory = "6Gi" }
    }
  }
  llm_worker = {
    resources = {
      requests = { cpu = "500m", memory = "1Gi" }
      limits   = { cpu = "2", memory = "4Gi" }
    }
  }
}

requests and limits are maps keyed by Kubernetes resource name (cpu, memory, ephemeral-storage, etc.); either can be omitted independently.

Node groups (new-cluster path)

On the new-cluster path, you can size the node groups the workloads run on:

The ClickHouse and Keeper node groups pin their AMI version by default; update it deliberately via each node group's ami_release_version — see High availability — node AMI updates.

Workload replicas

ClickHouse replicas are controlled by clickhouse_replica_count — see High availability below.

High availability

The topology inputs below deploy the standard HA shape — how it works, the dev/testing single-replica variant, and day-2 operations are covered on the High availability page.

Storage

ClickHouse data is stored on an EBS-backed persistent volume.

Network access

By default the ClickHouse and OpenTelemetry Collector Network Load Balancers are internal, but accept traffic from any source that can route to them. Restrict the source ranges to harden access:

Both NLBs run with cross-zone routing enabled and their subnet placement pinned to the module's private subnets (one subnet per AZ) — see Harden network access.

TLS

TLS is enabled by default. The OpenTelemetry Collector and ClickHouse NLB endpoints are TLS-terminated using ACM certificates that the module provisions for your otel_collector_domain and clickhouse_domain. Traffic between the Collector and ClickHouse inside the cluster is secured with certificates issued by cert-manager.

Encryption at rest

All persistent data is encrypted at rest by default:

• ClickHouse trace data — the module's gp3 and clickhouse-gp3 StorageClasses set encrypted = "true", so the EBS volumes backing ClickHouse and Keeper are encrypted.
• Credentials — every ClickHouse-user secret in AWS Secrets Manager is encrypted with a customer-managed KMS key the module creates (aws_kms_key.pipeline_secrets).
• Kubernetes secrets — EKS envelope encryption of etcd secrets is enabled by default on the new-cluster path.

Bring-your-own-key is not exposed for the Secrets Manager or EKS keys (both are module-created). The optional S3 trace-ingest buckets are customer-owned resources, so their encryption at rest is governed by your own bucket configuration.

S3 ingest (OTel Collector awss3 receivers)

In addition to its OTLP endpoints, the OpenTelemetry Collector can ingest OTLP traces from objects in one or more S3 buckets, each notified via its own SQS queue. Set helm.opentelemetry_collector.awss3_receivers with one map entry per queue/bucket pair (requires module >= 2.2.0). For every enabled entry, the module:

• Renders an awss3 receiver with component ID awss3/<key>, configured with the supplied SQS URL/region and S3 bucket/region/prefix, and appends it to the trace pipeline so the receiver is actually wired up.
• Attaches an inline policy to the otel-collector IRSA role granting sqs:ReceiveMessage/DeleteMessage/GetQueueAttributes/GetQueueUrl on every receiver's queue and s3:GetObject/GetBucketLocation on every receiver's bucket.

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

  opentelemetry_collector = {
    awss3_receivers = {
      traces = {
        sqs_queue_arn = "arn:aws:sqs:us-east-1:123456789012:otel-traces"
        sqs_queue_url = "https://sqs.us-east-1.amazonaws.com/123456789012/otel-traces"
        s3_bucket     = "acme-otel-traces"
        # enabled defaults to true
        # sqs_region / s3_region default to var.region
        # s3_prefix defaults to ""
      }
    }
  }
}

Per entry: enabled defaults to true (set false to keep the entry without rendering it); sqs_region and s3_region default to var.region; s3_prefix defaults to "" (any object in the bucket) and is normalized internally to include a single trailing / when non-empty (so "traces" and "traces/" behave identically).

Adding, changing, or removing a receiver changes the collector's rendered config, which rolling-restarts the collector Deployment on apply. (helm.opentelemetry_collector.awss3_receiver — singular — is the deprecated single-receiver form; it keeps working throughout module v2.x but use awss3_receivers for new configuration.)

Evaluation (Amazon Bedrock)

On AWS deployments the LLM worker invokes models through Amazon Bedrock. By default it targets your deployment region.