Terraform State File Management (Part 2: Gitlab)

Terraform State File Management (Part 2: Gitlab)

Gitlab-managed terraform state over http backend


4 min read


Welcome to the second part of my post on Terraform Start Management. In Part 1 we discuss what Terraform State is, its importance and how terraform default behaviour is to store the state file in the local project working directory.

In this second part, we will configure terraform to store its State file in a remote repository on Gitlab using terraform HTTP backend.

  • NB: Gitlab also supports versioning of Terraform state files, encryption "in transit/at rest" of the state files as well as state lock/unlock.

Create a Gitlab account and GitLab Personal Access Token.

The first step is to head to gitlab.com and create the account. Log into your account, in the top right corner click on your avatar and click on "Edit Profile".

  • On the left side of the page in your User Setting menu, click on Access Token. Input a token name, select "api" scope and click "create personal access token".


  • This will generate a token similar to the on below that will be require by terraform to authenticate against Gitlab to write or read the terraform state. image.png

Create new Gitlab project

Now let's create a new Gitlab project in which the state file will be stored. Simply click on "Menu" in the upper left corner of your page, select "Projects" and click "Create new Project"

Screenshot 2022-05-15 at 6.24.14 PM.png

Then click "Create Blank Project", input a project name, keep visibility private and click "Create project". This will create a project with a "Project ID" that will be needed for the state configuration.


Update terraform configuration

  • Define a http backend configuration block

In order for the terraform state file to be stored on Gitlab, you are required to configure an http backend by adding a backend configure block to the terraform configuration block and in this example located in main.tf

# Terraform version & Providers #
terraform {
  required_version = ">=1.0.0"

  required_providers {
    # AWS provider
    aws = {
      source  = "hashicorp/aws"
      version = "~> 3.0"

  backend "http" {
    address        = "https://gitlab.com/api/v4/projects/36152149/terraform/state/aws-root-tfstate"
    lock_address   = "https://gitlab.com/api/v4/projects/36152149/terraform/state/aws-root-tfstate/lock"
    unlock_address = "https://gitlab.com/api/v4/projects/36152149/terraform/state/aws-root-tfstate/lock"
    lock_method    = "POST"
    unlock_method  = "DELETE"
    # gitlab_username      = " "
    # gitlab_token         = " "

# AWS Region & AWS credential #
provider "aws" {
  region                  = local.aws_region
  shared_credentials_file = local.aws_credential_file
  profile                 = local.aws_profile

NB: Remember to update the "project_id" and "state_file_name" with your own values. You will also notice that "gitlab_username" and "personal token" are commented out. This is to separate the gitlab credential from the general config that could end up in a version control system.


  • Gitlab credential file

Create a Gitlab credential file name "backend_cred.conf" or whatever you want it. username is your Gitlab name and password is your personal access token.

username       = "m.komlaetou"
password       = "glpat-sBU5V7zBzyWpdzULWJyx"

Reinitialise the terraform module

Now that all configurations are completed, reinitialise your terraform module with the command below. The command will also allow you migrate the local state file information to the remote state file

terraform init -reconfigure -backend-config=backend_cred.conf


Finally run the "terraform plan" command to ensure everything is working. The local state file will still existing in the working directory but will totally be empty and can be deleted.

Locate State File in Gitlab

In Gitlab click on the project you created for the terraform state file, in the project property menu click on the Infrastructure tab then on Terraform. There, you will locate your infrastructure terraform state file


Take notice that anytime changes are being made on the infrastructure (terraform plan or terraform apply), the state file will be in locked state.

NB: Due to the fact the remote state file will be access by other team members, it is recommended not to lock the state file during the planning stage using "terraform plan -lock=false" command instead of just "terraform plan"


Part 1: Local Backend State File.

๐Ÿ’ฅ๐Ÿ’ฅ๐Ÿ’ฅ๐Ÿ’ฅ Happy Terraforming ! ๐Ÿ’ฅ๐Ÿ’ฅ๐Ÿ’ฅ๐Ÿ’ฅ๐Ÿ’ฅ๐Ÿ’ฅ