Directors: Updates

DataStream supports both automatic and manual update methods for Directors, Clusters, and Agents. Organization-level defaults can be overridden at the component level through Custom Policy settings.

Update Modes

Mode	Description
Manual	Administrator manually downloads the latest Director/Agent version and starts the installation
Auto	System automatically handles updates based on configured method

Update Methods

When Auto mode is selected, three methods are available:

Method	Description
User Action	Updates available in GUI; administrator confirms and triggers
Immediate	Updates applied automatically when available
Scheduled	Updates applied according to cron or interval schedule

Scheduling Options

When using the Scheduled method, two scheduling approaches are available:

Cron-Based Scheduling:

Standard cron expressions for precise timing control:

0 2 * * 0    # Every Sunday at 2:00 AM
0 3 * * 1-5  # Weekdays at 3:00 AM
0 0 1 * *    # First day of each month at midnight

Interval-Based Scheduling:

Duration-based intervals for regular polling:

1h     # Check every hour
30m    # Check every 30 minutes
24h    # Check daily

See Cron-Based Scheduling and Interval-Based Scheduling for detailed syntax.

Configuration Hierarchy

Update settings follow a three-tier hierarchy where lower levels can override higher levels:

Level	Location	Scope
Organization	Organization > Settings > Update Management	Default rules for all Directors and Agents
Director/Cluster	Fleet Management > Directors	Override organization defaults via Custom Policy
Agent	Devices > Linux/Windows	Override organization agent defaults via Custom Policy

Automatic Updates

Auto Update enables Directors to automatically update themselves when new versions become available. The feature supports immediate and scheduled update methods with built-in rollback capability and cryptographic signature verification.

Configuration

Auto Update is configured through the update section in the Director configuration:

Property	Type	Required	Description
mode	string	Y	Set to auto to enable automatic updates
method	string	Y	Update trigger method: immediate or schedule
version	string	Y	Target version to update to
cron	string	N	Cron expression for scheduled updates (schedule method only, minimum 30 seconds)
interval	duration	N	Fallback polling interval if no cron specified (default: 30s minimum)

Example Configuration:

update:
  mode: auto
  method: schedule
  version: "2.5.0"
  cron: "0 2 * * 0"  # Every Sunday at 2:00 AM

Update Methods

Immediate Method:

Triggers the update as soon as possible after configuration is applied. A 10-minute cooldown prevents rapid retry attempts if the update fails.

update:
  mode: auto
  method: immediate
  version: "2.5.0"

Schedule Method:

Updates occur according to a cron schedule or interval-based polling:

• Cron Expression: Use standard cron syntax for precise scheduling (e.g., 0 2 * * 0 for Sunday at 2:00 AM)
• Interval Fallback: If no cron is specified, updates check on the configured interval

update:
  mode: auto
  method: schedule
  version: "2.5.0"
  interval: 1h  # Check hourly

Update Process

When an update triggers, the Director performs these steps:

1. Version Check - Compares current version against configured target version
2. Service Stop - Gracefully stops the running Director service
3. Backup - Creates timestamped backup of current binary and configuration
4. Download - Retrieves new binary from Fleet management instance
5. Signature Verification - Verifies Ed25519 signature of downloaded binary
6. Deployment - Replaces current binary with new version
7. Resource Update - Updates package resources (pipelines, definitions)
8. Service Start - Restarts the Director service

If any step fails, the rollback system automatically restores the previous binary and configuration.

Health Reporting

During an update, the Director reports additional health information:

Field	Description
version	Currently running Director version
scheduled_version	Target version pending update
architecture	System architecture (amd64, arm64, etc.)
os	Operating system (windows, linux, darwin)

The scheduled version field appears in health reports after an update is triggered but before it completes, allowing monitoring systems to track pending updates.

Update Logs

Update progress is logged to the Director activity stream. Log entries include:

• Update triggered timestamp
• Download progress and completion
• Signature verification result
• Deployment success or failure
• Rollback actions (if update fails)

