Campaign Agent

Host an agent to scan for policy violations in your environment, securely

If Campaigns is not enabled for your account. Login to Resourcely -> Campaigns -> Request Access

Once Campaigns is activated for your account, you'll need to set up the Resourcely Campaign Agent, a lightweight Docker container. The agent's primary goal is to continuously fetch your Terraform state files and scan them for guardrail violations and sends the findings back to Resourcely. For the Agent to work, it must have access to your Terraform state file storage.

Why Resourcely Campaign Agent?

Resourcely places a high priority on the security of customers' state files. For that reason, the Campaign Agent proxy scanner is designed to operate entirely within the customer's environment. This approach ensures that the state file is scanned locally using the resourcely-cli, maintaining strict data security. Any findings are securely sent back to Resourcely, without granting direct access to the customer's state file.

Setting up Resourcely Campaign Agent

Step 1: Deploying Resourcely Campaign Agent

The Resourcely Campaign agent needs to authenticate with both ngrok and Resourcely. To do so, the following environment variables should be supplied.

a. Obtaining Environment Variables

The agent requires the following environment variables for authentication. to obtain RESOURCELY_NGROK_TUNNEL_SEED and RESOURCELY_NGROK_TOKEN login to Resourcely → Settings → Campaign settings → update settings → Provision ngrok.

provision ngrok to create necessary environment variables

seed and token required to setup the campaigns agent

Please copy both RESOURCELY_NGROK_TUNNEL_SEED and RESOURCELY_NGROK_TOKEN as you will not be able to retrieve them again if you navigate away from the page.

Page after ngrok environment variables are created.

For the RESOURCELY_API_TOKEN (Generate this in Resourcely: Settings → Generate API Token → CI Runner → Generate Token)

Optional Environment Variables

• SPACELIFT_API_TOKEN (used for Spacelift state integration)

• TF_API_TOKEN (used for HCP Terraform state integration)

(b) Networking Configuration

Ensure the following egress rules are configured for the container running the agent:

• Port 443 to tunnel.<region>.proxy.resourcely.io (Regions: in, us, us-cal-1, eu, au, ap, jp).

• Port 443 to api.resourcely.io.

(c) Deployment Options

Next you will have two options to deploy the container, either Kubernetes route or docker-compose:

Option 1: Kubernetes

# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  creationTimestamp: null
  labels:
    app: campaigns-agent
  name: campaigns-agent
spec:
  replicas: 1
  selector:
    matchLabels:
      app: campaigns-agent
  strategy: {}
  template:
    metadata:
      creationTimestamp: null
      labels:
        app: campaigns-agent
    spec:
      containers:
      - image: ghcr.io/resourcely-inc/campaigns-agent:latest
        name: campaigns-agent
        env:
          - name: RESOURCELY_NGROK_TUNNEL_SEED
            value: <RESOURCELY_NGROK_TUNNEL_SEED>
          - name: RESOURCELY_NGROK_TOKEN
            value: <TOKEN>
          - name: RESOURCELY_API_TOKEN
            value: <TOKEN>

# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - deployment.yaml

Option 2: Docker Compose

You can use docker-compose.yml to run the container with the required environment variables and configurations, similar to what’s specified in the Kubernetes deployment.yaml file:

version: '3.8'

services:
  campaigns-agent:
    image: ghcr.io/resourcely-inc/campaigns-agent:latest
    container_name: campaigns-agent
    environment:
      - RESOURCELY_NGROK_TUNNEL_SEED=<RESOURCELY_NGROK_TUNNEL_SEED>
      - RESOURCELY_NGROK_TOKEN=<TOKEN>
      - RESOURCELY_API_TOKEN=<TOKEN>
    restart: unless-stopped

Replace the placeholders in angle brackets (<...>) with your actual values. Now run:

docker-compose up -d

Directly with Docker

docker run -d \
  --name campaigns-agent \
  -e RESOURCELY_NGROK_TUNNEL_SEED=<RESOURCELY_NGROK_TUNNEL_SEED> \
  -e RESOURCELY_NGROK_TOKEN=<TOKEN> \
  -e RESOURCELY_API_TOKEN=<TOKEN> \
  ghcr.io/resourcely-inc/campaigns-agent:latest

Step 2: Configuration .resourcely.yaml Changes

.resourcely.yaml Setup

• For all environments that have the campaigns-agent configured, the last piece is to ensure that the source for the state file is associated with the config root in the .resourcely.yaml.
• For a config root to be configured for campaigns, it will need to have the following block. If the config root has multiple environments, then it needs this block in each environment, similarly to how context is managed.

# Required
version: "2"

# Array of Terraform config roots that Resourcely should care about
terraform_config_roots:
  -
    name: basic
    default_file: main.tf
    path: .
    skip: false
    campaign_config:
      state_file_config:
        s3:
          path: s3://campaigns-terraform-state/terraform.tfstate

Make sure to run "queue scan" when you update your resourcely.yaml file

For other state file support check out State File Support

Step 3: Validating the setup

Once you set everything, you can confirm that campaigns is configured by

• Navigate to Metrics → Integrations.

• Confirm all integrations are marked green.

Next steps

Congratulations! Your next step is to create your Remediate policy violations in existing infrastructure, and then Remediate Resources!