How to use Git Submodules with Terraform Enterprise

Introduction

Git submodules allow a Terraform configuration repository to include and reference another Git repository at a specific commit. In Terraform Enterprise (TFE), this enables teams to reuse shared Terraform code across multiple workspaces.

Prerequisites

• Terraform Enterprise
• VCS Provider such as Github

This approach was validated and tested using Github VCS provider or Terraform Enterprise version 1.1.1

Steps

Step 1: Create a main Github repository

• Log in to GitHub

• Click New repository

• Enter a repository name (e.g., terraform-main)

• Select repository visibility (Private recommended)

• Click Create repository 

Step 2: Create a secondary Github repository

• In GitHub, click New repository

• Enter a repository name (e.g., terraform-secondary)

• Select repository visibility

• Click Create repository

Step 3: Initialize the main repository

• On your laptop, open a terminal.
• Create a test directory

$ mkdir ~/test-directory

• Change directory

$ cd ~/test-directory

• Clone the main repository

$ git clone https://github.com/<org>/<terraform-main>.git

• Change directory to the main repository

$ cd terraform-main

• Create a README.md file

$ echo "# This is a test for Git Submodules - Main Repository" > README.md

• Commit and Push the changes

$ git add .
$ git commit -m "Initial commit"
$ git push

Step 4: Initialize the secondary repository

• On your laptop, open a terminal.
• Change directory

$ cd ~/test-directory

• Clone the main repository

$ git clone https://github.com/<org>/<terraform-secondary>.git

• Change directory to the main repository

$ cd terraform-secondary

• Create a README.md file

$ echo "# This is a test for Git Submodules - Secondary Repository" > README.md

• Create a main.tf file with the following content

resource "null_resource" "this" {
}
output "test" {
  value = "Hello from sub-repo"
}

• Commit and Push the changes

$ git add .
$ git commit -m "Initial commit"
$ git push

Step 5: Enable Submodules in the main repository

• On your laptop, open a terminal.
• Change directory

$ cd ~/test-directory/terraform-main

• Add the terraform-secondary as a submodule to the terraform-main repository

# Option A use HTTPS URL
$ git submodule add https://github.com/<org>/<terraform-secondary>.git
# Option B use SSH URL
$ git submodule add git@github.com:<org>/<terraform-secondary>.git

• Verify the content of the .gitmodules file

# In case of HTTPS URL is used
$ cat .gitmodules
[submodule "terraform-secondary"]
	path = terraform-secondary
	url = https://github.com/<org>/<terraform-secondary>.git
	
# In case of SSH URL is used
$ cat .gitmodules
[submodule "terraform-secondary"]
	path = terraform-secondary
	url = git@github.com:<org>/<terraform-secondary>.git

• Commit and push the changes

$ git add .
$ git commit -m "adding submodule"
$ git push

Step 6: Connect to your Github VCS provider

• Login to your Terraform Enterprise and connect it to your Github as explained in the following document: Connect to VCS Providers

Step 7: Create a VCS Workspace

• Login to your Terraform Enterprise
• Go to your organization
• Click on Create new workspace
• Select Version Control Workflow
• Select GitHub as the VCS provider
• Select the terraform-main as your repository
• Click Create
• Go to your workspace settings
• Inside the settings page, go to Version control
• Check the Include submodule on clone option and click Update VCS settings

Step 8: Do a manual run

• In your VCS workspace click on New run
• You should see that the plan is about to create a null resource
• Click on Confirm plan