gitlab-org--gitlab-foss/doc/administration/terraform_state.md

stage	group	info
Configure	Configure	To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments

Terraform state administration (FREE)

Introduced in GitLab 12.10.

GitLab can be used as a backend for Terraform state files. The files are encrypted before being stored. This feature is enabled by default.

The storage location of these files defaults to:

• /var/opt/gitlab/gitlab-rails/shared/terraform_state for Omnibus GitLab installations.
• /home/git/gitlab/shared/terraform_state for source installations.

These locations can be configured using the options described below.

Use external object storage configuration for GitLab Helm chart installations.

Disabling Terraform state

To disable terraform state site-wide, follow the steps below. A GitLab administrator may want to disable Terraform state to reduce disk space or if Terraform is not used in your instance. To do so, follow the steps below according to your installation's type.

In Omnibus installations:

1. Edit /etc/gitlab/gitlab.rb and add the following line:

   gitlab_rails['terraform_state_enabled'] = false
   

2. Save the file and reconfigure GitLab for the changes to take effect.

In installations from source:

1. Edit /home/git/gitlab/config/gitlab.yml and add or amend the following lines:

   terraform_state:
     enabled: false
   

2. Save the file and restart GitLab for the changes to take effect.

Using local storage

The default configuration uses local storage. To change the location where Terraform state files are stored locally, follow the steps below.

In Omnibus installations:

1. To change the storage path for example to /mnt/storage/terraform_state, edit /etc/gitlab/gitlab.rb and add the following line:

   gitlab_rails['terraform_state_storage_path'] = "/mnt/storage/terraform_state"
   

2. Save the file and reconfigure GitLab for the changes to take effect.

In installations from source:

1. To change the storage path for example to /mnt/storage/terraform_state, edit /home/git/gitlab/config/gitlab.yml and add or amend the following lines:

   terraform_state:
     enabled: true
     storage_path: /mnt/storage/terraform_state
   

2. Save the file and restart GitLab for the changes to take effect.

Using object storage (FREE SELF)

Instead of storing Terraform state files on disk, we recommend the use of one of the supported object storage options. This configuration relies on valid credentials to be configured already.

Read more about using object storage with GitLab.

Object storage settings

The following settings are:

• Nested under terraform_state: and then object_store: on source installations.
• Prefixed by terraform_state_object_store_ on Omnibus GitLab installations.

Setting	Description	Default
enabled	Enable/disable object storage	false
remote_directory	The bucket name where Terraform state files are stored
connection	Various connection options described below

Migrate to object storage

Introduced in GitLab 13.9.

WARNING: It's not possible to migrate Terraform state files from object storage back to local storage, so proceed with caution. An issue exists to change this behavior.

To migrate Terraform state files to object storage, follow the instructions below.

• For Omnibus package installations:

  gitlab-rake gitlab:terraform_states:migrate
  

• For source installations:

  sudo -u git -H bundle exec rake gitlab:terraform_states:migrate RAILS_ENV=production
  

For GitLab 13.8 and earlier versions, you can use a workaround for the Rake task:

1. Open the GitLab Rails console.

2. Run the following commands:

   Terraform::StateUploader.alias_method(:upload, :model)
   
   Terraform::StateVersion.where(file_store: ::ObjectStorage::Store::LOCAL).   find_each(batch_size: 10) do |terraform_state_version|
     puts "Migrating: #{terraform_state_version.inspect}"
   
     terraform_state_version.file.migrate!(::ObjectStorage::Store::REMOTE)
   end
   

You can optionally track progress and verify that all packages migrated successfully using the PostgreSQL console:

• sudo gitlab-rails dbconsole for Omnibus GitLab instances.
• sudo -u git -H psql -d gitlabhq_production for source-installed instances.

Verify objectstg below (where store=2) has count of all states:

gitlabhq_production=# SELECT count(*) AS total, sum(case when store = '1' then 1 else 0 end) AS filesystem, sum(case when store = '2' then 1 else 0 end) AS objectstg FROM terraform_states;

total | filesystem | objectstg
------+------------+-----------
   15 |          0 |      15

Verify that there are no files on disk in the terraform_state folder:

sudo find /var/opt/gitlab/gitlab-rails/shared/terraform_state -type f | wc -l

S3-compatible connection settings

See the available connection settings for different providers.

In Omnibus installations:

1. Edit /etc/gitlab/gitlab.rb and add the following lines; replacing with the values you want:

   gitlab_rails['terraform_state_object_store_enabled'] = true
   gitlab_rails['terraform_state_object_store_remote_directory'] = "terraform"
   gitlab_rails['terraform_state_object_store_connection'] = {
     'provider' => 'AWS',
     'region' => 'eu-central-1',
     'aws_access_key_id' => 'AWS_ACCESS_KEY_ID',
     'aws_secret_access_key' => 'AWS_SECRET_ACCESS_KEY'
   }
   

   NOTE: If you are using AWS IAM profiles, be sure to omit the AWS access key and secret access key/value pairs.

   gitlab_rails['terraform_state_object_store_connection'] = {
     'provider' => 'AWS',
     'region' => 'eu-central-1',
     'use_iam_profile' => true
   }
   

2. Save the file and reconfigure GitLab for the changes to take effect.

3. Migrate any existing local states to the object storage

In installations from source:

1. Edit /home/git/gitlab/config/gitlab.yml and add or amend the following lines:

   terraform_state:
     enabled: true
     object_store:
       enabled: true
       remote_directory: "terraform" # The bucket name
       connection:
         provider: AWS # Only AWS supported at the moment
         aws_access_key_id: AWS_ACCESS_KEY_ID
         aws_secret_access_key: AWS_SECRET_ACCESS_KEY
         region: eu-central-1
   

2. Save the file and restart GitLab for the changes to take effect.

3. Migrate any existing local states to the object storage