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, this enables teams to reuse shared Terraform code across multiple workspaces.

This guide provides the steps to configure a Terraform Enterprise workspace to correctly clone and use a repository containing Git submodules.

Prerequisites

• An active Terraform Enterprise instance.
• A VCS Provider, such as GitHub, connected to your Terraform Enterprise instance.

Note: This approach was validated using the GitHub VCS provider and Terraform Enterprise v1.1.1.

Procedure

Step 1: Create the Main GitHub Repository

This repository will contain the primary Terraform configuration and will reference the submodule.

1. Log in to GitHub.
2. Create a new repository (e.g., terraform-main).
3. Select the repository visibility (Private is recommended).
4. Click Create repository.

Step 2: Create the Secondary GitHub Repository

This repository will be included as a submodule and contains reusable Terraform code.

1. In GitHub, create another new repository (e.g., terraform-secondary).
2. Select the repository visibility.
3. Click Create repository.

Step 3: Initialize the Main Repository

Clone the main repository locally and add an initial file.

1. Create and navigate to a test directory on your local machine.

   $ mkdir ~/test-directory
   $ cd ~/test-directory

2. Clone the main repository.

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

3. Navigate into the repository directory.

   $ cd terraform-main

4. Create a README.md file.

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

5. Commit and push the changes.

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

Step 4: Initialize the Secondary Repository

Clone the secondary repository and add a sample Terraform configuration.

1. Navigate back to your test directory.

   $ cd ~/test-directory

2. Clone the secondary repository.

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

3. Navigate into the repository directory.

   $ cd terraform-secondary

4. Create a README.md file.

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

5. Create a main.tf file with the following content.

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

6. Commit and push the changes.

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

Step 5: Add the Submodule to the Main Repository

Reference the secondary repository as a submodule from within the main repository.

1. Navigate to the main repository directory.

   $ cd ~/test-directory/terraform-main

2. Add terraform-secondary as a submodule. You can use either an HTTPS or SSH URL.

   ## 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

3. Verify the content of the .gitmodules file. The output will vary based on the URL you used.

   $ cat .gitmodules

   Example output for HTTPS:

   [submodule "terraform-secondary"]
   path = terraform-secondary
   url = https://github.com/<org>/<terraform-secondary>.git

4. Commit and push the changes.

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

Step 6: Connect Terraform Enterprise to Your VCS Provider

If you have not already done so, connect your Terraform Enterprise instance to your GitHub account. For detailed instructions, refer to the official documentation on how to Connect to VCS Providers.

Step 7: Create and Configure a VCS-backed Workspace

Create a new workspace in Terraform Enterprise and configure it to use the main repository and its submodules.

1. Log in to your Terraform Enterprise instance and navigate to your organization.
2. Click Create new workspace.
3. Select the Version Control Workflow.
4. Choose GitHub as the VCS provider.
5. Select the terraform-main repository.
6. Click Create workspace.
7. Navigate to your workspace's Settings page, then select Version Control.
8. Check the Include submodules on clone option and click Update VCS settings.

Step 8: Trigger a Run

Finally, trigger a run to verify that Terraform Enterprise correctly clones the repository and its submodule.

1. In your workspace, click Actions and select Start new run.
2. Observe the plan output. It should show that Terraform plans to create the null_resource defined in the submodule.
3. Click Confirm & Apply to complete the run.