Drift Detection and Ephemeral Workspaces
Configure scheduled drift detection and automatic workspace lifecycle (ephemeral workspaces) at the workspace and project level in Harness IaCM.
Harness IaCM provides two native automation features that keep your infrastructure healthy and your workspace list clean: Drift Detection, which runs a scheduled check for infrastructure that has diverged from your state, and Ephemeral Workspaces, which automatically destroys (and optionally deletes) workspaces after a period of inactivity. Both features share one configuration model, so you set them up the same way at the workspace level or the project level.
What you will learn from this topic
What Drift Detection and Ephemeral Workspaces do, and how they relate.
The two configuration levels (workspace and project, per provisioner) and how they override each other.
How to configure each feature via the Harness UI or the REST API.
The workspace lifecycle and the safety guards that protect against accidental deletion.
Before you begin
IaCM enabled: Your account must have Infrastructure as Code Management entitled. Go to Get started with IaCM to confirm access.
Permissions: Workspace-level configuration requires workspace edit permission. Project-level configuration requires project settings edit permission. Go to Workspace permissions to review IaCM roles.
A default Destroy pipeline: Ephemeral Workspaces runs your workspace or project Destroy default pipeline when a workspace expires. Configure it first. Go to Default pipelines to set one up.
A drift pipeline: Drift Detection runs a pipeline that performs a detect-drift operation. Go to Drift detection to build one.
How the two features relate
Both features extend the same workspace lifecycle and reuse the same configuration surface, but they solve different problems and run on different schedulers.
Purpose
Detect infrastructure that no longer matches state.
Automatically destroy, and optionally delete, inactive workspaces.
Action
Runs a drift pipeline on a recurring schedule.
Runs a destroy pipeline once after inactivity, then optionally deletes the workspace record.
Schedule
Recurring (every N hours or days).
One-time action anchored to the last successful apply.
Scheduler
Harness scheduled pipeline trigger (cron).
Harness background finder jobs that scan periodically.
Workspace state
active or drifted.
active, then inactive, then deleted.
Configuration levels
Workspace and project (per provisioner).
Workspace and project (per provisioner).
Both features attach to the workspace and project default pipelines and use the same override model described in Configuration levels. You can enable one without the other.
Configuration levels
Both features support two configuration levels.
Workspace-level
A single workspace.
Takes precedence over project-level configuration.
Project-level (per provisioner)
All workspaces in the project that use the specified provisioner.
Acts as the fallback when a workspace has no workspace-level configuration.
The supported provisioner values are opentofu, terraform, terragrunt, and awscdk.
Configuration resolves in this priority order:
1
Workspace-level
Highest priority. Always wins when present.
2
Workspace opt-out
A workspace that you explicitly disable stays disabled and does not inherit project-level configuration.
3
Project-level (specific provisioner)
Fallback when no workspace-level configuration exists.
4
None
The workspace is not drift-detected or ephemeral.
Drift detection
Drift Detection runs a pipeline on a schedule to check whether your live infrastructure still matches your Terraform, OpenTofu, or Terragrunt state. When the scheduled run detects drift, the pipeline fails and the workspace is marked drifted.
Go to Drift detection to understand how the drift detection operation works. This page covers the scheduled, native configuration. To run drift detection manually or as a step in a provision pipeline, go to Drift detection (manual).
How drift detection works
You configure a drift pipeline and a schedule at the workspace or project level.
Harness creates a recurring scheduled trigger for the pipeline.
The trigger fires on the schedule and runs the drift pipeline.
The pipeline runs a plan, compares it against state, and reports the result.
Harness updates the workspace status to drifted when changes are detected, or keeps it active when no drift is found.
A random jitter of up to 15 minutes is applied to each schedule so that workspaces do not all run at the same moment.
Schedule fields
pipeline_id
The pipeline to run for drift detection.
Yes
my_drift_pipeline
run_every
The interval value.
Yes
6
run_every_unit
The interval unit: hours or days.
Yes
hours
provisioner
The provisioner this configuration applies to. Required at the project level.
Conditional
opentofu
The schedule is converted to a cron expression automatically. For example, run_every: 6 with run_every_unit: hours runs every six hours.
Enable drift detection
Workspace level
Open your workspace and select the Configuration tab.
Scroll to the Advanced section and expand Default Pipelines.
Under Check for Drift, select your drift pipeline from the dropdown.
Select Automated Check for Drift.
In the Run every field, enter a number and select Days or Hours.
Select Save Changes.
Project level
Go to Project Settings → IaCM Settings → IaCM Defaults.
Expand the accordion for your provisioner (for example, For OpenTofu).
Under Check for Drift, select your drift pipeline from the dropdown.
Select Automated Check for Drift.
In the Run every field, enter a number and select Days or Hours.
Select Save Changes.
Workspace level
Send a PUT request to the workspace drift-config endpoint. Replace <harness_host> with your Harness environment URL (app.harness.io for production SaaS, or your cluster-specific domain for self-managed).
To check the current configuration, send a GET request to the same path (add ?provisioner=<value> as a query parameter). The response reports enabled, pipeline_id, run_every, run_every_unit, and trigger_id.
To disable drift detection for the workspace, send a DELETE request to the same path. This removes the scheduled trigger.
Project level
Send a PUT request to the settings drift-config endpoint. Project-level configuration is applied asynchronously — the request returns 202 Accepted with a job_id. Workspaces that already have a workspace-level drift configuration are not overwritten.
To disable drift detection for the project, send a DELETE request to the settings drift-config endpoint.
Drift status values
active
Infrastructure matches state.
drifted
Differences were detected between infrastructure and state.
View the workspace status on the workspace detail page or in the workspace list. When a workspace is marked drifted, run a new apply to reconcile the infrastructure and return the workspace to active status.
Ephemeral workspaces
Ephemeral Workspaces are time-limited environments that automatically destroy their infrastructure after a period of inactivity. Optionally, Harness deletes the workspace record itself after a further delay.
How ephemeral workspaces work
You configure a destroy schedule, and optionally a delete schedule, at the workspace or project level.
Harness periodically scans for workspaces whose destroy time has passed.
When a workspace is eligible, Harness runs the workspace or project Destroy default pipeline.
After a successful destroy, the workspace status becomes inactive.
When you opt in to deletion, the workspace record is permanently removed after the delete delay passes. Deletion removes only the workspace record from Harness — infrastructure is already destroyed by the destroy pipeline in step 4.
The TTL is a sliding window anchored to the last successful apply, not to the workspace creation time. The clock resets each time a workspace transitions from inactive to active.
Schedule fields
Destroy schedule
provisioner
The provisioner this configuration applies to. Required at the project level.
Conditional
opentofu
destroy_delay_value
The relative delay after the last successful apply. Provide this with destroy_delay_unit, or use destroy_on_date instead.
Conditional
7
destroy_delay_unit
The delay unit: hours or days.
Conditional
days
destroy_on_date
An absolute destroy date in ISO 8601 format (YYYY-MM-DD). Use this instead of a delay.
Conditional
2026-07-01
The destroy operation uses your configured Destroy default pipeline (workspace-level or project-level fallback).
Delete schedule (optional)
delete_workspace
Whether to delete the workspace record after a successful destroy.
No
true
delete_delay_value
How long to wait after destroy before deletion.
Conditional
7
delete_delay_unit
The delay unit: hours or days.
Conditional
days
delete_on_date
An absolute delete date in ISO 8601 format (YYYY-MM-DD).
Conditional
2026-07-15
Enable ephemeral workspaces
Workspace level
Open your workspace and select the Configuration tab.
Scroll to the Advanced section and expand Default Pipelines.
Under Destroy Infrastructure, confirm your destroy pipeline is selected.
Select Allow TTL (time-to-live) settings.
Choose Delayed to set a relative delay, or On a specific day to set an absolute date.
For Delayed: enter a number in Destroy infrastructure in and select Days or Hours.
For On a specific day: enter a date using the date picker.
Optionally, select Delete Workspace after destroying and configure the delete delay in the same way.
Select Save Changes.
Project level
Go to Project Settings → IaCM Settings → IaCM Defaults.
Expand the accordion for your provisioner (for example, For OpenTofu).
Under Destroy Infrastructure, confirm your destroy pipeline is selected.
Select Allow TTL (time-to-live) settings and configure the destroy schedule.
Optionally, select Delete Workspace after destroying and configure the delete delay.
Select Save Changes.
Workspace level
Send a PUT request to the workspace ephemeral-config endpoint:
To check the current configuration, send a GET request to the same path (add ?provisioner=<value> as a query parameter). The response reports enabled, provisioner, source, the destroy schedule (ttl_value/ttl_unit or destroy_on_date), delete_workspace, and the delete schedule.
To disable an ephemeral workspace, send a DELETE request to the same path.
Project level
Send a PUT request to the settings ephemeral-config endpoint:
To disable ephemeral workspaces for the project, send a DELETE request to the settings ephemeral-config endpoint.
Workspace lifecycle
Safety guards
Ephemeral Workspaces includes several safeguards against accidental teardown:
Re-validation at execution: Before a destroy or delete runs, Harness re-checks that the workspace is still eligible. If you disabled the feature or the workspace became active again, the job is skipped.
Resource binding protection: A workspace is not deleted while another resource still references it.
Explicit opt-out: A workspace you disable stays disabled, even if the project later enables ephemeral workspaces.
Activity reset: If a destroyed workspace becomes active again, any pending deletion is cancelled and the clock resets.
Failed destroy handling: If a destroy pipeline fails, the workspace remains in a failed state. Investigate the failure, fix the underlying issue, and manually trigger a destroy operation or re-run the scheduled automation once the issue is resolved.
Troubleshooting
Next steps
You can now keep infrastructure in sync with Drift Detection and control workspace lifecycle with Ephemeral Workspaces.
Go to Drift detection to run drift detection manually or during provisioning.
Go to Destroy workspaces to tear down infrastructure on demand.
Go to Default pipelines to configure the pipelines these features run.
Last updated
Was this helpful?