👍

This is a more advanced deployment, which can require additional setup, monitoring, and maintenance. If you want to use an agent, Monte Carlo generally recommends using the cloud-native options whenever possible. See the documentation for: AWS, Azure or GCP.

About

Monte Carlo supports running the Agent on generic infrastructure (sometimes referred to as "bare metal"). Any infrastructure capable of running a Docker image can be used to run the Agent.

Please note that running the Agent on more generic infrastructure requires a proxy to authenticate communication between the Monte Carlo platform and the deployed Agent. Supported authentication mechanisms to the proxy include OAuth with optional mTLS.

To get started please review the requirements and then follow the steps under the relevant subsection:

• AWS Deployment

Currently, this setup is supported only in the AWS Cloud. However, let us know if you would be interested in support for other clouds like Azure or GCP. FAQs can be found here.

Requirements

• Monte Carlo Role and Subscription: You must have the Account Owner role in Monte Carlo. Additionally, your account must be subscribed to either the Scale or Enterprise tier with with the Advanced Networking add-on.
• AWS Admin: Administrative access to AWS is necessary for the setup.
• Additional Admin Roles: Depending on the specific integration, you may also need administrative rights. Additionally, please note that certain integrations require specific subscription tiers and configurations with their respective vendors. Refer to your vendor's documentation for more details.

AWS Deployment

📝

Prerequisites

1. You are an admin in AWS (for step 1).
2. You have (or can deploy) a proxy configured to enforce OAuth authentication (for step 2).
3. You are an Account Owner (for step 3).

Additionally, your account must be subscribed to either the Scale or Enterprise tier with the Advanced Networking add-on.

The Monte Carlo Agent can be deployed to AWS infrastructure such as ECS, EKS, or EC2. It can run as a Docker image on the chosen AWS infrastructure but requires a proxy to handle authentication.

This is an alternative to using AWS Lambda for running the Agent. Learn more about that deployment option here.

1. Deploy the Agent

You can deploy the Agent using the IaC tool of your choice. We have provided a CloudFormation sample with ECS.

ℹ️

The following quick-create link can deploy the agent on any supported region in your AWS account:

If you need to share with a colleague or first review the template you can download a copy here (source).

Configuration

Your deployment will vary based on the infrastructure and environment you choose for running and managing the Agent Docker image. See the CloudFormation template above as an example.

However, general requirements and recommendations for operating the Agent are provided below.

Agent Image

When deploying the Agent to generic AWS infrastructure, use the image tag latest-aws-generic.

docker.io/montecarlodata/agent:latest-aws-generic

You can review the Agent resources and code here.

Agent Resources and Infrastructure

The resources required for running the Agent will vary depending on the chosen AWS infrastructure.

If using ECS, Monte Carlo recommends starting with these allocations:

• vCPU: 2
• Memory: 6gb
• Container instances: 1+
• Gunicorn workers: 5
• Gunicorn threads: 8

You also need to chose a port to expose, for example 8081, and create a port mapping using TCP/HTTP protocols.

As additional Monte Carlo integrations and monitors are created, you may need to scale these resources to optimize performance. Increasing the number of task instances in ECS is supported.

Additional Resources and Infrastructure

The following AWS resources might also be necessary:

• One S3 bucket. This is required. The S3 bucket will serve as the Agent's data store. A good starting point would be the configuration outlined here. Monte Carlo strongly recommends not sharing this S3 bucket with other jobs, as the agent might overwrite existing data. We also strongly recommend that the bucket is private and has expiration lifecycles set.
• One CloudWatch log group. This is optional, but is helpful for triaging issues with integrations.
• One IAM role, attached to the infra where the Agent is running, granting permission to the mentioned bucket and log group (if applicable). This is required. See policies below (note that the values need to be filled in):
  S3 Policy (Required)Log Policy (Optional)

  {
      "Version": "2012-10-17",
      "Statement": [
          {
              "Sid": "StorageBucketAccess",
              "Effect": "Allow",
              "Action": [
                  "s3:PutObject",
                  "s3:GetObject",
                  "s3:DeleteObject",
                  "s3:ListBucket",
                  "s3:GetBucketPublicAccessBlock",
                  "s3:GetBucketPolicyStatus",
                  "s3:GetBucketAcl"
              ],
              "Resource": [
                  "arn:aws:s3:::<MCD_STORAGE_BUCKET_NAME>",
                  "arn:aws:s3:::<MCD_STORAGE_BUCKET_NAME>/*"
              ]
          }
      ]
  }

  {
      "Version": "2012-10-17",
      "Statement": [        
          {
              "Sid": "FilterLogGroupLogs",
              "Effect": "Allow",
              "Action": [
                  "logs:FilterLogEvents"
              ],
              "Resource": [
                  "<MCD_LOG_GROUP_ID>*"
              ]
          }
      ]
  }

