Terraform state settings

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab Self-Managed

You can configure settings for Terraform state files, including encryption and storage limits.

Terraform state encryption

By default, GitLab encrypts Terraform state files before storing them. You can turn off encryption if needed.

When encryption is turned off, Terraform state files are stored as they are received, without any encryption applied.

Prerequisites:

  • You must have administrator access.

To configure Terraform state encryption:

  1. In the upper-right corner, select Admin.
  2. In the left sidebar, select Settings > Preferences.
  3. Expand Terraform state.
  4. Select or clear the Turn on Terraform state encryption checkbox.
  5. Select Save changes.

When you turn off encryption, the change affects only new Terraform state files. Existing encrypted files remain encrypted and continue to work as expected.

Encryption key rotation

You cannot rotate the Terraform state encryption key.

The encryption key is derived from the db_key_base application secret and the project ID. For more information, see decryption process. Because the key is derived rather than stored directly, no standalone Terraform state key exists to rotate.

Rotating db_key_base itself is not supported because it encrypts data across the entire instance, including CI/CD variables, integration and webhook credentials, and authentication tokens.

If you change db_key_base, existing Terraform state files become unreadable. GitLab raises an error if more than one db_key_base is configured and no re-encryption tool exists.

Key rotation is proposed in issue 25332.

Terraform state storage limits

You can limit the total storage of Terraform state files. The limit applies to each individual state file version and is checked when a new version is created.

Prerequisites:

  • You must have administrator access.

To add a storage limit:

  1. In the upper-right corner, select Admin.
  2. In the left sidebar, select Settings > Preferences.
  3. Expand Terraform state.
  4. In the Terraform state size limit (bytes) field, enter a size limit in bytes. Set to 0 to allow files of unlimited size.
  5. Select Save changes.

When Terraform state files exceed this limit, GitLab does not save them and rejects the associated Terraform operations.