📝

Prerequisites

1. You have a GCP project with administrative access.
2. Terraform (>= 1.9) is installed with GCP authentication configured.
3. kubectl is installed for cluster access.
4. You are an Account Owner in Monte Carlo.

This guide walks through deploying the Generic Agent on GCP using GKE (Google Kubernetes Engine) with the monte-carlo-data/mcd-k8s-agent/google Terraform module. The module provisions all required infrastructure — including VPC, GKE cluster, GCS storage, Secret Manager, and IAM — and deploys the agent via Helm.

Architecture

The diagram below shows the GCP-specific deployment architecture. For a general overview of how the Generic Agent works, see the Architecture section on the main page.

The agent runs as a pod in a GKE cluster and connects to:

• GCS Bucket — object storage for sampling and temporary data during operations.
• Secret Manager — stores the agent token and integration credentials, synced to the cluster via External Secrets Operator.
• Customer Integrations — the data sources (e.g. BigQuery, Snowflake) being monitored by Monte Carlo.

Provider Configuration

This module does not configure the google provider — your root module must do so. At minimum, set the target project and region:

provider "google" {
  project = "my-gcp-project"
  region  = "us-central1"
}

The module applies Monte Carlo agent labels to resources directly. To add your own labels alongside these, use the custom_default_tags variable.

Steps

1. Register the Agent

2. Deploy the Agent

2.1 Configure the Terraform Module

📘

Set backend_service_url to the Public endpoint shown in the Agent Service section of the Account Information page in Monte Carlo.

📘

Check Docker Hub for the latest available chart version and update the helm.chart_version value accordingly.

Agent token secret

You must configure the agent token secret using one of two options:

Option 1 — Provide credentials at deploy time (recommended): The module creates and populates the secret in GCP Secret Manager.

token_credentials = {
  mcd_id    = var.mcd_id
  mcd_token = var.mcd_token
}

Define the variables in a terraform.tfvars file:

mcd_id    = "your-mcd-id"
mcd_token = "your-mcd-token"

Option 2 — Use a pre-existing secret: Point the module to an existing secret in GCP Secret Manager by name. The secret value must be a JSON object with the following format:

{
  "mcd_id": "<your-mcd-id>",
  "mcd_token": "<your-mcd-token>"
}

token_secret = {
  create = false
  name   = "my-existing-secret-name"
}

Full deployment (new VPC and cluster)

This is the simplest option — the module creates all infrastructure from scratch:

provider "google" {
  project = "my-gcp-project"
  region  = "us-central1"
}

module "mcd_agent" {
  source = "monte-carlo-data/mcd-k8s-agent/google"

  project_id          = "my-gcp-project"
  location            = "us-central1"
  backend_service_url = "<backend_service_url>"

  token_credentials = {
    mcd_id    = var.mcd_id
    mcd_token = var.mcd_token
  }

  helm = {
    chart_version = "0.0.2"
  }
}

Existing VPC

If you already have a VPC, provide the network and subnetwork IDs:

provider "google" {
  project = "my-gcp-project"
  region  = "us-central1"
}

module "mcd_agent" {
  source = "monte-carlo-data/mcd-k8s-agent/google"

  project_id          = "my-gcp-project"
  location            = "us-central1"
  backend_service_url = "<backend_service_url>"

  helm = {
    chart_version = "0.0.2"
  }

  networking = {
    create_network         = false
    existing_network_id    = "projects/my-gcp-project/global/networks/my-vpc"
    existing_subnetwork_id = "projects/my-gcp-project/regions/us-central1/subnetworks/my-subnet"
  }
}

Existing GKE cluster

If you already have a GKE cluster, the module can deploy the agent into it:

provider "google" {
  project = "my-gcp-project"
  region  = "us-central1"
}

module "mcd_agent" {
  source = "monte-carlo-data/mcd-k8s-agent/google"

  project_id          = "my-gcp-project"
  location            = "us-central1"
  backend_service_url = "<backend_service_url>"

  helm = {
    chart_version = "0.0.2"
  }

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

  networking = {
    create_network = false
  }
}

Infrastructure only (manual Helm deployment)

To provision GCP infrastructure without deploying the agent via Helm — useful if you want to manage the Helm release separately:

provider "google" {
  project = "my-gcp-project"
  region  = "us-central1"
}

