How to set up Terraform on GitLab

If you use the GitLab platform, you can be tempted to move pretty much all aspects of your development to them - since you already pay for it because of the feature X, why not use Y & Z that comes in the plan. One of the features I was recently investigating is infrastructure-as-code with Terraform.


Terraform is a tool that allows us to describe in a file what infrastructure we want. So, for example, we have

provider "aws" {
  region = "eu-west-1"

resource "aws_instance" "example" {
  ami           = "ami-0f89681a05a3a9de7"
  instance_type = "t2.micro"
  subnet_id       = "subnet-1234"

  tags = {
    Name = "terraform-example"

This file, we manage in the same way as we would manage any source code - by putting it under a version control system (most likely git). Then, when we have changes to the environment description, Terraform figures out what to remove/add/update apply the changes to the infrastructure. In this way, we can do our DevOps in git - the so-called GitOps. I'm new to this, but I definitively want to keep all the important information in a repository.

Terraform on GitLab

So far, we have talked about changes & existing infrastructure. There is one important piece missing - the current, expected state. Terraform, on its own, will not remember what severs are already started by it, and we need a backend to store this information. When we use the backend provided by GitLab, we will additionally get an overview of our infrastructure in the GitLab UI.

The best resource on this topic is one of the articles on GitLab documentation. In short, you should be able to do:

  1. make some changes from the localhost, and save their result on GitLab, so they appear in the Terraform tab
  2. get the same thing up & running, so you have a deployment task in your repo CI - if you trigger the deployment once, it should create the infrastructure & update the Terraform tab. If you trigger after that, it should fail because it recognizes the changes were already applied.

Documenation caveat

If you tried following some Terraform documentation from GitLab and got very frustrated - you are not alone. Two articles cover this topic, and the one I linked above is doing a pretty good job. Make sure you check out this article:

Screenshot 2021-07-20 at 22-13-06 GitLab managed Terraform State GitLab.png

Before you give up on setting up Terraform.


Terraform looks like an exciting approach to managing the infrastructure, and I'll definitively keep on investigating it. The GitLab integration can be nice if you use their platform, and after all, they do have good documentation about it - but you have to look out not to fall into the trap of a not-so-helpful guide.