Remote State Management

Related Guides and Examples:

• Overview: Firefly Workflows and Guardrails: High-level concepts and options.

• Creating New Firefly Workflows: How to set up managed workflows.

• Creating Guardrail Rules in Firefly: How to define and enforce policies and best practices.

• Creating Projects: How to create projects to group IaC orchestration resources and control access.

• Triggering Workspace Deployment: How to trigger a workspace deployment from the Firefly UI.

Firefly offers a sophisticated state backend synchronized with the rest of the application to manage your Terraform state and maximize security and convenience—available for workspaces configured with Firefly runner or Self-hosted runner pool.

State History

You can view your stack's state history in Firefly. Navigate to the workspace, hover over the actions and select View Assets. In the modal that opens you can see all the assets created by this workspace, when each was created, and the ability to download the state file.

Note: Not all runs or tasks will trigger a new state version, so you should not expect to see an exhaustive list of your runs and tasks in this list. For example, runs that produce no Terraform changes do not result in a new state version being created.

Limitations

• OpenTofu versions: All versions are supported.

• Workspace name format: Workspace names cannot contain spaces in the HCL backend block. Note that while Firefly allows spaces in workspace names within the UI, the name used in your backend configuration must not contain spaces.

Remote Management Workspace Set-up

Workspace Configuration

To enable state management for a workspace:

New Workspace

In the Execution Configuration step, enable the Firefly Remote Backend Configuration option.

Migration

Firefly Backend Configuration

To use the Firefly remote backend, configure your Terraform backend block as follows:

terraform {
  backend "remote" {
    hostname     = "api.gofirefly.io"
    organization = "<your-organization-id>"
    workspaces {
      name = "<your-workspace-name>"
    }
  }
}

Migrating from Terraform remote backend to OpenTofu

If you are switching from Terraform to OpenTofu and currently use a remote backend, add hostname = "app.terraform.io" to your existing backend block, then run the migration command.

Existing backend block:

terraform {
  backend "remote" {
    hostname     = "app.terraform.io"
    organization = "your-organization"
    workspaces {
      name = "your-workspace"
    }
  }
}

Then run:

tofu init -migrate-state

Migrating from Terraform cloud backend to OpenTofu + Firefly

If you are switching from Terraform to OpenTofu and currently use a cloud backend, follow these steps:

1. Add hostname to your existing cloud block:

terraform {
  cloud {
    hostname     = "app.terraform.io"
    organization = "your-organization"
    workspaces {
      name = "your-workspace"
    }
  }
}

1. Pull and validate the current state:

tofu state pull > terraform.tfstate.backup
tofu show terraform.tfstate.backup   # If this succeeds, the state is valid

1. Update your backend block — replace the cloud block with the Firefly remote backend:

terraform {
  backend "remote" {
    hostname     = "api.gofirefly.io"
    organization = "<your-organization-id>"
    workspaces {
      name = "<your-workspace-name>"
    }
  }
}

1. Reinitialize and push state:

rm -rf .terraform
tofu init -reconfigure
tofu state push terraform.tfstate.backup

Note: If a state already exists on the workspace and you need to override it, append the -force flag:

tofu state push -force terraform.tfstate.backup