Resource Definitions

Driver

Capability

Flavor

Resource Type

Backends

GitLab HTTP Backend using Long Lived credentials

GitLab implements the Terraform HTTP backend . In order to use the Terraform backend in GitLab, the following is needed:

  • A Personal Access Token with api scope
  • A GitLab project that the token has access to.

This example has a simple resource definition using the Terraform Driver. The backend configuration is generated via a config resource and then injected as a file in the terraform resource definition using a placeholder.

The following needs to be defined in the config for this example to work:

  • .entity.driver_inputs.values.gitlab_project_id - Should be the numerical ID of the GitLab project being used to store the state
  • .entity.driver_inputs.secret_refs.username - The username that the Personal Access token is associated with
  • .entity.driver_inputs.secret_refs.password - The value of the Personal Access token

Resource Definitions

gitlab-backend.yaml ( view on GitHub ) :

# This Resource Definition uses GitLab as the Terraform backend to store Terraform state
apiVersion: entity.humanitec.io/v1b1
kind: Definition
metadata:
  id: example-terraform-gitlab-backend-s3
entity:
  driver_inputs:
    values:
      files:
        main.tf: |
          resource "random_id" "thing" {
            byte_length = 8
          }

          output "bucket" {
            value = random_id.thing.hex
          }
    secrets:
      files:
        # We don't supply the res_id so that it can be passed through to build the state key
        backend.tf: ${resources['config.tf-runner'].outputs.backend_tf}
  driver_type: humanitec/terraform
  name: example-terraform-gitlab-backend-s3
  type: s3

  # Supply matching criteria
  criteria: []

tf-be-config.yaml ( view on GitHub ) :

# This Resource Definition provides backend configuration for using GitLab to store the Terraform state.
apiVersion: entity.humanitec.io/v1b1
kind: Definition
metadata:
  id: example-terraform-gitlab-backend-config

entity:
  criteria:
  - class: tf-runner
  driver_type: humanitec/template
  driver_inputs:
    values:
      # Provide the ID of the GitLab Project - it should be a long number as a string
      gitlab_project_id: ""
      state_name: ${context.app.id}_${context.env.id}_${context.res.id}
      templates:
        init: |
          address: https://gitlab.com/api/v4/projects/{{ .driver.values.gitlab_project_id }}/terraform/state/{{ .driver.values.state_name | replace "." "_" }}
        outputs: |
          # Useful for debugging to output the address as an output
          address: {{ .init.address }}
        secrets: |
          backend_tf: |
            terraform {
              # https://developer.hashicorp.com/terraform/language/v1.5.x/settings/backends/configuration
              # https://developer.hashicorp.com/terraform/language/v1.5.x/settings/backends/http
              backend "http" {
                address = "{{ .init.address }}"
                lock_address = "{{ .init.address }}/lock"
                lock_method = "POST"
                unlock_address = "{{ .init.address }}/lock"
                unlock_method = "DELETE"
                username = "{{ .driver.secrets.username }}"
                password = "{{ .driver.secrets.password }}"
                retry_wait_min = 5
              }
            }
    secret_refs:
      # The Username associated with your Personal Access Token
      username:
        store:
        ref:
      # The Personal Access Token
      password:
        store:
        ref:
  type: config
  name: example-terraform-gitlab-backend-config

gitlab-backend.tf ( view on GitHub ) :

resource "humanitec_resource_definition" "example-terraform-gitlab-backend-s3" {
  driver_type = "humanitec/terraform"
  id          = "example-terraform-gitlab-backend-s3"
  name        = "example-terraform-gitlab-backend-s3"
  type        = "s3"
  driver_inputs = {
    values_string = jsonencode({
      "files" = {
        "main.tf" = <<END_OF_TEXT
resource "random_id" "thing" {
  byte_length = 8
}

output "bucket" {
  value = random_id.thing.hex
}
END_OF_TEXT
      }
    })
    secrets_string = jsonencode({
      "files" = {
        "backend.tf" = "$${resources['config.tf-runner'].outputs.backend_tf}"
      }
    })
  }
}

tf-be-config.tf ( view on GitHub ) :

resource "humanitec_resource_definition" "example-terraform-gitlab-backend-config" {
  driver_type = "humanitec/template"
  id          = "example-terraform-gitlab-backend-config"
  name        = "example-terraform-gitlab-backend-config"
  type        = "config"
  driver_inputs = {
    values_string = jsonencode({
      "gitlab_project_id" = ""
      "state_name"        = "$${context.app.id}_$${context.env.id}_$${context.res.id}"
      "templates" = {
        "init"    = "address: https://gitlab.com/api/v4/projects/{{ .driver.values.gitlab_project_id }}/terraform/state/{{ .driver.values.state_name | replace \".\" \"_\" }}\n"
        "outputs" = <<END_OF_TEXT
# Useful for debugging to output the address as an output
address: {{ .init.address }}
END_OF_TEXT
        "secrets" = <<END_OF_TEXT
backend_tf: |
  terraform {
    # https://developer.hashicorp.com/terraform/language/v1.5.x/settings/backends/configuration
    # https://developer.hashicorp.com/terraform/language/v1.5.x/settings/backends/http
    backend "http" {
      address = "{{ .init.address }}"
      lock_address = "{{ .init.address }}/lock"
      lock_method = "POST"
      unlock_address = "{{ .init.address }}/lock"
      unlock_method = "DELETE"
      username = "{{ .driver.secrets.username }}"
      password = "{{ .driver.secrets.password }}"
      retry_wait_min = 5
    }
  }
END_OF_TEXT
      }
    })
    secret_refs = jsonencode({
      "username" = {
        "store" = null
        "ref"   = null
      }
      "password" = {
        "store" = null
        "ref"   = null
      }
    })
  }
}

resource "humanitec_resource_definition_criteria" "example-terraform-gitlab-backend-config_criteria_0" {
  resource_definition_id = resource.humanitec_resource_definition.example-terraform-gitlab-backend-config.id
  class                  = "tf-runner"
}