Terraform stores state about managed infrastructure to map real-world resources to the configuration, keep track of metadata, and improve performance. Terraform stores this state in a local file by default, but you can also use a Terraform remote backend to store state remotely.

By default, cdktf init will configure a HCP Terraform workspace and a corresponding remote backend to store state for the new project. If you run cdktf init --local to configure your new project to use a local backend to store state, you can still migrate the state to a remote backend later.

You can configure your CDK for Terraform (CDKTF) remote backend to be HCP Terraform, another Terraform supported backend, or a custom location.

When to Use Remote Backends

Consider using a remote backend when multiple individuals or teams need access to your infrastructure state data.

Remote state makes it easier for teams to work together because all members have access to the latest state data in the remote store. It also allows you to share output values with other configurations, allowing groups to share infrastructure resources. For example, a core infrastructure team can handle building the core machines and then expose some information that other teams can use for their own infrastructure.

Define Remote Backends

You can define a JSON configuration for a remote backend with a TerraformBackend subclass or a JSON configuration file.

The following example uses the TerraformBackend subclass CloudBackend.

import { Construct } from "constructs";
import {
  CloudBackend,
  TerraformStack,
  TerraformOutput,
  NamedCloudWorkspace,
  App,
} from "cdktf";

export class CloudBackendStack extends TerraformStack {
  constructor(scope: Construct, id: string) {
    super(scope, id);

    new CloudBackend(this, {
      hostname: "app.terraform.io",
      organization: "company",
      workspaces: new NamedCloudWorkspace("my-app-prod"),
    });

    new TerraformOutput(this, "dns-server", {
      value: "hello-world",
    });
  }
}

import software.constructs.Construct;
import com.hashicorp.cdktf.TerraformStack;
import com.hashicorp.cdktf.App;
import com.hashicorp.cdktf.CloudBackend;
import com.hashicorp.cdktf.CloudBackendConfig;
import com.hashicorp.cdktf.NamedCloudWorkspace;
import com.hashicorp.cdktf.TerraformOutput;
import com.hashicorp.cdktf.TerraformOutputConfig;

public class MainRemoteBackendDefine extends TerraformStack {

    public MainRemoteBackendDefine(Construct scope, String id) {
        super(scope, id);

        new CloudBackend(this, CloudBackendConfig.builder()
                .hostname("app.terraform.io")
                .organization("company")
                .workspaces(new NamedCloudWorkspace("my-app-prod"))
                .build()
        );

        new TerraformOutput(this, "dns-server", TerraformOutputConfig.builder()
                .value("hello-world")
                .build()
        );
    }
}

from constructs import Construct
from cdktf import App, CloudBackend, NamedCloudWorkspace, TerraformStack, TerraformOutput
class RemoteBackendStack(TerraformStack):
    def __init__(self, scope: Construct, id: str):
        super().__init__(scope, id)

        CloudBackend(self,
            hostname = "app.terraform.io",
            organization = "company",
            workspaces = NamedCloudWorkspace("my-app-prod")
        )

        TerraformOutput(self, "dns-server",
            value = "hello-world"
        )

app = App()
RemoteBackendStack(app, "hello-terraform")
app.synth()

using System;
using System.IO;
using System.Collections.Generic;
using System.Linq;
using Constructs;
using HashiCorp.Cdktf;

namespace Examples
{
    class CloudBackendStack : TerraformStack
    {
        public CloudBackendStack(Construct scope, string name) : base(scope, name)
        {
            new CloudBackend(this, new CloudBackendConfig
            {
                Hostname = "app.terraform.io",
                Organization = "company",
                Workspaces = new NamedCloudWorkspace("my-app-prod")
            });

            new TerraformOutput(this, "dns-server", new TerraformOutputConfig
            {
                Value = "hello-world"
            });
        }
    }
}

import (
    "github.com/aws/constructs-go/constructs/v10"
    "github.com/aws/jsii-runtime-go"
    "github.com/hashicorp/terraform-cdk-go/cdktf"
)