module "mcd_agent" {
  source = "monte-carlo-data/mcd-k8s-agent/google"

  project_id          = "my-gcp-project"
  location            = "us-central1"
  backend_service_url = "<backend_service_url>"

  helm = {
    chart_version = "0.0.2"
    deploy_agent  = false
  }
}

output "helm_values" {
  value     = module.mcd_agent.helm_values
  sensitive = true
}

After applying, use the helm_values output as your values.yaml and follow the Helm deployment steps in the Kubernetes deployment guide.

2.2 Deploy

terraform init && terraform apply

Additional module inputs, options, and defaults can be found in the module documentation.

2.3 Verify

Configure kubectl access to the cluster:

gcloud container clusters get-credentials <cluster_name> --region <location> --project <project_id>

Check the agent pod is running:

kubectl get pods -n mcd-agent
kubectl logs -n mcd-agent -l app=mcd-agent --tail=30

Run the reachability test to confirm the agent can communicate with the Monte Carlo platform:

kubectl exec -n mcd-agent deploy/mcd-agent-deployment -- \
  curl -s -X POST localhost:8080/api/v1/test/reachability

A successful response contains "ok": true.

3. Enable the Agent

After verifying the agent is running, click Enable on the agent registration screen.

📘

If you've navigated away from the registration screen, go to Settings > Deployments, select your agent, and click Enable.

Once validations pass, click Enable in the validations dialog to activate the agent.

Outputs

The module exposes the following outputs:

FAQs

Does the agent require inbound network access?

No. The Generic Agent is egress-only. All connections are initiated from the agent to the Monte Carlo platform. No inbound connectivity to the agent is required.

Can I customize the Helm values?

Yes. Use the custom_values variable to merge additional values with the module-generated Helm configuration. This accepts any map matching the chart's values.yaml schema.

How do I add credentials for data source integrations?

1. Create a secret in GCP Secret Manager with the integration credentials. See the Self-Hosted Credentials documentation for the JSON format for each integration type.

   Bash

   echo -n '{"connect_args": { ... }}' | \
     gcloud secrets create mcd-integrations-<integration> --data-file=-

2. Grant the agent's service account access to the secret. You can find the service account email in the Terraform output service_account_email.

   Bash

   gcloud secrets add-iam-policy-binding mcd-integrations-<integration> \
     --member="serviceAccount:<service_account_email>" \
     --role="roles/secretmanager.secretAccessor"

3. Register the integration in Monte Carlo. You can do this via the UI (see Self-Hosted Credentials) or via the CLI:

   Bash

   montecarlo integrations add-self-hosted-credentials-v2 \
     --connection-type <integration> \
     --self-hosted-credentials-type GCP_SECRET_MANAGER \
     --gcp-secret <secret_name>

How do I scale the agent?

agent = {
  replica_count = 3
}

custom_values = {
  container = {
    opsRunnerThreadCount = "36"
  }
}

custom_values = {
  container = {
    resources = {
      requests = {
        cpu    = "500m"
        memory = "512Mi"
      }
      limits = {
        cpu    = "2"
        memory = "2Gi"
      }
    }
  }
}

custom_values = {
  autoscaling = {
    enabled                          = true
    minReplicas                      = 1
    maxReplicas                      = 5
    targetCPUUtilizationPercentage   = 70
  }
}

How do I upgrade the agent?

agent = {
  image = "montecarlodata/agent:1.0.0-generic"
}

helm = {
  chart_version = "0.1.0"
}

How do I monitor the agent?

You can monitor the agent using Google Cloud Monitoring for GKE. The agent exposes a health endpoint at /api/v1/test/healthcheck that can be used for liveness and readiness probes.

How do I rotate the agent token?

1. Update the secret in GCP Secret Manager:

   Bash

   echo -n '{"mcd_id":"<new-mcd-id>","mcd_token":"<new-mcd-token>"}' | \
     gcloud secrets versions add mcd-agent-token --data-file=-

2. Force sync the Kubernetes secret from External Secrets Operator:

   Bash

   kubectl annotate externalsecret -n mcd-agent --all \
     force-sync=$(date +%s) --overwrite

3. Restart the agent services:

   Bash

   kubectl rollout restart deployment mcd-agent-deployment -n mcd-agent
   kubectl rollout restart daemonset logs-collector metrics-collector -n mcd-agent