How to use Terraform CLI with Local Mirror for Provider Plugins for system without internet access

Introduction

This guide explains how to configure the Terraform CLI to use a local filesystem mirror for provider plugins. This allows you to manage and use Terraform providers in environments without internet access.

Use Case

This procedure is for users who need to run Terraform in a disconnected or air-gapped environment where direct access to the public Terraform Registry is not available.

Prerequisites

• Terraform CLI v0.13.2 or later.
• A system with internet access to download the required provider plugins initially.

Procedure

Step 1: Download Provider Plugins to a Mirror Directory

On a system with internet access, create a directory to serve as your local mirror and download the necessary provider plugins into it.

This example uses the directory /users/macosuser/home/terraform_mirror.

Use the terraform providers mirror command to download the providers. Refer to the terraform providers mirror command documentation for more details.

$ terraform providers mirror -platform=darwin_amd64 -platform=linux_amd64 /users/macosuser/home/terraform_mirror

After downloading, transfer the entire mirror directory to the system that does not have internet access.

Step 2: Create the Terraform Configuration File

On the disconnected system, create a Terraform CLI configuration file to instruct Terraform to use your local mirror. This file should be named .terraformrc on Linux/macOS or terraform.rc on Windows.

Create the file with the following content, replacing the path with the location of your mirror directory.

provider_installation {
  filesystem_mirror {
    path    = "/users/macosuser/home/terraform_mirror"
    include = ["registry.terraform.io/*/*"]
  }
}

Step 3: Set Environment Variables

To ensure Terraform can find your plugins and the configuration file, export the following environment variables. These variables point to your mirror directory and the CLI configuration file you just created.

• TF_PLUGIN_CACHE_DIR: Specifies the location where plugins are cached.
• TF_CLI_CONFIG_FILE: Specifies the path to the CLI configuration file.

$ export TF_PLUGIN_CACHE_DIR="/users/macosuser/home/terraform_mirror"
$ export TF_CLI_CONFIG_FILE="/users/macosuser/home/terraform_mirror/.terraformrc"

Step 4: Initialize Terraform

Create a main.tf file with the required provider configuration. Ensure the provider version in your configuration matches a version you downloaded to your local mirror.

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "4.50.0" # Specify a version available in your local mirror
    }
  }
}

provider "aws" {
  region = "ap-south-1"
}

Run terraform init in the same directory as your main.tf file. Terraform will find the provider in the local mirror directory specified by your configuration file instead of attempting to download it from the internet.

$ terraform init

Initializing the backend...

Initializing provider plugins...
- Finding hashicorp/aws versions matching "4.50.0"...
- Using hashicorp/aws v4.50.0 from the shared cache directory

Terraform has been successfully initialized!

The output confirms that Terraform used the provider from the shared cache directory, successfully leveraging the local filesystem mirror.

Additional Information

• The required_providers block in your Terraform configuration is crucial for pinning the provider to a specific version that you have made available in the local mirror.
• This method allows you to manage Terraform provider plugins effectively in environments with restricted network access.