func NewCloudBackendStack(scope constructs.Construct, name string) cdktf.TerraformStack {
    stack := cdktf.NewTerraformStack(scope, &name)

    cdktf.NewCloudBackend(stack, &cdktf.CloudBackendConfig{
        Hostname:     jsii.String("app.terraform.io"),
        Organization: jsii.String("company"),
        Workspaces:   cdktf.NewNamedCloudWorkspace(jsii.String("my-app-prod"), nil),
    })

    cdktf.NewTerraformOutput(stack, jsii.String("dns-server"), &cdktf.TerraformOutputConfig{
        Value: "hello-world",
    })

    return stack
}

When you call cdktf synth, CDKTF stores the backend metadata like the organization name and workspace name in the cdk.tf.json file within the cdktf.out stack sub-directory containing the synthesized CDKTF code. For example, CDKTF creates the output for a stack called hello-terraform in cdktf.out/stacks/hello-terraform.

The following example shows the stack output directory.

tree .
.
└── cdk.tf.json

The following example shows a relevant snippet of the generated cdk.tf.json file.

{
  "//": {
    "metadata": {
      "backend": "cloud",
      "cloud": "tfc",
      "stackName": "hello-terraform",
      "version": "0.20.11"
    }
  },
  "terraform": {
    "cloud": {
      "hostname": "app.terraform.io",
      "organization": "company",
      "workspaces": {
        "name": "hello-terraform"
      }
    }
  }
}

Initialize Remote Backends

All cdktf operations perform an automatic terraform init, but you can also initialize manually.

To manually initialize a remote backend, go to the corresponding stack output directory in the cdktf.out folder and run terraform init.

$ cd cdkf.out/stacks/hello-terraform
$ terraform init

Migrate Local State Storage to Remote

After you define your remote backend, you can migrate existing local state files to the designated remote location. This requires moving Terraform state files to the CDKTF output directory.

Consider an example project called hello-terraform that is using local storage to store the Terraform state. To migrate the local stage files to the remote backend:

1. Navigate into the main project directory.

2. Use CloudBackend to add a new remote backend.

class LocalBackendStack extends TerraformStack {
  constructor(scope: Construct, id: string) {
    super(scope, id);

    new TerraformOutput(this, "dns-server", {
      value: "local",
    });
  }
}

const app = new App();
const stack = new LocalBackendStack(app, "local-to-cloud-backend");
new CloudBackend(stack, {
  hostname: "app.terraform.io",
  organization: "company",
  workspaces: new NamedCloudWorkspace("my-app-prod"),
});

public class MainRemoteBackend extends TerraformStack {

    public MainRemoteBackend(Construct scope, String id) {
        super(scope, id);

        new TerraformOutput(this, "dns-server", TerraformOutputConfig.builder()
                .value("local")
                .build()
        );
    }

    public static void main(String[] args) {
        final App app = new App();
        MainRemoteBackend stack = new MainRemoteBackend(app, "local-to-cloud-backend");
        new CloudBackend(stack, CloudBackendConfig.builder()
                .hostname("app.terraform.io")
                .organization("company")
                .workspaces(new NamedCloudWorkspace("my-app-prod"))
                .build()
        );
        app.synth();
    }
}

stack = Stack(App(), "hi-terraform")
        CloudBackend(self,
            hostname = "app.terraform.io",
            organization = "company",
            workspaces = NamedCloudWorkspace("my-app-prod")
        )

using System;
using System.IO;
using System.Collections.Generic;
using System.Linq;
using Constructs;
using HashiCorp.Cdktf;

namespace Examples
{
    class LocalBackendStack : TerraformStack
    {
        public LocalBackendStack(Construct scope, string name) : base(scope, name)
        {
            new TerraformOutput(this, "dns-server", new TerraformOutputConfig
            {
                Value = "local"
            });
        }
    }
}

