Running Terraform in an Air-Gapped Environment – Part 1

Introduction

Running Terraform in an air-gapped environment (one without internet access) poses several challenges, especially when it comes to installing Terraform providers like AWS, Azure, or GCP. Normally, Terraform downloads providers from the Terraform Registry, but in an offline setup, this isn’t possible.

This guide walks through how to configure Terraform for offline use, including manually downloading provider binaries, setting up a local Terraform plugin mirror, and ensuring smooth Terraform operations in restricted environments.

📚 This guide is at an intermediate level difficulty. 📚

Why Use Terraform in an Air-Gapped Environment?

Air-gapped environments are used in high-security deployments, including:

• Government & Defense sectors
• Financial institutions
• Regulated industries with strict compliance needs
• Internal development/test environments with limited internet access

In such cases, Terraform needs to operate without connecting to the internet, requiring pre-downloaded providers and modules.

Step 1: Identify System Architecture

Before downloading Terraform and providers, determine the CPU architecture of your system.

Run the following:

uname -m

Expected outputs:

• x86_64 → Intel/AMD 64-bit
• aarch64 → ARM64 (e.g., AWS Graviton)

Step 2: Download and Install Terraform

For x86_64 (Intel/AMD)

wget https://releases.hashicorp.com/terraform/1.6.6/terraform_1.6.6_linux_amd64.zip
unzip terraform_1.6.6_linux_amd64.zip
sudo mv terraform /usr/local/bin/

For ARM64 (Graviton)

wget https://releases.hashicorp.com/terraform/1.6.6/terraform_1.6.6_linux_arm64.zip
unzip terraform_1.6.6_linux_arm64.zip
sudo mv terraform /usr/local/bin/

Verify installation:

terraform -version

Step 3: Download Terraform Providers (Manually)

Terraform providers need to be pre-downloaded before being used in an air-gapped setup.

3.1 – Find the required provider versions in terraform.tf

3.2 – Manually download the AWS provider

For x86_64:

wget https://releases.hashicorp.com/terraform-provider-aws/5.58.0/terraform-provider-aws_5.58.0_linux_amd64.zip
unzip terraform-provider-aws_5.58.0_linux_amd64.zip -d ~/.terraform.d/plugins/registry.terraform.io/hashicorp/aws/5.58.0/linux_amd64/

For ARM64:

wget https://releases.hashicorp.com/terraform-provider-aws/5.58.0/terraform-provider-aws_5.58.0_linux_arm64.zip
unzip terraform-provider-aws_5.58.0_linux_arm64.zip -d ~/.terraform.d/plugins/registry.terraform.io/hashicorp/aws/5.58.0/linux_arm64/

3.3 – Ensure the correct file structure

Terraform expects providers to be stored in:

~/.terraform.d/plugins/registry.terraform.io/hashicorp/aws/5.58.0/linux_amd64/

Or for ARM64:

~/.terraform.d/plugins/registry.terraform.io/hashicorp/aws/5.58.0/linux_arm64/

Step 4: Configure Terraform to Use Local Providers

By default, Terraform tries to download providers from the Terraform Registry. To override this, create a local Terraform mirror.

mkdir -p /terraform-mirror/registry.terraform.io/hashicorp/aws/5.58.0/linux_amd64
mv ~/.terraform.d/plugins/registry.terraform.io/hashicorp/aws/5.58.0/linux_amd64/terraform-provider-aws /terraform-mirror/registry.terraform.io/hashicorp/aws/5.58.0/linux_amd64/

Step 5: Run Terraform in Offline Mode

After setting up the provider mirror, run:

terraform init -plugin-dir=/terraform-mirror

Now apply your Terraform configurations:

terraform apply

Step 6: Storing Multiple Providers for Future Use

If you need multiple providers (e.g., AWS, Azure, Kubernetes), download and store them in your local Terraform mirror.

Example directory structure:

/terraform-mirror/
  ├── registry.terraform.io/
      ├── hashicorp/
          ├── aws/5.58.0/linux_amd64/
          ├── azuread/2.43.0/linux_amd64/
          ├── azurerm/3.50.0/linux_amd64/
          ├── kubernetes/2.15.0/linux_amd64/

Bonus: Automate Provider Download (Script)

To automate downloading multiple providers, use this script (download here):

Run this on a machine with internet, then transfer /terraform-mirror to your air-gapped environment.

Conclusion

Setting up Terraform in an air-gapped environment requires pre-downloading Terraform and providers, creating a local provider mirror, and ensuring Terraform is configured to use local files instead of downloading from the registry. With this setup, you can manage infrastructure offline while maintaining security and compliance in restricted environments.

In the next post, we will discuss setting up VPC Endpoints to allow an air-gapped Terraform to interact with AWS services.

All code in this post can be found on my GitHub.

I’ll be posting more of these guides, going over a wide range of difficulty, so subscribe below! My newsletter sends out friendly emails when I make new posts.
Want to learn more about how I can assist you with your cloud and DevOps needs? Visit my homepage to get in touch and let’s find out how I can support your next project!