Security

Auto Update includes multiple security measures:

• Ed25519 Signature Verification: All downloaded binaries are verified against cryptographic signatures before deployment
• Secure Download: Binaries are downloaded over HTTPS from the Fleet management instance
• Rollback Protection: Failed updates automatically restore the previous working version
• Path Traversal Protection: Archive extraction validates paths to prevent directory escape

warning

Auto Update requires network connectivity to the Fleet management instance. Ensure firewall rules allow outbound HTTPS connections to the configured Fleet instance URL.

Manual Updates

Manual updates provide direct control over the update process, suitable for environments with strict change management requirements or air-gapped deployments.

Directors

Update Procedure:

1. Download the new Director version from VirtualMetric
2. Stop the Director service:
   • Windows: Stop-Service vmetric-director
   • Linux: systemctl stop vmetric-director
3. Backup current installation directory
4. Extract new binary and resources to installation directory
5. Start the Director service:
   • Windows: Start-Service vmetric-director
   • Linux: systemctl start vmetric-director
6. Verify version:

   ./vmetric-director -version

Clusters

Cluster updates require a rolling update strategy to maintain quorum and service availability.

Update Procedure:

1. Plan update sequence - Identify all cluster members and update order
2. Verify cluster health - Ensure all nodes are healthy before starting
3. Update one Director at a time:
   • Remove node from load balancer (if applicable)
   • Stop Director service
   • Deploy new binary and resources
   • Start Director service
   • Verify node rejoins cluster
4. Verify cluster health between each node update
5. Complete rollout - Confirm all nodes running new version

warning

Never update more than one cluster member simultaneously. Maintain quorum throughout the update process to prevent service disruption.

Agents

Agent updates are typically pushed from the managing Director. For manual updates:

Update Procedure:

1. Download the new Agent version from the managing Director or VirtualMetric
2. Stop the Agent service:
   • Windows: Stop-Service vmetric-agent
   • Linux: systemctl stop vmetric-agent
3. Backup current Agent binary
4. Deploy new binary to installation directory
5. Start the Agent service:
   • Windows: Start-Service vmetric-agent
   • Linux: systemctl start vmetric-agent
6. Verify version:

   ./vmetric-agent -version

Component Differences

Component	Update Contents	Source	Notes
Directors	Binary + Package resources	Fleet instance	Full update includes pipelines, definitions, lookups
Clusters	Rolling updates	Fleet instance	Quorum preservation required during update
Agents	Binary only	Managing Director	Lighter update package, no pipeline resources

Configuring Updates in GUI

Organization Defaults

Configure organization-wide update defaults:

1. Navigate to Organization > Settings
2. Select Update Management tab
3. Configure:
   • Update Mode: Manual or Auto
   • Update Method (Auto only): User Action, Immediate, or Scheduled
   • Schedule (Scheduled only): Cron expression or interval
4. Click Save

These settings apply as defaults to all Directors and Agents unless overridden.

Director/Cluster Custom Policy

Override organization defaults for specific Directors or Clusters:

During Creation:

1. In the Director/Cluster creation wizard, locate Update Management step
2. Enable Custom Policy toggle
3. Configure custom update settings
4. Complete creation wizard

For Existing Directors/Clusters:

1. Navigate to Fleet Management > Directors
2. Click the Director or Cluster name to open detail view
3. Locate Update Management panel
4. Enable Custom Policy toggle
5. Configure custom update settings
6. Click Save

Agent Custom Policy

Override organization defaults for specific Agents:

During Creation:

1. Navigate to Devices > Linux or Windows
2. Click Create to start device creation
3. In Update Management step, enable Custom Policy toggle
4. Configure custom update settings
5. Complete creation wizard

For Existing Agents:

1. Navigate to Devices > Linux or Windows
2. Click the Agent name to open detail view
3. Locate Update Management panel
4. Enable Custom Policy toggle
5. Configure custom update settings
6. Click Save