Agent Observability Platform: Connect to Monte Carlo

Deploy the Monte Carlo Agent and connect the platform to Monte Carlo

After installation, verify the deployment, deploy the Monte Carlo Agent, and create the ClickHouse integration in Monte Carlo. You carry out these steps yourself — work through them in order.

1. Configure cluster access

If you ran terraform apply from this same machine, you can skip this step — the module already ran aws eks update-kubeconfig during apply, so the cluster's context is in your ~/.kube/config and is current. Run the command below only when connecting from a different machine:

aws eks update-kubeconfig --name <eks_cluster_name> --region <region>

📘
This requires eks:DescribeCluster on the cluster, plus access to authenticate to it. The principal that ran terraform apply is granted cluster-administrator access automatically (enable_cluster_creator_admin_permissions = true), so the same credentials you deployed with can run the verification below. To let a different principal run kubectl, add an EKS access entry for it.

2. Verify the deployment

All components run in the montecarlo namespace. Confirm each is healthy:

Component	Command	Healthy when
ClickHouse operator	`kubectl get pods -n montecarlo -l app.kubernetes.io/name=altinity-clickhouse-operator`	Pod `Running`
ClickHouse instance	`kubectl get chi -n montecarlo`	Resource `otel`, status `Completed`
ClickHouse pod	`kubectl get pods -n montecarlo -l clickhouse.altinity.com/chi=otel`	Pod `Running`
Schema migration job	`kubectl get jobs -n montecarlo`	`clickhouse-schema-<n>` shows `COMPLETIONS 1/1`
OpenTelemetry Collector	`kubectl get pods -n montecarlo -l app.kubernetes.io/name=opentelemetry-collector`	Pod `Running`
LLM worker	`kubectl get pods -n montecarlo -l app.kubernetes.io/component=llm-worker`	Pod `Running`
TLS certificates	`kubectl get certificates -n montecarlo`	`clickhouse-server-tls` and `otel-collector-tls` show `READY True`
External secrets	`kubectl get externalsecret -n montecarlo`	`ao-clickhouse-otel-credentials` shows status `SecretSynced`

The schema migration job must reach 1/1 before the Collector and LLM worker can write data — both wait on it via an init container, so it is normal for them to sit in Init for a minute or two on a fresh install. <n> in the job name is the Helm release revision (e.g. clickhouse-schema-1).

📘
If any check above doesn't reach its healthy state, see Troubleshooting & FAQ — it covers ClickHouse pods stuck Pending, certificates not becoming Ready, external secrets not syncing, and schema-job failures.

3. Deploy the Monte Carlo Agent

All SQL from the Monte Carlo platform — for both Trace Exploration and agent monitors — flows through the Monte Carlo Agent. For this platform, the Agent runs as an AWS Lambda function in the same VPC as the EKS cluster and queries ClickHouse over its internal endpoint as the otel user.

The Agent is not deployed by the terraform-aws-ao-data-platform module — it is deployed separately with the terraform-aws-mcd-agent module. The Agent Observability-specific configuration is the ClickHouse connection: the endpoint (your clickhouse_domain) and the credentials retrieved below.

📘
You deploy and register the Agent yourself — it is a separate deployment from the data platform, not something Monte Carlo runs in your account. Make sure the Agent's Lambda is in (or can route to) the same VPC and can reach the ClickHouse endpoint. Your Monte Carlo representative can help you obtain the Agent's registration values.

4. Retrieve credentials and endpoints

Monte Carlo connects to ClickHouse as the otel user. Its password is stored in AWS Secrets Manager; the module exposes the secret's ARN as the clickhouse_otel_credentials_secret_arn output. Retrieve it:

aws secretsmanager get-secret-value \
  --secret-id "$(terraform output -raw clickhouse_otel_credentials_secret_arn)" \
  --query SecretString --output text

You enter the following when you create the ClickHouse integration in the next step:

Value to provide	Source
ClickHouse endpoint	The `clickhouse_domain` you configured (e.g. `clickhouse.acme.com`)
ClickHouse port	`8443` (HTTPS)
ClickHouse database	`otel_traces`
ClickHouse username	`otel`
ClickHouse password	The value retrieved above from `clickhouse_otel_credentials_secret_arn`

🔒
Treat these credentials as secrets — avoid printing them into shared logs or terminals, and if you need to share them (for example with a teammate or your Monte Carlo representative), use a secure channel. Note that otel is a read/write user; a dedicated least-privilege user is planned for a future release.

5. Create the ClickHouse integration in Monte Carlo

With the Agent deployed (step 3) and the connection values in hand (step 4), create the ClickHouse integration in Monte Carlo. Monte Carlo reaches ClickHouse through the Agent you deployed, so this is the step that ties the platform to your account. Creating the integration runs a connection check — when it succeeds, you have confirmation that the endpoint, port, credentials, and database are all wired correctly.

📘
Monte Carlo's general ClickHouse integration guide covers connecting Monte Carlo to a ClickHouse warehouse. It does not strictly apply to this platform: you do not need to create a read-only user for the connection — the otel user is already provisioned with the permissions the Agent needs.

Next steps

Tune retention, users, TLS, and sizing in the Configuration reference.
Hit a problem during verification or onboarding? See Troubleshooting & FAQ.