Drift Detection

Overview

Configuration drift is a difference between what Veltrix deployed and what is actually live on the target system, typically because someone changed it by hand outside the pipeline. Drift detection is the Monitor stage of the pipeline: after a configuration is deployed, Veltrix keeps checking that the live system still matches it.

How a check works

• Veltrix takes each configuration's latest successful deployment in each environment. The desired state is the snapshot frozen at deploy time, not the current draft, so undeployed edits never show up as drift.
• It calls the app's drift detect handler, which reads the live state from the target and returns the differences. A configuration type whose app does not implement drift detection cannot be verified and reports "This configuration does not support drift verification".
• Targets are the servers the configuration was deployed to (or, for zone-scoped types, each selected domain). Each environment and target gets its own record.
• Only configurations with at least one successful deployment are checked. A configuration that was never deployed has nothing to compare.
• If the live state matches again, the open record is closed automatically.

Drift detection is part of the Starter plan and above. See Plans, permissions and gotchas.

Where drift appears

Scheduled and on-demand checks

Scheduled sweep

A sweep runs every hour. For each deployed configuration it works out the effective frequency (see Setting the schedule) and checks the configuration only when it is due: when it has never been checked, or when the last check is older than its frequency (one hour, one day or one week). Tenants on a plan without drift detection are skipped. Hourly is therefore the finest granularity. Because a check is timestamped when it finishes, the due test allows a 15-minute tolerance, so an hourly configuration is checked at every hourly sweep.

Check drift now

Both buttons need write access and a plan with drift detection. On-demand checks count toward the pipeline rate limit of 30 operations per minute per organization.

When a check cannot run

• A check that could not reach the target or read its state is a check failure, not drift. The reason is shown on the configuration's Drift tab, and a warning-level alert is raised. The configuration is not shown as "In sync".
• A failed or partial check never closes an open drift record.
• Typical causes: no credential is available for the target, no targets could be resolved, the server cannot be reached, or the deployment snapshot is missing.

Reading drift records

The Drift page

• Three cards show the number of Critical, Warning and Info records. They count the records on the page you are viewing, so they change when you change the filter or the page.
• The filter buttons are unresolved (the default), resolved and all, with a record count. Records are paged 15 at a time with Previous and Next.
• Empty states say "No unresolved drift detected", "No resolved drift records" or "No drift records found". The list shows recorded incidents only; use a configuration's Drift tab to see its latest verification status.

A record

Severity

Each difference carries its own severity, set by the app's drift handler; the record takes the highest.

States

Resolving drift

1. Acknowledge (on the Drift page, the dashboard, or a configuration's Drift tab) records who acknowledged and when, and marks the record "Acknowledged, awaiting correction". It does not close the record.
2. Correct (configuration Drift tab only) re-deploys the approved configuration to that environment, overwriting the manual change. You confirm "Re-deploy the approved configuration to <environment>?" first. The record is closed only if the re-deployment succeeds and a verification then finds the live state matching; if the deployment fails you are shown the reason and the record stays open.
3. If someone reverts the manual change themselves, the next check closes the record as drift cleared.

On the configuration's Drift tab

• In sync (green) means every environment's latest check succeeded with nothing unresolved. "In sync — no drift detected: the deployed configuration matches the approved version".
• Otherwise the tab shows the number unresolved and badges per severity, then a card per record with its environment, target, and the same diff table, plus Acknowledge and Correct.
• "Drift status has not been verified" means no check has completed successfully yet; "could not be verified" means the last check failed.

Setting the schedule

Organization default

1. Open Settings and choose Drift Detection.
2. Under Scheduled check frequency, change Drift check schedule to Off, Hourly, Daily or Weekly.
3. It saves immediately, and you see "Drift check schedule updated."

If you have never set it, the default is Hourly.

Per-app override

1. Open Marketplace and choose the gear (Settings) icon on the app's card.
2. In the dialog's Drift detection section, choose Inherit tenant default (<current default>) or a specific frequency.
3. It also saves immediately, independent of the dialog's Save Settings button.

A per-app setting always wins over the organization default. Choosing Inherit removes the override.

Plans, permissions and gotchas

On the Free plan the Pipeline dashboard and Drift page show an upgrade prompt, the scheduled sweep skips your organization, and the drift API answers "Configuration drift detection requires a paid plan." The Drift Detection settings page shows the same upgrade prompt instead of the schedule.

Permissions

Gotchas

• A configuration deployed to several environments or targets produces separate records for each.
• You cannot delete an environment while it has drift records; resolve them first.
• The dashboard shows the ten most recent unresolved records; the Drift page lists them all.
• Drift handlers are part of each app. If a configuration type reports that drift verification is unsupported, the app does not implement it.
• In a sandbox, a drift handler can be run for testing, but only against components tagged "sandbox".