• One VPC is required to connect your infrastructure and send requests from your proxy. This setup will vary based on your organization's needs. Generally, Monte Carlo recommends keeping minimal access on private subnets and attaching VPC endpoints for AWS services such as S3 and CloudWatch Logs. The integrations you want to connect with Monte Carlo also need to be reachable from this VPC, such as warehouses, databases, and tools.

Agent Environment Variables and Other Configuration

When configuring the agent image the following environment variables are required:

Note that the Agent provides a health check endpoint at both the root route (/) and the route /health. This can be useful for validating health or distributing traffic when using a load balancer or other mechanisms.

For instance, you can configure a health check command as follows:

CMD-SHELL,curl -f http://localhost:[PORT]/ || exit 1

2. Configure your Proxy

An HTTPS proxy is required in front of the Agent when running on generic AWS infrastructure. This proxy should manage authentication to the Agent. Monte Carlo currently supports two OAuth authentication schemes:

• Client credentials
• Username/password

When registering the Agent with your Monte Carlo account (step 3), you will provide either the client_id/client_secret or username/password credential combinations. This allows Monte Carlo to authenticate with your proxy to access the Agent.

Additionally, Monte Carlo supports optionally using mTLS for communication from the platform to the Agent via your proxy. When registering the Agent, you can provide the client certificate and private key that Monte Carlo should use to establish mTLS communication with your proxy to access the Agent.

Furthermore, Monte Carlo requires that your proxy supports long-running operations (approximately 15-minute requests) and large payloads. We have provided an example of configuring an Apigee proxy below.

By default, communication between the Monte Carlo platform and your proxy will be over the public internet, but you can use PrivateLink via an AWS Endpoint Service if preferred. See the documentation for further details on this option.

Examples

Apigee

Example of a TargetEndpoint configuration for a simple Apigee proxy, using the deployed Agent as the target:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TargetEndpoint name="default">
  <Description/>
  <FaultRules/>
  <PreFlow name="PreFlow">
    <Request>
      <Step>
        <!-- Verify OAuth access token -->
        <Name>OAuthV2-VerifyToken</Name>
      </Step>
    </Request>
    <Response/>
  </PreFlow>
  <PostFlow name="PostFlow">
    <Request/>
    <Response/>
  </PostFlow>
  <Flows/>
  <HTTPTargetConnection>
    <Properties>
	    <!-- Increase timeout defaults to support longer queries -->
      <Property name="api.timeout">900000</Property>
      <Property name="keepalive.timeout.millis">900000</Property>
      <Property name="io.timeout.millis">900000</Property>
    </Properties>
    <!-- IP/DNS of MC Agent in AWS -->
    <URL>http://my-aws-generic-agent.us-east-1.elb.amazonaws.com</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

Note the timeout/keepalive property overrides; these are required to support long-running queries from the Monte Carlo platform.

3. Register the Agent

After deploying the agent and configuring your proxy you can register via the Monte Carlo CLI or API.

After this step is complete, all supported integrations using this deployment will automatically use this agent (and object store for troubleshooting and temporary data). You can add these integrations as you normally would using Monte Carlo's UI wizard or CLI.

CLI

Use montecarlo agents register-aws-proxied-agent to register.

See reference documentation here. And see here for how to install and configure the CLI. For instance:

montecarlo agents register-aws-proxied-agent \
 --proxy-endpoint <proxy agent endpoint> \
 --auth-url <proxy oauth endpoint> \
 --authentication <oauth_client_credentials|oauth_password> \
 --username <oauth username> \
 --password <oauth password> \
 --collector-id <collector service id allocated to your account> \
 --client-certificate <path/to/client.crt> \
 --private-key <path/to/client.private.pem> \
 --deployment-type generic

Once the Agent is registered, you can test connectivity and operation from the platform in your Monte Carlo account here. Click the three-dot menu on your newly registered Agent and select “Test” from the popover menu. The validations should pass.

API

You can use the API to register either by generating an API token or from the UI via the API Explorer.

To open this directly in the API explorer you can use the following: https://mc-d.io/proxy-reg (fill in the variables).

