xraydev/terraform-ci repository overview

⁠Terraform CI/CD Runner

⁠Description

This Docker image is tailor-made for CI/CD pipelines, specifically designed to automate Terraform tasks such as validation, planning, application, and destruction of infrastructure. Based on Alpine Linux, it's a lightweight yet robust solution for managing your cloud infrastructure efficiently.

⁠Features

• Lightweight & Secure: Built on Alpine Linux for enhanced security and performance.
• Terraform Ready: Comes pre-installed with the latest stable version of Terraform for immediate use.
• CI/CD Optimized: Perfectly suited for seamless integration into any CI/CD pipeline, ensuring automated and reliable infrastructure deployment.
• Ideal for teams looking to streamline their DevOps workflows with Terraform in a reliable and secure manner.

⁠Terraform and GitLab CI/CD Integration Guide

This guide outlines the steps for setting up a Terraform project within GitLab, configuring the necessary backend, and managing CI/CD variables. It also details how to write the .gitlab-ci.yml to automate Terraform operations such as initialization, validation, application, and destruction of infrastructure.

⁠Configuring Terraform Backend Using GitLab

To integrate Terraform with GitLab's managed state services, follow these steps:

1. Navigate to your GitLab project settings:

   • Go to your project on GitLab.com.
   • Click on Operate in the sidebar, then select Terraform states.
   • Click Copy Terraform init command.

   You will receive a command similar to the following:

   export GITLAB_ACCESS_TOKEN=<YOUR-ACCESS-TOKEN>
   export TF_STATE_NAME=$TF_STATE_NAME
   terraform init \
       -backend-config="address=https://gitlab.com/api/v4/projects/YOUR_PROJECT_ID/terraform/state/$TF_STATE_NAME" \
       -backend-config="lock_address=https://gitlab.com/api/v4/projects/YOUR_PROJECT_ID/terraform/state/$TF_STATE_NAME/lock" \
       -backend-config="unlock_address=https://gitlab.com/api/v4/projects/YOUR_PROJECT_ID/terraform/state/$TF_STATE_NAME/lock" \
       -backend-config="username=YOUR_USER_NAME" \
       -backend-config="password=$GITLAB_ACCESS_TOKEN" \
       -backend-config="lock_method=POST" \
       -backend-config="unlock_method=DELETE" \
       -backend-config="retry_wait_min=5"
   

   Copy

   Explanation:

   • address: URL to the Terraform state file stored on GitLab.
   • lock_address: URL to acquire a state lock, preventing others from writing to the state.
   • unlock_address: URL to release a state lock.
   • retry_wait_min: Minimum time to wait before retrying after a lock error.

2. Add these configurations to your main.tf file:

   terraform {
     backend "http" {
         address        = "https://gitlab.com/api/v4/projects/YOUR_PROJECT_ID/terraform/state/$TF_STATE_NAME"
         lock_address   = "https://gitlab.com/api/v4/projects/YOUR_PROJECT_ID/terraform/state/$TF_STATE_NAME/lock"
         unlock_address = "https://gitlab.com/api/v4/projects/YOUR_PROJECT_ID/terraform/state/$TF_STATE_NAME/lock"
     }
   }
   

   Copy

⁠Setting Up CI/CD Variables in GitLab

To configure your project's CI/CD pipeline with the necessary Terraform variables, follow these steps:

1. Go to your project settings in GitLab:

   • Navigate to Settings > CI/CD.
   • Under the Variables section, click Add variable.

2. Add the following variables:

   • AWS_ACCESS_KEY_ID (AWS IAM with EC2 full access).
   • AWS_SECRET_ACCESS_KEY.
   • TF_STATE_NAME (default value: default).
   • GITLAB_ACCESS_TOKEN (create this under Settings > Access Tokens with the role of Maintainer and all scopes checked).

   Ensure each variable is set as:

   • Protected:
     • AWS_ACCESS_KEY_ID
     • AWS_SECRET_ACCESS_KEY
     • TF_STATE_NAME
     • GITLAB_ACCESS_TOKEN
   • Masked:
     • AWS_ACCESS_KEY_ID
     • AWS_SECRET_ACCESS_KEY
     • TF_STATE_NAME
     • GITLAB_ACCESS_TOKEN
   • Expand variable reference:
     • TF_STATE_NAME
     • GITLAB_ACCESS_TOKEN

⁠.gitlab-ci.yml Configuration for Terraform

This YAML file defines the stages and jobs for the Terraform operations in your GitLab CI/CD pipeline.

stages:
  - init
  - fmt
  - validate
  - plan
  - apply
  - destroy

image: xraydev/terraform-ci:latest

cache:
  paths:
    - .terraform/

terraform_init:
  stage: init
  script:
    - echo "Initializing Terraform"
    - >
      terraform init
      -backend-config="username=$GITLAB_USER_LOGIN"
      -backend-config="password=$GITLAB_ACCESS_TOKEN"
      -backend-config="lock_method=POST"
      -backend-config="unlock_method=DELETE"
      -backend-config="retry_wait_min=5"

terraform_fmt:
  stage: fmt
  script:
    - echo "Checking Terraform file formatting"
    - terraform fmt -check

terraform_validate:
  stage: validate
  script:
    - echo "Validating Terraform configuration"
    - terraform validate

terraform_plan:
  stage: plan
  script:
    - echo "Planning Terraform configuration"
    - gitlab-terraform plan
    - gitlab-terraform plan-json
  artifacts:
    paths:
      - .terraform/plan.cache
    reports:
      terraform: .terraform/plan.json

terraform_apply:
  stage: apply
  script:
    - echo "Applying Terraform configuration"
    - terraform apply -auto-approve
  only:
    - main
  when: manual

terraform_destroy:
  stage: destroy
  script:
    - echo "Destroying Terraform infrastructure"
    - terraform destroy -auto-approve
  when: manual

Note: The terraform_apply and terraform_destroy stages require manual activation for safety reasons. You can automate it by commenting out when: manual if necessary.