Terraform Backends

The following backends are supported directly in the plugin

Any other backend, can be supported by setting the appropriate tokens on GenericBackend.

Configuring the local backend

Most people using Terraform local state would probably just store terraform.tfstate in the same directory as the source and commit that to source control. In some cases this might not be what you want. For example you might want to apply terraform to a LocalStack instance and have no need for keeping the state. The state path can be configured.

import org.ysb33r.gradle.terraform.backends.LocalBackend

terraform {
  backends {
    local(LocalBackend) {
        path = 'my/other/path' (1)
    }
  }
  sourceSets {
    main {
      usedBackend('local')
    }
  }
}

1	Set a different path where to store local state.

main.tf

terraform {
  backend "local" {}
}

Configuring a generic backend

If you are using a backend that is not directly supported by this plugin suite, you can still use it by some manipulation of the local backend.

Let’s assume you want tho use the Consul backend and, it is not supported.

import org.ysb33r.gradle.terraform.backends.GenericBackend

terraform {
  backends {
    consul(GenericBackend) {
      tokens address : "consul.example.com", (1)
            scheme : "https",
            path : "full/path"
    }
  }
  sourceSets {
    main {
      usedBackend('consul')
    }
  }
}

1	Define the attributes that you need.

main.tf

terraform {
  backend "consul" {}
}

Configuring the legacy Terraform Cloud backend

This is for the legacy remote backend.

import org.ysb33r.gradle.terraform.backends.TerraformRemoteBackend

terraform {
  backends {
    tfRemote(TerraformRemoteBackend) {
        organization = 'company'
        authToken = grolifantOps.providerTools.resolveProperty('my.tf.cloud.token')
    }
  }
  sourceSets {
    main {
      usedBackend('tfRemote')
    }
  }
}

main.tf

terraform {
  backend "remote" {}
}

Configuring the Gitlab backend

It is possible to store remote state in Gitlab and it utilises the http backend.

The Gitlab backend DOES NOT support workspaces. If you need something like workspaces, but want to use Gitlab tfstate storage, consider using multiple source sets and use local modules to share common IAC. Then configure a Gitlab backend for each source set and change the address.

build.gradle

import org.ysb33r.gradle.terraform.backends.GitlabBackend

terraform {
  backends {
    gitlab(GitlabBackend) {
        address = 'https://gitlab.com/api/v4/projects/123456/terraform/state/my-project' (1)
        username = grolifantOps.providerTools.resolveProperty('my.gitlab.username')  (2)
        accessToken = grolifantOps.providerTools.resolveProperty('my.gitlab.access.token') (3)

        retryMax = 2 (4)
        retryWaitMin= 1 (5)
        retryWaitMax = 30 (6)
    }
  }
  sourceSets {
    main {
      usedBackend('gitlab')
    }
  }
}

1	Set the location of your Gitlab endpoint. It takes the form `https://gitlab.com/api/v4/projects/<PROJECT_ID>/terraform/state/<STATE-NAME>;`, where `PROJECT_ID` is the project state will be stored in, and `STATE-NAME` is a name for the state.
2	Provide the Gitlab user name. This user needs to have at least a Gitlab `Maintainer` role to perform updates. This will be injected into the environment as `TF_USERNAME`
3	Provide the Gitlab access token. This will be injected into the environment as `TF_PASSWORD`
4	The number of HTTP request retries. Defaults to 2.
5	The minimum time in seconds to wait between HTTP request attempts. Defaults to 1.
6	The maximum time in seconds to wait between HTTP request attempts. Defaults to 30.

main.tf

terraform {
  backend "http" {}
}

Adding a new backend programmatically

See contributing/add-tofu-or-tf-backend.adoc if you would like to add a new backend.