Create a Fleet Policy

Fleet Policies are the heart of CollectorCtrl. They let you define an OpenTelemetry Collector configuration once and push it to any subset of your fleet — without SSH, without restarts, and without config drift.

What You'll Learn

• How to create a policy with label-based targeting
• How policies compile into Effective Configs
• How the Supervisor applies configs via hot-reload
• How to verify the deployment succeeded

Time: ~10 minutes

Before You Start

Make sure you have:

• A running CollectorCtrl Management Server
• At least one Supervisor agent connected and showing as Healthy in the Fleet Overview
• An API token (if you want to test via the REST API)

Step 1: Navigate to Policies

1. Log into the CollectorCtrl dashboard
2. Click Fleet → Policies in the left sidebar
3. Click New Policy

Step 2: Name Your Policy

Give your policy a descriptive name:

Name: production-trace-pipeline
Description: Standard trace collection for production API servers

Step 3: Define the Target Selector

This is where you choose which agents receive this config. You have two options:

Option A: Target All Agents

Use an empty selector to apply to every connected agent:

{}

Option B: Target by Labels (Recommended)

Target only agents matching specific labels. For example, only production Linux servers:

{
  "matchLabels": {
    "env": "production",
    "host.os": "linux"
  }
}

Or use matchExpressions for more complex rules:

{
  "matchLabels": {
    "env": "production"
  },
  "matchExpressions": [
    {
      "key": "region",
      "operator": "In",
      "values": ["us-east", "us-west"]
    }
  ]
}

How labels work: Agents report labels through OpAMP based on resource attributes. Common labels include env, host.os, service.name, and any custom attributes you configure on your collectors.

Step 4: Write the Main Config

Paste your OpenTelemetry Collector YAML configuration. This is the config that will be pushed to matching agents.

Here's a standard trace pipeline example:

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:
    timeout: 1s
    send_batch_size: 1024
  memory_limiter:
    limit_mib: 512
    spike_limit_mib: 128

exporters:
  otlp:
    endpoint: datadog.internal:4317
    tls:
      insecure: false
  debug:
    verbosity: detailed

extensions:
  health_check:
    endpoint: 0.0.0.0:13133

service:
  extensions: [health_check]
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [otlp, debug]

Step 5: Set the Rollout Strategy

Choose how aggressively to deploy:

For your first policy, use Immediate to see results faster.

Step 6: Publish the Policy

Click Publish. CollectorCtrl will:

1. Compile the Effective Config by merging policy + overrides
2. Run a dry-run validation check
3. Calculate the config hash
4. Push the config to all matching agents via OpAMP
5. The Supervisor hot-reloads the collector (no restart)

Step 7: Verify the Deployment

In the Dashboard

1. Go to Fleet → Overview
2. Look at the Config column for your agents
3. It should show Applied (green) within a few seconds

Check Agent Logs

On a target agent, check the Supervisor log:

$sudo journalctl -u collectorctrl-supervisor -n 50 --no-pager

PS >Get-Content 'C:\ProgramData\CollectorCtrlSupervisor\supervisor.log' -Tail 50

You should see lines like:

[OpAMP] Received remote config
[Config] Writing effective config to /etc/otelcol/config.yaml
[HotReload] Sending SIGHUP to collector process
[Health] Collector healthy after reload

Via REST API

$curl -H 'Authorization: Bearer cct_your_token' \\
$  https://your-server:4321/api/agents \\
$  | jq '.[] | {name: .hostname, config_status: .effective_config_hash}'

Understanding Config Compilation

CollectorCtrl uses a three-layer merge to produce the final config:

Policy Template (global)
    ↓ merge
Override Config (node-specific)
    ↓ compile
Effective Config (what the collector runs)

Override Config (Node-Specific Tweaks)

If an agent needs a slight variation (e.g., different endpoint port), you can set an Override Config on that specific agent. The override is deep-merged on top of the policy.

Example override — change just the gRPC endpoint port:

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:5317

⚠️ Important: YAML lists (arrays) are replaced entirely during merge, not appended. If your policy defines receivers: [otlp, prometheus] and you want to add hostmetrics, you must re-specify the full list in the override.

Version History

Every time you edit and publish a policy, CollectorCtrl creates an immutable snapshot:

1. Go to Fleet → Policies
2. Click on your policy
3. Switch to the History tab
4. View any past version, compare diffs, or click Rollback to revert

Next Steps

• Perform a Canary Rollout — test changes safely on a subset
• Upgrade Agents Fleet-Wide — push new Supervisor versions
• Read about Drift Prevention — how Supervisor guards your configs