mutation createOrUpdateAgent(
  $agentId: UUID,
  $dataCollectorId: UUID,
  $credentials: JSONString,
  $endpoint: String,
  $agentType: AgentTypeEnum,
  $authType: AuthTypeEnum,
  $storageType: StorageTypeEnum,
  $platform: PlatformTypeEnum,
  $dryRun: Boolean
) {
  createOrUpdateAgent(
    agentId: $agentId,
    dataCollectorId: $dataCollectorId,
    credentials: $credentials,
    endpoint: $endpoint,
    agentType: $agentType,
    authType: $authType,
    storageType: $storageType,
    platform: $platform,
    dryRun: $dryRun
  ) {
    agentId
    validationResult {
    success
    validationName
    }
  }
}

{
  "agent_type": "REMOTE_AGENT",
  "endpoint": "<proxy agent endpoint>",
  "storage_type": "S3",
  "platform": "AWS_GENERIC",
  "auth_type": "<oauth_client_credentials|oauth_password>",
  "dry_run": false,
  "data_collector_id": "<collector service id allocated to your account>",
  "credentials": "{\"auth_url\": \"<proxy oauth endpoint>\", \"username\": \"<username>\", \"password\": \"<password>\", \"client_certificate\": \"base64 encoded client certificate\", \"private_key\": \"base64 encoded private key\"}"
}

Once the Agent is registered, you can test connectivity and operation from the platform in your Monte Carlo account here. Click the three-dot menu on your newly registered Agent and select “Test” from the popover menu. The validations should pass.

FAQs

What regions does the Agent support?

You can deploy an agent in the following AWS regions:

Can I review agent resources and code?

Absolutely! You can find details here:

How do I upgrade the agent?

Monte Carlo releases new agent image versions to add new features, fix bugs, and patch CVEs. It's important to keep your agent up to date. When deployed on generic infrastructure, automatic remote upgrades of the agent are not supported. Managing updates is part of your shared responsibility.

To upgrade the agent, simply update the tag of the agent's Docker image used in your deployment. For example, if your current deployment is using this image reference:

docker.io/montecarlodata/agent:1.3.5-aws-generic

You could update to the newer version by modifying the tag to this:

docker.io/montecarlodata/agent:1.3.6-aws-generic

Next, simply trigger an update or deployment of your service. This will vary depending on what infrastructure you're using.

Monte Carlo also offers the 'latest' image tags (e.g. latest-aws-generic ) which can be used to ensure you're always running the latest image. However, to upgrade these images sometimes you might have to "force" a deployment on your infrastructure so the latest image is pulled from Dockerhub.

You can confirm the agent was upgraded successfully by checking your Monte Carlo account here.

How do I scale the agent?

As you onboard integrations and create monitors in your Monte Carlo account it might become necessary to scale up the agent to optimize performance. Monte Carlo supports scaling the agent by increasing the number of internal Gunicorn workers and threads along with increasing CPU and memory of a single instance or by scaling the number of instances.

To increase the number of Gunicorn workers and threads, update these environment variables:

• GUNICORN_WORKERS (default: 5)
• GUNICORN_THREADS (default: 8)

After triggering a deployment of the agent with the new environment variables values, monitor your agent's resource usage. Increasing CPU or memory might be required.

Increasing the number of instances of the agent is also a valid scaling option. In AWS ECS this can be accomplished by increasing the number of task instances of your service. In this case the AWS ALB will distribute the load between the instances, optimizing the performance of your agent.

How do I monitor the Agent?

The Agent automatically generates a log of all operations, which can from CloudWatch.

Operational metrics can similarly be retrieved from CloudWatch metrics (or the infra console).

How do I migrate from a native agent to this deployment type?

👍

These steps assume you have already completed steps #1 and #2, which involve deploying the agent and creating the proxy. See the docs here for further details on those steps.

First, find your existing agent's identifier using the list command on the Monte Carlo CLI (see here for how to install and configure the CLI):

montecarlo agents list

Next, run the register-aws-proxied-agent command using the agent-id from above to migrate your agent from a native deployment to a generic one. Be sure to modify the command to include the authentication and mTLS options required for your agent’s generic deployment.

montecarlo agents register-aws-proxied-agent \
 --proxy-endpoint <proxy agent endpoint> \
 --auth-url <proxy oauth endpoint> \
 --authentication <oauth_client_credentials|oauth_password> \
 --username <oauth username> \
 --password <oauth password> \
 --collector-id <collector service id allocated to your account> \
 --client-certificate <path/to/client.crt> \
 --private-key <path/to/client.private.pem> \
 --deployment-type generic \
 --agent-id <agent identifier>

What features are not supported with this deployment type?

The following are not supported:

• Functionality that uses pre-signed URLs, such as generating breach download CSVs.
• Remote upgrading.

How do I check the reachability between Monte Carlo and the Agent?

Please refer to the documentation here.

How do I debug connectivity between the Agent and my integration?

Please refer to the documentation here.