How do you rename a GitLab managed Terraform state file without destroying existing infrastructure?

I have some Terraform being managed and its IaC deployed via a CI/CD pipeline in GitLab. I currently store the Terraform state in GitLab as well as all other related environments.

However, I have recently run into an issue that is requiring me to change the name of my GitLab managed Terraform state file. How can I modify the name of my state file without having to destroy and/or redeploy infrastructure already managed by the old state file?

I haven't managed to find any resources online indicating how to do so without letting infrastructure go down (which is what I'm trying to avoid).

You can migrate the state, but as you'll be doing so within the same project, it'll just be the same as if you have renamed it.

The steps for this process look as follows:

1. First initialise locally the Terraform state with your current state

export GITLAB_ACCESS_TOKEN=$YOUR_GITLAB_ACCESS_TOKEN
export TF_ADDRESS="https://gitlab.com/api/v4/projects/$YOUR_PROJECT_ID/terraform/state/$CURRENT_STATE_NAME"
terraform init \
    -backend-config="address=${TF_ADDRESS}" \
    -backend-config="lock_address=${TF_ADDRESS}/lock" \
    -backend-config="unlock_address=${TF_ADDRESS}/lock" \
    -backend-config="username=$YOUR_USERNAME" \
    -backend-config="password=$GITLAB_ACCESS_TOKEN" \
    -backend-config="lock_method=POST" \
    -backend-config="unlock_method=DELETE" \
    -backend-config="retry_wait_min=5"

2. Run terraform init with the -migrate-state with the new name of the state so it will be copied. You'll have to respond with yes on the terminal for the process to kick in.

export TF_ADDRESS="https://gitlab.com/api/v4/projects/$YOUR_PROJECT_ID/terraform/state/$NEW_STATE_NAME"
terraform init \
  -migrate-state \
  -backend-config=address=${TF_ADDRESS} \
  -backend-config=lock_address=${TF_ADDRESS}/lock \
  -backend-config=unlock_address=${TF_ADDRESS}/lock \
  -backend-config=username=$YOUR_GITLAB_USERNAME \
  -backend-config=password=${GITLAB_ACCESS_TOKEN} \
  -backend-config=lock_method=POST \
  -backend-config=unlock_method=DELETE \
  -backend-config=retry_wait_min=5

Having run the above two commands, you can navigate to Operate > Terraform States and double-check that a new state has been created according to the value of $NEW_STATE_NAME. And from now on if your CI variable $TF_STATE_NAME makes use of this new value the config will be able to use it.

Hope it helps!