App app = new App();
LocalBackendStack stack = new LocalBackendStack(app, "local-to-cloud-backend");
new CloudBackend(stack, new CloudBackendConfig {
    Hostname = "app.terraform.io",
    Organization = "company",
    Workspaces = new NamedCloudWorkspace("my-app-prod")
});

app.Synth();

func NewLocalBackendStack(scope constructs.Construct, name string) cdktf.TerraformStack {
    stack := cdktf.NewTerraformStack(scope, &name)

    cdktf.NewTerraformOutput(stack, jsii.String("dns-server"), &cdktf.TerraformOutputConfig{
        Value: "local",
    })

    return stack
}

func main() {
    app := cdktf.NewApp(nil)

    stack := NewLocalBackendStack(app, "hello-terraform")
    cdktf.NewCloudBackend(stack, &cdktf.CloudBackendConfig{
        Hostname:     jsii.String("app.terraform.io"),
        Organization: jsii.String("company"),
        Workspaces:   cdktf.NewNamedCloudWorkspace(jsii.String("my-app-prod"), nil),
    })

    app.Synth()
}

1. Run cdktf diff <stack name> --migrate-state to migrate the state into HCP Terraform or Terraform Enterprise.

   Initializing Terraform Cloud...
   Migrating from backend "local" to Terraform Cloud.
   Do you wish to proceed?
                 As part of migrating to Terraform Cloud, Terraform can optionally copy your
                 current workspace state to the configured Terraform Cloud workspace.
   
                 Answer "yes" to copy the latest state snapshot to the configured
                 Terraform Cloud workspace.
   
                 Answer "no" to ignore the existing state and just activate the configured
                 Terraform Cloud workspace with its existing state, if any.
   
                 Should Terraform migrate your existing state?
   
                 Enter a value:
   yes
   Initializing provider plugins...
               - Reusing previous version of hashicorp/random from the dependency lock file
   - Using previously-installed hashicorp/random v3.4.3
   Terraform Cloud has been successfully initialized!
   

Supported Backends

In addition to HCP Terraform, Terraform and CDKTF support the following backends.

• local
  new LocalBackend(stack, {...});
  
• azurerm
  new AzurermBackend(stack, {...});
  
• consul
  new ConsulBackend(stack, {...});
  
• cos
  new CosBackend(stack, {...});
  
• gcs
  new GcsBackend(stack, {...});
  
• http
  new HttpBackend(stack, {...});
  
• oss
  new OssBackend(stack, {...});
  
• pg
  new PgBackend(stack, {...});
  
• s3
  new S3Backend(stack, {...});
  

Escape Hatches

Escape hatches can add to or override existing resources, and you can use them for backends or backend constructs that CDKTF does not natively support. Escape hatch methods have an Override suffix (e.g., addOverride).

The following example uses an escape hatch to add an unsupported remote backend on a Stack object.

stack.addOverride("terraform.backend", {
  atlas: {
    name: "example_corp/networking-prod",
    address: "https://app.terraform.io",
  },
});

stack.addOverride("terraform.backend", new HashMap<String, HashMap>() {
    {
        put("atlas", new HashMap<String, String>() {
            {
                put("name", "example_corp/networking-prod");
                put("address", "https://app.terraform.io");
            }
        });
    }
});

stack.add_override("terraform.backend",{
    "atlas": {
        "name": "example_corp/networking-prod",
        "address": "https://app.terraform.io"
    }
})

stack.AddOverride("terraform.backend", new Dictionary<String, Object> {
  { "atlas", new Dictionary<String, Object> {
    { "name", "example_corp/networking-prod" },
    { "address", "https://app.terraform.io" }
  }
});

stack.AddOverride(jsii.String("terraform.backend"), &map[string]map[string]string{
    "atlas": {
        "name":    "example_corp/networking-prod",
        "address": "https://app.terraform.io",
    },
})