Remote Backends
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
.
When you call cdktf synth
, CDKTF generates a JSON file called remote.tf.json
in 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.
The following example shows the generated remote.tf.json
file.
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
.
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:
Navigate into the main project directory.
Use
CloudBackend
to add a new remote backend.
Run
cdktf diff <stack name> --migrate-state
to migrate the state into HCP Terraform / Terraform Enterprise.
Supported Backends
In addition to HCP Terraform, Terraform and CDKTF support the following backends.
Note: CDK for Terraform v0.14 deprecated the artifactory, etcd, etcdv3, manta, and swift backends, and removed them in v0.20. Terraform removed these backends in v1.3. For migration paths from these removed backends, refer to Upgrading to Terraform v1.3.
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.