Agent Observability Platform: Connect to Monte Carlo (Azure)

Connect your Azure Agent Observability data platform to Monte Carlo

☁️
This page covers Azure. Also available for AWS and GCP.

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 az aks get-credentials and kubelogin convert-kubeconfig during apply, so the cluster's context is in your ~/.kube/config and is current. Run the commands below only when connecting from a different machine:

az aks get-credentials --resource-group <resource_group_name> --name <aks_cluster_name>
kubelogin convert-kubeconfig -l azurecli

📘
The principal that ran terraform apply is granted cluster-administrator access automatically (an "Azure Kubernetes Service RBAC Cluster Admin" role assignment), so the same credentials you deployed with can run the verification below. To let a different principal run kubectl, grant it an AKS RBAC role assignment on the cluster. Local (certificate-based) cluster accounts are disabled by default — all access goes through Entra ID via kubelogin.

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 pods	`kubectl get pods -n montecarlo -l clickhouse.altinity.com/chi=otel`	One pod per replica, all `Running`
Keeper ensemble	`kubectl get chk -n montecarlo`	Resource `otel`, status `Completed`
Keeper pods	`kubectl get pods -n montecarlo -l clickhouse-keeper.altinity.com/chk=otel`	One pod per voter, all `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`
Gateway and routes	`kubectl get gateway,httproute -n montecarlo`	Gateway `PROGRAMMED True`; both HTTPRoutes accepted
Gateway TLS certificates	`kubectl get certificate gateway-otel-tls gateway-clickhouse-tls -n montecarlo`	Both show `READY True`
External secrets	`kubectl get externalsecret -n montecarlo`	Each `ao-clickhouse-*-credentials` secret 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).

The Gateway certificates are issued by Let's Encrypt via DNS-01 validation, so they can take a few minutes to become READY on a fresh install while the DNS challenge propagates.

📘
A ClickHouse pod showing Running and Ready confirms it can serve writes — it does not confirm replication has caught up. To verify replication health on the HA topology, check system.replicas — see Verifying cluster health.

📘
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. On Azure, the Agent is the containerized agent (montecarlodata/agent:latest-azure) running on Azure Functions, deployed with the terraform-azurerm-mcd-agent module — see Azure agent deployment for the full agent setup.

The Agent is not deployed by the terraform-azurerm-ao-data-platform module. The Agent Observability-specific configuration is the ClickHouse connection: the Agent queries ClickHouse over HTTPS as the monte_carlo user, at the endpoint you configured as clickhouse_domain. That endpoint is the platform's managed Gateway on an internal load balancer, so the Agent's Function App must be VNet-integrated with a network path to it — integrate it into a subnet in the platform's VNet (or a peered VNet) that can reach the Gateway's private IP, and make sure any gateway.allowed_source_ranges restriction admits that subnet.

📘
You deploy and register the Agent yourself — it is a separate deployment from the data platform, not something Monte Carlo runs in your subscription. 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 monte_carlo user — a least-privilege identity that reads telemetry and appends only to the evaluation job queue. Its password is stored in Azure Key Vault; the module exposes the secret's ID as the clickhouse_monte_carlo_credentials_secret_id output. Retrieve it:

az keyvault secret show \
  --id "$(terraform output -raw clickhouse_monte_carlo_credentials_secret_id)" \
  --query value --output tsv

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 — the Gateway is HTTP-only; ClickHouse's native TCP protocol is not exposed)
ClickHouse database	`otel_traces`
ClickHouse username	`monte_carlo`
ClickHouse password	The value retrieved above from `clickhouse_monte_carlo_credentials_secret_id`

❗️
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. monte_carlo is a least-privilege user: it can read telemetry and append to the evaluation job queue, but cannot write telemetry, run DDL, or manage access.

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 user for the connection — the purpose-built monte_carlo user is already provisioned with exactly 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.

Updated 1 day ago

Did this page help you?