Workspaces

Introduction

A workspace is where all objects related to Terraform and OpenTofu managed resources are stored and managed. This is where you can find state, update the Terraform and OpenTofu versions, manage variables, see run history, and much more. Workspaces can be as simple as a single resource or can be a complex monolithic configuration, it all depends on your use case and the directories that the workspace is linked to. A workspace can be integrated with your existing workflow whether it is a GitOps approach through a VCS provider, using the native Terraform CLI, or deploying modules directly in the UI. All workspace types follow the same pipeline:

Workspace Pipelines

Pre-Init

A custom hook can be executed during pre-init to execute a script or Linux command of your choice. A common use case is to use the pre-init stage to integrate with external secrets management tooling. Runs that fail during this stage are not billed for.

Pre-Plan

The pre-plan stage allows users to run native tools such as terraform fmt, terraform validate, Open Policy Agent, and Checkov, or build a custom solution with a custom hook. Runs that fail during this stage are not billed for.

Plan

The plan stage is when Terraform or OpenTofu are running the plan command, which will show you the proposed changes to resources. Users can view the planned creation, update, or destruction of resources through the standard console output or visual plan view. The visual plan alerts users of destructive changes and makes it easier to search the plan when many resources are affected.

Post-Plan

A custom hook can be executed during post-plan to execute a script or Linux command of your choice. A common use case is to use the post-plan stage would be to pull the plan details and export them or trigger API calls to external tools.

Cost Estimate

Cost Estimate, which will show you the estimated cost for the resources that are being created. This information can be used for writing a policy to check cost. See Infracost for details of providers and resources that are currently included in the cost estimation.

Post-Plan Policy Check

Policy Check, which is used to check the Terraform plan JSON output against Open Policy Agent policies. This step can be used to enforce company standards and policies.

Approval

The approval phase prompts users to approve the proposed changes resulting in an apply, which will make the changes to the resources. The approval step can be disabled by clicking "Auto apply changes when a Terraform plan is successful" in the workspace settings. Approvals can be done directly in the Scalr UI/API or through an integration with Microsoft Teams or Slack. Only users with the runs:apply permissions can approve runs.

Pre-Apply

A custom hook can be executed during pre-apply to execute a script or Linux command of your choice.

Apply

Apply, which will actually create, update, or destroy the resources based on the Terraform configuration file.

Post-Apply

A custom hook can be executed during post-apply to execute a script or Linux command of your choice. The post-apply stage is often used to call an external API to notify of the run results, download the state externally, or any other requirement needed after the apply.

Managing Workspaces

While workspaces are created and updated in the environment scope, you do have the option to view all workspaces that you have access to at the account scope. The account scope view aggregates all workspaces across environments into a single dashboard with the ability to also execute runs from there if you have the proper permissions to do so. The permission workspaces:read must be granted at the account scope to view the workspaces.