> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/infrastructure-as-code-management/troubleshooting-and-resources/faq.md).
# FAQ — Harness IaCM
Answers to common questions about Harness Infrastructure as Code Management (IaCM), covering workspaces, provisioners, variables, secrets, file secrets, plugin configuration, drift detection, state, a
This page answers common questions about Harness Infrastructure as Code Management (IaCM). Go to the [IaCM overview](/infrastructure-as-code-management/new-to-iacm/overview.md) to understand how workspaces, provisioners, and pipelines fit together.
***
## Provisioners and versions
Which Terraform versions does IaCM support?
Harness IaCM supports MPL-licensed Terraform up to **1.5.x** only. BSL-licensed releases, meaning **1.6.0** and later, are not supported. If you are on Terraform 1.6 or above, use OpenTofu as a drop-in replacement.
Go to [What is supported in IaCM](/infrastructure-as-code-management/troubleshooting-and-resources/whats-supported.md) to review provisioner version support.
Can I run the IACMOpenTofuPlugin step without a workspace?
No. The `IACMOpenTofuPlugin` step requires a workspace ID because it uses the workspace configuration, variables, connectors, and state for the execution.
If you need to run OpenTofu commands in a pipeline without a workspace — for example, to run `tofu test` in a CI pipeline — use a standard **Plugin** step with the `plugins/harness_terraform` image and pass the OpenTofu command directly. That step does not require a workspace.
Go to [Default pipelines for OpenTofu](/infrastructure-as-code-management/use-iacm/iac-provisioners/opentofu/default-pipelines.md) to configure workspace-backed provisioning pipelines.
Does IaCM capture tofu test results as test report artifacts?
No. IaCM does not currently publish `tofu test` results as Harness test report artifacts. The test output is available in the pipeline step log. To review the results, open the step log in the pipeline execution.
***
## Workspaces
Can we use multiple workspaces in a single stage?
No, a single stage is limited to one workspace. A pipeline can include multiple stages, however, and each stage can reference a different workspace. You select the workspace when you configure the Infrastructure as Code Management stage, so you handle multiple workspaces by chaining stages, each performing specific tasks on its assigned workspace.
Go to [Provision workspace](/infrastructure-as-code-management/platform/workspaces/provision-workspace.md) to configure a stage and select its workspace.
Does the workspace UI update before an apply runs?
No. The workspace UI reflects the last successfully applied state. Resource counts, outputs, and state data do not update until an Apply operation completes. When changes are pending, such as updated variables, a modified provisioner version, or new code commits, Harness transitions the workspace to **Apply\_Needed** status. The **Resources** and **State** tabs continue to show the last applied configuration until the next apply completes successfully.
Go to [Workspace statuses](/infrastructure-as-code-management/platform/workspaces/workspace-statuses.md) to understand what triggers **Apply\_Needed** and how to resolve it.
Where do I edit the workspace YAML in the UI?
Open the workspace and select the **Configuration** tab. In the Configuration panel, enable the **YAML** toggle. Harness displays the raw YAML for your workspace configuration, which you can edit directly and save.
Can a workspace contain duplicate resource types?
Yes. A workspace can contain multiple resources of the same type, such as two `aws_instance` resources, as long as each resource has a unique name within your OpenTofu or Terraform configuration. Harness identifies each resource by its full address, which combines the resource type and name. For example, `aws_instance.web` and `aws_instance.db` are distinct resources even though they use the same resource type.
What is the hws_* project, and do I need to manage it?
The `hws_*` project is created automatically by Harness Solutions Factory (HSF), one per organization. It contains the Factory Floor pipelines that manage workspace lifecycle operations, including workspace creation, teardown, drift analysis, provisioning, validation, and bulk management.
If you are not using HSF, you will not encounter `hws_*` projects. If you use HSF and see an `hws_*` project in your account, you do not need to configure or manage it directly. Contact your HSF Admin or go to your organization's HSF runbook for information about the factory project structure.
Can workspace names contain hyphens?
Yes. Workspace names can contain hyphens. A valid workspace name must start with a letter or underscore and can contain letters, numbers, underscores, hyphens, and spaces. The maximum length is 128 characters.
The workspace identifier, or slug, is automatically generated from the workspace name and is used in URLs and API calls. The identifier must start with a letter or underscore and can contain letters, numbers, underscores, and hyphens. Spaces in the workspace name are not included in the identifier.
What is the modules[] list under a workspace resource, and how do I reduce it?
The **modules** list on the workspace **Resources** tab shows the external registry modules referenced by your workspace configuration, such as `registry.opentofu.org/terraform-aws-modules/ec2-instance/aws`. Harness extracts this list from the workspace's module metadata after each plan or apply.
You cannot filter or shorten the list directly in the Harness UI. To reduce the list, remove unused module references from your IaC configuration and run a new apply. Harness then displays the updated module list.
How do I deactivate and delete a workspace?
A workspace must be in **Inactive** status before you can delete it. A workspace becomes inactive after a successful destroy operation tears down its provisioned infrastructure and clears its active state.
To set a workspace as inactive:
1. Open the workspace.
2. Run a destroy pipeline against it. If a default destroy pipeline is configured, select the **More** icon next to the workspace in the list, then select **Destroy**. Otherwise, go to the **Configuration** tab and configure a default pipeline first.
3. Confirm that the pipeline completes successfully. The workspace status changes to **Inactive**.
You can then go to [Delete workspace](/infrastructure-as-code-management/platform/workspaces/delete-workspace.md) to remove the workspace.
Go to [Destroy workspaces](/infrastructure-as-code-management/platform/workspaces/destroy-workspaces.md) to configure a destroy pipeline.
***
## Module registry
Can the same module be used with OpenTofu and Terraform?
Yes, modules are agnostic and can be used with either an OpenTofu or Terraform provisioner. The registry parses and versions the module the same way regardless of which provisioner consumes it.
Go to the [module registry overview](/infrastructure-as-code-management/registry/module-registry/module-registry-overview.md) to publish and version reusable modules.
***
## Variables and secrets
Can I pass AWS session tags during IaCM pipeline execution?
IaCM does not currently support passing AWS STS session tags during role assumption.
If your goal is to apply tags to the AWS resources managed by your configuration, use the AWS provider's `default_tags` block and supply the values through workspace environment variables or Terraform variables instead.
```hcl
# provider.tf
provider "aws" {
default_tags {
tags = {
Team = var.team_tag
Project = var.project_tag
}
}
}
```
Set `team_tag` and `project_tag` as workspace Terraform variables or environment variables. Go to [Connectors and variable sources](/infrastructure-as-code-management/platform/iacm-connectors-variables/connectors-variables.md) to add them.
How do I make a file available to an IaCM pipeline step?
IaCM workspace variables store string values only. To make a file available inside a pipeline run, use a **Run** step placed before your IaCM steps to write the file content to disk, then reference the path from the IaCM step.
For example, to provide a `.tofurc` registry token file or a provider configuration file:
```yaml
- step:
type: Run
name: write-config-file
identifier: write_config_file
spec:
shell: Sh
command: |
echo "$TF_CONFIG_CONTENT" > /tmp/.tofurc
envVariables:
TF_CONFIG_CONTENT: <+secrets.getValue("tofurc_content")>
```
Then, on the IaCM stage, set `TF_CLI_CONFIG_FILE` as a workspace environment variable pointing to `/tmp/.tofurc`. The Run step and IaCM steps share the stage filesystem, so the file is available when the IaCM step runs.
Go to [Connectors and variable sources](/infrastructure-as-code-management/platform/iacm-connectors-variables/connectors-variables.md) to add environment variables to a workspace.
Can I carry secret variables from one workspace to another?
You can reference the same Harness secret in multiple workspaces. There is no restriction on using a secret in more than one workspace. You cannot copy or export the secret value itself from one workspace to another through the IaCM UI or API. Instead, reference the same underlying Harness secret in both workspaces.
For org- or project-scoped secrets, the same secret reference is valid in any workspace within that org or project. If the destination workspace is in a different project, create the secret at org or account scope so both workspaces can reference it.
Go to [Connectors and variable sources](/infrastructure-as-code-management/platform/iacm-connectors-variables/connectors-variables.md) to add a secret variable to a workspace. Go to [Manage secrets](https://developer.harness.io/harness-platform/use-harness-platform/secrets) to create and scope Harness secrets.
***
## Plugin configuration
How do I configure a .tofurc file or TF_CLI_CONFIG_FILE in an IaCM workspace?
To use a `.tofurc` configuration file in an IaCM workspace, create the file in the pipeline before the IaCM step runs and set `TF_CLI_CONFIG_FILE` to its path.
Use a **Run** step to write the file to `/tmp/.tofurc`, then set `TF_CLI_CONFIG_FILE=/tmp/.tofurc` as a workspace environment variable. Every subsequent IaCM step in the stage picks it up automatically. Go to [How do I make a file available to an IaCM pipeline step?](#variables-and-secrets) for the example YAML.
Alternatively, include the `.tofurc` file in a custom plugin image and set `TF_CLI_CONFIG_FILE` to the file path. Go to [Custom images for OpenTofu](/infrastructure-as-code-management/use-iacm/iac-provisioners/opentofu/custom-images.md) for instructions on building and registering a custom image.
Can I increase the memory limit for the clone-workspace container step?
Yes. The IaCM plugin runs each pipeline step, including `clone-workspace`, as a container. To increase the memory limit for the step, open the pipeline in Pipeline Studio, locate the **clone-workspace** step, and edit its **Container Resources** settings. Set **Memory** to a higher value, such as `2Gi`, and save the pipeline.
If you use a default pipeline configured on the workspace, open that pipeline in **Pipeline Studio** and apply the same change to the `clone-workspace` container resources.
Go to [Default pipelines](/infrastructure-as-code-management/platform/iacm-pipelines/default-pipelines.md) to locate the pipeline you need to edit.
Can I change the log level for the Manage IACM Workspace step plugin?
The *Manage IACM Workspace* step plugin does not expose a dedicated log-level setting. To increase the verbosity of OpenTofu or Terraform output during pipeline execution, set the `TF_LOG` environment variable on your workspace. Accepted values are `TRACE`, `DEBUG`, `INFO`, `WARN`, and `ERROR`.
To set `TF_LOG`:
1. Open the workspace and select the **Connectors and Variables** tab.
2. In the **Environment Variables** panel, select **+ Add Variable**.
3. Set **Key** to `TF_LOG` and **Value** to your desired log level, for example `DEBUG`.
4. Select **Save Changes**.
The variable takes effect on the next pipeline execution against the workspace.
Go to [Connectors and variable sources](/infrastructure-as-code-management/platform/iacm-connectors-variables/connectors-variables.md) to add environment variables to a workspace.
***
## Drift detection
Why does drift detection report more changes than a plan?
Drift detection and planning answer different questions, so they report different results. Harness runs `tofu plan -refresh-only` for drift detection, which surfaces every change made outside of OpenTofu, including metadata such as `updated_at` values. A normal `tofu plan`, and the equivalent Harness step, only reports differences that affect bringing your infrastructure in line with your configuration, so it reports no changes when your configuration already matches state. This is by design in OpenTofu, so drift detection legitimately shows more changes than you might expect.
When drift is found, the pipeline fails and flags the affected resources in the **Resources** tab. To reconcile state without applying unrelated configuration changes, use a `plan-refresh-only` step.
Go to [drift detection](/infrastructure-as-code-management/platform/iacm-pipelines/content/drift-detection.md) to build a drift pipeline and review drift details.
***
## Remote backends and state
Which remote state backends does IaCM support?
When your code contains no backend block, IaCM automatically uses Harness-managed state storage. You can also point a workspace at an existing **AWS S3**, **Google Cloud Storage**, or **Azure Blob Storage** backend by committing a `backends.tf` file, with no migration required. A separate `http` backend block lets you reach Harness-managed state from outside a pipeline.
Go to [Use existing remote state](/infrastructure-as-code-management/use-iacm/remote-backends/use-backends.md) to connect an existing backend, or [State migration](/infrastructure-as-code-management/use-iacm/remote-backends/state-migration.md) to move state into Harness.
Does Harness support the `cloud {}` configuration block?
No. The `cloud` block was designed for Terraform Cloud and Enterprise, and OpenTofu retains it only for backward compatibility. IaCM does not honor it, so remove any `cloud` block before running your configuration in a workspace.
To run operations against a workspace, use a pipeline or the Harness CLI, for example `harness execute workspace `. To inspect or modify state locally, copy the `http` backend block from the workspace **CLI Integration** tab into a temporary `backend.tf` file, add that file to `.gitignore` so it does not conflict with pipeline runs, and remove it after inspection.
Go to the [Harness CLI reference](/infrastructure-as-code-management/use-iacm/iacm-cli-commands/harness-cli.md) to review the available commands, and [CLI integration](/infrastructure-as-code-management/platform/workspaces/cli-integration.md) to copy your workspace backend block.
How is state locking handled?
Each backend implements its own locking mechanism, and OpenTofu acquires and releases the lock during pipeline execution. S3 uses DynamoDB, GCS uses object metadata, and Azure Blob Storage uses leases. IaCM adds no locking layer of its own, so a stuck lock is resolved through the backend rather than through Harness.
Go to [state locking considerations](/infrastructure-as-code-management/use-iacm/remote-backends/use-backends.md#state-locking-considerations) to configure locking for your backend.
***
## Pipelines and variables
How do I reference a pipeline variable inside an IaCM step?
Use the standard Harness JEXL expression syntax. Pipeline variables defined in the **Variables** panel of the pipeline use `<+pipeline.variables.VARIABLE_NAME>`. Stage variables use `<+stage.variables.VARIABLE_NAME>`. You can supply these values to an IaCM step by setting them as workspace environment variables or by passing them as values in a **Run** step that runs before the IaCM steps.
Go to [Workspace expressions](/infrastructure-as-code-management/platform/workspaces/workspace-expressions.md) to reference workspace-level data such as outputs and variables directly in pipeline expressions.
Can I run Plan or Apply across multiple workspaces in parallel?
Yes. IaCM supports one workspace per stage, but a pipeline can contain multiple stages running in parallel. To run Plan or Apply across several workspaces simultaneously, add a parallel stage group to your pipeline, where each stage targets a different workspace. Harness executes all stages in the group concurrently.
Go to [Provision workspace](/infrastructure-as-code-management/platform/workspaces/provision-workspace.md) to configure a stage and assign a workspace to it. Go to [Pipeline Studio](https://developer.harness.io/harness-platform/use-harness-platform/pipelines/pipeline-studio/pipeline-execution-branches) to add parallel stages.
***
## API
How do I page through IaCM list API results?
The IaCM list APIs return paginated results. Use the `page` and `pageSize` query parameters to navigate pages. `page` is zero-indexed, so `page=0` returns the first page. `pageSize` controls the number of results per page. The response body includes `totalItems`, `totalPages`, and `pageSize` fields so you can determine whether further pages exist.
For example, to retrieve the second page of 25 workspaces:
```
GET /v1/workspaces?page=1&pageSize=25
```
Go to the [IaCM API reference](https://github.com/harness/harness-developer-hub/tree/main/docs/delivery/infrastructure-as-code-management/api-reference/SUMMARY.md) for the full endpoint reference.
***
## Getting started
Does the IaCM module need to be enabled on my account?
Yes. The Harness Infrastructure as Code Management module must be enabled on your account before you can create workspaces or run IaCM pipelines. Contact your Harness account team to enable the module. Once enabled, the **Infrastructure** navigation item appears in your Harness project.
***
## Costs and billing
Can drift detection incur additional costs?
No, usage charges are only incurred when an `apply` changes resources. The `plan` command and drift detection are free.
{% @harness-feedback/feedback %}