Using Terraform Providers in Isolation

*upd 12/26/2024: Dev Community formatting has gone nuts, I will eventually rewrite all or some of my blog posts on my personal website. Stay tuned to get the link.

Is This Guide for Me?

If you need to use Terraform providers in an isolated environment, or in case you don't have access to the Terraform Registry, look no further.

The Telmate/proxmox provider is used as an example in this guide. Configurations are performed on a Linux distribution, but can be applied anywhere with slight modifications.

Quick tip: To install Terraform CLI on Linux or Mac without hassle, check out Homebrew.

Table of Contents

1. Find the Source Code
2. Get the Binaries
3. Place the Binaries Somewhere Locally
4. Configure the Terraform CLI
5. Test It Out!

Find the Source Code

Option 1. Go to GitHub and Search for Providers There

By convention, all providers' names start with the terraform-provider- prefix. Try typing this prefix in the search bar in combination with the name of the target provider — no hyphens needed. For example, terraform provider proxmox.

There's a high chance the first link will be a good choice. Also, I'd look for a greater number of stars. Most of the time, popular projects have lots of them.

Option 2. Search the Registry Beforehand or Ask Someone to Do This for You

Yeah, I know. That's kind of obvious.

Just type the name of the target provider in the search bar and pick one. Each provider's main page has a link to the source code.

Get the Binaries

Many providers' devs are kind enough to provide archives with binaries compiled for various platforms. They are located on the Releases page.

But Not Always

That is the case with HashiCorp, of course.

If there're no binaries, then you have to compile the provider yourself. Search for docs in the repo.

Place the Binaries Somewhere Locally

Terraform expects a directory structure of one of the two layouts:

• Packed (.zip archive)
• Unpacked (binaries)

About the Layouts

From the official documentation:

• Packed layout: HOSTNAME/NAMESPACE/TYPE/terraform-provider-TYPE_VERSION_TARGET.zip is the distribution zip file obtained from the provider's origin registry.
• Unpacked layout: HOSTNAME/NAMESPACE/TYPE/VERSION/TARGET is a directory containing the result of extracting the provider's distribution zip file.

Packed Layout Visualized

YOUR.REGISTRY.HOSTNAME/
└── ORGANIZATION-NAME
    └── PROVIDER
        └── terraform-provider-PROVIDER_X.X.X_PLATFORM.zip

We'll cover the first one.

There're no strict rules on where you should place a local mirror on the filesystem. Just make sure the files are accessible by other users if you're not the only one using the system.

I'm a Linux user, so according to FHS, /usr/libexec is a suitable option. There will be a directory for Terraform. Providers will have a separate directory under it — terraform/providers.

/usr/libexec summary

From the Linux Foundation Referenced Specifications website:

/usr/libexec includes internal binaries that are not intended to be executed directly by users or shell scripts. Applications may use a single subdirectory under /usr/libexec.

1. Create a proper directory layout
   

   # mkdir -p /usr/libexec/terraform/providers/registry.terraform.io/Telmate/proxmox
   

   Note: The path before registry.terraform.io is up to you, but after it the layout must be either of two types mentioned earlier.

2. Copy the archive(s) so the result looks similar to this:
   

   deathroll@hellish:~$ tree /usr/libexec/terraform/
   /usr/libexec/terraform/
   └── providers
       └── registry.terraform.io
           └── Telmate
               └── proxmox
                   ├── terraform-provider-proxmox_2.9.11_linux_amd64.zip
                   └── terraform-provider-proxmox_2.9.14_linux_amd64.zip
   
   5 directories, 2 files
   deathroll@hellish:~$
   

Configure the Terraform CLI

According to the documentation, the config file for the cli utility on Linux is placed in the home directory and is called .terraformrc.

1. Create the config file.

2. Populate it with the following content:

   Make sure to replace the path with your own.
   

   provider_installation {
     filesystem_mirror {
       path    = "/usr/libexec/terraform/providers"
       include = ["*/*"] # */* is a shorthand for registry.terraform.io/*/*
     }
   
     direct {
       exclude = ["*/*"]
     }
   }
   

   Note: The path doesn't include the registry host name.

Test It Out!

Now you can go to your Terraform project directory and start working on it. Everything should work as expected.