Preparing your Terraform environment

When running Terraform on a local PC, the state of the resources managed by Terraform is saved in a local file. This state is queried to learn which resources already exist in order to properly apply updates and destroy resources.

When Terraform is run by Octopus, this state file is not preserved between executions. This means a remote backend must be configured for almost all practical applications of Terraform through Octopus, allowing the state information to be preserved between Terraform steps.

Refer to the Terraform documentation for more information on configuring backends.

Caution on Terraform runs

By default, Terraform stores state files locally. If a remote backend is not configured, attempts to update or delete existing resources will fail because the state file is lost between deployments. We therefore recommend using a remote backend, such as HCP Terraform, when using Terraform with Octopus. There are many options for storing state files, you can learn more about storing state remotely in the Terraform documentation.

HCP Terraform

HCP Terraform or Terraform Enterprise are Terraform execution platforms and remote backends. Using Terraform Enterprise or HCP Terraform for execution and/or state management can be achieved using the Terraform cloud block.

Basic Example

terraform {
  cloud {
	organization = "my-org" 
    workspaces {
      project = "Default Project"
      name = "base_layer"
    }
  }
}

Common Example

A common setup will be use a combination of Octopus environment variables, Octopus Project Variables, and hardcoded values. The below example shows the organization is inherited from an ENV variable in Octopus, the HCP Terraform project is derived from a combination of Octopus project name and environment name, and the workspace name is hardcoded.

# organization is inherited from ENV variable TF_CLOUD_ORGANIZATION
terraform {
  cloud {
    workspaces {
      project = "#{Octopus.Project.Name}-#{Octopus.Environment.Name}"
      name = "base_layer"
    }
  }
}

Cloud block settings can be set via environment variable and omitted from HCL:

TF_CLOUD_ORGANIZATION
TF_CLOUD_PROJECT
TF_WORKSPACE

note: if you set all 3 environment variables, a empty cloud block must exist in the hcl root configuration (ex: terraform { cloud {} }).

Adding environment variables to Octopus Project

You can add environment Variables to your Octopus project like this:

setting environment variables in octopus project

Managed cloud accounts

You can optionally prepare the environment that Terraform runs in using the details defined in accounts managed by Octopus. If an account is selected then those credentials do not need to be included in the Terraform template. Using credentials managed by Octopus is optional. These credentials can be saved directly into the Terraform template if that approach is preferable. Credentials defined in the Terraform template take precedence over any credentials defined in the step. The following pages provide instruction on creating cloud accounts:

Querying outputs from HCP Terraform

You can query Terraform Enterprise for values from a remote state file using a data source referencing the tfe_outputs backend. A token is required and should be set as an ENV variable (TFE_TOKEN)

data "tfe_outputs" "previous_step_outputs" {
  organization = var.organization
  workspace    = var.workspace
}

Help us continuously improve

Please let us know if you have any feedback about this page.

Send feedback

Page updated on Wednesday, October 4, 2023

Edit on GitHub