Manage the Terraform state file

For any deployment, you may want to inspect or modify the state file. For example, you may want to import or remove resources from the deployment, which you do through modifying the state file.

This page describes how to work with the Terraform state file that is created for each deployment and revision. To learn more about the state file, see State .

The instructions on this page assume that you are familiar with Terraform .

Before you begin

Ensure you have the required permissions to work with the state file. The config.admin role includes the required permissions. The specific permissions needed are:
- config.deployments.lock
- config.revisions.getState
- config.deployments.updateState
- config.deployments.unlock
- config.deployments.getLock
- config.deployments.getState
Ensure you have a local copy of the Terraform configuration. This is the configuration that corresponds to the state file you are working with.

The local copy of the configuration allows you to run commands such as terraform refresh or terraform plan locally while you are modifying the state file.
Install Terraform to use the Terraform CLI on your local machine.

Mutate or inspect the state file

To mutate (modify) or inspect the state file, you need to lock the deployment and download the state file. You can then mutate or inspect the state file.

After you mutate the state file, you then upload the file for Infra Manager to use in your deployment.

Lock the deployment

Lock the deployment to prevent any changes to the deployment while you mutate the statefile. The deployment must be locked to be able to download the state file.
```
 gcloud  
infra-manager  
deployments  
lock  
 DEPLOYMENT_ID 
  
--project  
 PROJECT_ID 
  
--location  
 LOCATION 
 
```
Replace:
- DEPLOYMENT_ID with the deployment identifier.
- PROJECT_ID with the project where the deployment runs.
- LOCATION with the location where the deployment runs.
The output of this command contains a lock ID that is used for uploading and unlocking the statefile.

To retrieve the lock ID at any time, use the command:

 gcloud  
infra-manager  
deployments  
export-lock  
 DEPLOYMENT_ID 
  
--project  
 PROJECT_ID 
  
--location  
 LOCATION

Download the state file

To download the state file, you use a signed Cloud Storage URL :

  SIGNED_STATE_DOWNLOAD_URL 
 = 
 $( 
gcloud  
infra-manager  
deployments  
export-statefile  
 DEPLOYMENT_ID 
  
--project  
 PROJECT_ID 
  
--location  
 LOCATION 
  
--format = 
 "get(signedUri)" 
 ) 
curl  
-s  
-X  
GET  
--output  
terraform.tfstate  
 ${ 
 SIGNED_STATE_DOWNLOAD_URL 
 }

Mutate the state file locally

Confirm that the configuration ( *.tf files) is in the same directory as the downloaded state file ( terraform.tfstate ).
Initialize Terraform:
```
 terraform  
init 
```
If you have previously initialized Terraform, you may need to initialize with the reconfigure flag:
```
 terraform  
init  
-reconfigure 
```
Work with the state file as you need. For example, you can do state inspection or mutation operations. For more details about working with the state file, see Manipulating Terraform State .
If you make any changes to the Terraform configuration files locally, then upload the modified configuration. Upload this configuration to the storage bucket or public git repository that you are using as the source to deploy the configuration.

Upload the state file

Use a signed Cloud Storage URL to upload the state file:

Get the lock ID:

  LOCK_ID 
 = 
 $( 
gcloud  
infra-manager  
deployments  
export-lock  
 DEPLOYMENT_ID 
  
--project  
 PROJECT_ID 
  
--location  
 LOCATION 
  
--format = 
 "get(lockId)" 
 )

Get the upload URL:

  SIGNED_STATE_UPLOAD_URL 
 = 
 $( 
gcloud  
infra-manager  
deployments  
import-statefile  
 DEPLOYMENT_ID 
  
--project  
 PROJECT_ID 
  
--location  
 LOCATION 
  
--lock-id  
 ${ 
 LOCK_ID 
 } 
  
--format = 
 "get(signedUri)" 
 ) 
curl  
-s  
-X  
PUT  
--upload-file  
terraform.tfstate  
 ${ 
 SIGNED_STATE_UPLOAD_URL 
 }

Unlock the deployment