Scaffolding GitLab CI/CD Pipeline (Terraform Cloud)

This repository demonstrates how to integrate the Resourcely guardrail validation job into a repository using GitLab CI/CD and Terrafom Cloud. It runs Terraform using the official Hashicorp Terraform Cloud Docker Images.

Assumption

This repository uses GitLab CI/CD + Terraform Cloud to generate a Terraform plan. Once a plan is downloaded to a specified directory, the Resourcely guardrail validation job runs on the configured path. If you use a different runner, see the scaffolding repository for that runner:

• GitHub Actions
• GitHub Actions + Terraform Cloud
• GitLab CI/CD

Prerequisites

1. A Resourcely Account
2. Resourcely GitLab SCM Configured
3. GitLab Premium or Ultimate subscription
4. Maintainer Role or Higher in the GitLab project
5. A Terraform Cloud Instance configured with Resourcely
6. AWS Provider Credentials configured in Terraform Cloud

Setup

1. Import this project to your GitLab group by URL
   a. On the left sidebar, at the top, select Create new (+) and New project/repository
   b. Select Import project
   c. Select Repository by URL
   d. Enter the Git repository URL: https://github.com/Resourcely-Inc/scaffolding-gitlab-pipeline-terraform-cloud.git
   e. Complete the remaining fields
   f. Select Create project
2. Allow Resourcely to monitor the newly created project
3. Generate a Resourcely API Token and save it in a safe place
4. Add your Resourcely API Token to your GitLab project CI/CD variables
   a. Go to the GitLab project that Resourcely will validate
   b. In the side tab, navigate to Settings > CI/CD
   c. Expand the Variables tab
   d. Click the Add variable button
   e. Add the RESOURCELY_API_TOKEN as the key and the token as the value
   f. Evaluate whether to unselect Protect variable, depending on the need to use the token in un-protected branches, while considering security implications
   g. Select the Mask variable to protect sensitive data from being seen in job logs
   h. Unselect Expand variable reference
   i. Press the Add variable button
5. Generate a Terraform Cloud Team Token
6. Add the Terraform Cloud Team token TF_API_TOKEN to GitLab following the same process in step 3
7. Configure Terraform Cloud Credentials a. Edit .gitlab-ci.yml
   b. Edit the value of TF_CLOUD_ORGANIZATION to match your Terraform Cloud Organization
   c. Edit the value of TF_WORKSPACE to match your Terraform Cloud Workspace
   d. Edit the value of TF_CLOUD_HOSTNAME to match your Terraform Cloud Hostname
   e. Commit the .gitlab-ci.yml file to your main branch
8. Provision Infrastructure using Resourcely

Once a new Resource has been created via Merge-Request, the Resourcely job will automatically kick-off. It runs in the test stage by default.

How it works

When a merge-request is created using Resourcely:

1. GitLab CI kicks off the plan stage a. The mjyocca/tfci:latest container image is loaded for multiple jobs via the remote import of tfc-workflows-gitlab template that is included in this project's .gitlab-ci.yml
   b. upload_configuration job is run to create and upload a configuration version to terraform-cloud.variables
   c. create_run job is run to create a Terraform Cloud run
   d. plan_output job is run to output the Terraform Plan details
   e. The alpine/curl container image is loaded for the download_plan job
   f. Call to the terraform API is peformed in order to download the Terraform plan json
2. After the plan stage completes, GitLab CI kicks off the test stage a. The test stage is loaded by the Resourcely template that is included in this project's .gitlab-ci.yml
   b. The ghcr.io/resourcely-inc/resourcely-cli:$RESOURCELY_IMAGE container image is loaded
   c. The resourcely_guardrails job runs resourcely-cli evaluate scanning the Terraform plan json(s)
   d. The resources generated with resourcely within the merge-request are validated against your Resourcely guardrails
3. The test stage completes a. If guardrail violations are found, Resourcely will assign a reviewer to the merge-request and require approval before it can be merged