Terraform Registry

Terraform Module Registry

Terraform Modules are Terraform configurations that can be called and configured by other configurations. They serve as containers for multiple resources that are used together. They contain a collection of .tf files kept together in a directory. To create a module, pack all your .tf files into a Zip archive and deploy to the Terraform local repository. For more information, see Creating Terraform Modules.

Terraform Module Repository Structure

The Terraform Module repository is a directory with a collection of Zip files, consisting of these main coordinates:

• namespace
• module
• Provider
• version.zip

Artifactory complies with the Terraform Module directory layout convention.

namespace/module-name/provider/version.zip

For example:

terraform-aws-modules/vpc/aws/2.0.0.zip
harshicorp/consul/aws/DEV-123.zip

Terraform Provider Registry

Providers are a set of plugins that interact with cloud providers, SaaS providers and other APIs. 

Terraform Provider Repository Structure

The Terraform Provider repository is a directory with a collection of Zip files consisting of these main coordinates:

• Namespace
• Provider
• Version.zip
• Operating system
• Architecture

Artifactory complies with the Terraform Provider directory layout convention.

namespace/provider/version/terraform-provider-{NAME}_{VERSION}_{OS}_{ARCH}.zip

/google/3.88.0/terraform-provider-google_3.88.0_darwin_amd64.zip

Setting up a Terraform Module/Provider Registry

You can set up the following repository types:

• Local Repository
• Remote Repository
• Virtual Repository

Setting up a Local Module/Provider Registry

Local repositories enable you to deploy the Terraform Module or Provider as a zip archive. Artifactory calculates the metadata for all packages and indexes them to allow users to download these packages through the Terraform CLI. 

1. To create a Terraform Module/Provider local repository, navigate to the Administration module.
2. Navigate to Repositories | Repositories | Local | New Local Repository and select Terraform as the Package Type.
3. In the Basic tab, from the Terraform Registry Type list:
   • Select Module to apply the terraform-module-default repository layout.
   • Select Provider to apply the terraform-provider-default repository layout.

Setting up a Remote Terraform Registry

Remote Repositories enable you to proxy and cache your remote Terraform Modules and Providers packages. 

To specify that a Remote Repository supports Terraform packages, you will need to set its Package Type to Terraform when it is created. 

Note that the Remote repository settings are identical for both Providers and Modules.

Follow these guidelines regarding the specific Terraform settings.

Setting up a Virtual Terraform Registry

A Virtual Repository defined in Artifactory aggregates packages from both local and remote repositories.

This allows you to access both locally hosted Modules and Providers and remote proxied Terraform repositories from a single URL defined for the Virtual Repository.

To define a virtual Terraform repository, do the following:

1. Create a Virtual Repositories, and set the Package Type to be Terraform.
2. Select the underlying local and remote Terraform Module or Provider repositories to include in the Basic settings tab. 

Resolving Terraform Module/Providers

Generating an Access Token

To use Artifactory with your Terraform CLI, you will need to generate an access token using the following two methods:

• Generating an Access Token Using Browser Login
• Manually Generating an Identity Token 

Generating an Access Token Using Browser Login

1. Natively run the Terraform login to your Artifactory domain to generate an access token and save it in the Credentials file (~/.terraform.d/credentials.tfrc.json).
   When you run the login, the following page opens.
   
   The Terraform command line login process is displayed.
   
2. You are routed to the JFrog Platform login page and the following page opens.
   
3. Click Approve.
   The following message is displayed.
   
   
4. Close the page and return to the command line to view the success message.
   
   
5. Next, perform a one time edit to the ~/.terraformrc file to ensure that the CLI searches for the providers only in the Artifactory. For this purpose, we recommend only pointing to the Terraform Virtual repository. 

Manually Generating an Identity Token

1. Generate an identity token that you can use to connect Artifactory to the Terraform CLI. For more details, please refer to User Profile- Identity Token.
2. Create a file named 'credentials.tfrc.json' in your Terraform directory, ('~/.terraform.d/credentials.tfrc.json').

3. Update the identity token you generated in the credentials.tfrc.json file, as in the example below: 

   #cat ~/.terraform.d/credentials.tfrc.json
   
   {
   	"credentials": {
   		"ARTIFACTORY-DOMAIN": {
   			"token": "IDENTITY-TOKEN" 
   			}
   		}
   	}

   If you have added the access token in credentials.tfrc.json, you do not need to login again using Terraform login servername.jfrog.io.

Searching for Terraform Packages

You can search for Terraform Module or Providers by their type, using the Artifact Package Search.

Calculate a Terraform Repository Metadata

You can trigger an asynchronous re-indexing of a local Terraform repository either through the UI or using the REST API.
This will also reindex the git index and, as a result, will also index the remote repositories.
In the Artifact Tree Browser, select your Terraform repository, right-click and select Recalculate Index from the list. Requires Admin privileges.
To reindex a Terraform repository through the REST API refer to the following REST API.

Calculate Terraform Index

Description: Calculates Terraform Modules or Providers index for the specified repository.
Notes: Requires Artifactory Pro.
Security: Requires a valid admin user.
Usage: POST /api/terraform/{repoKey}/reindex
Produces: application/text
Since: 7.38.4
Sample Output:

POST /api/terraform/terraform-local/reindex

Reindexing of Terraform repository terraform-local was scheduled to run.

Publishing Terraform Modules Using the JFrog CLI

JFrog CLI provides full support for packing Terraform modules and deploying them to JFrog Artifactory.

Step 1: Set Up Terraform Repositories

Before you can use JFrog CLI to publish your Terraform modules to Artifactory, you first need to set the deployment repository for the project.

Here's how you set the repository.

1. CD to the root of the Terraform project.
2. Run the jf terraform-config command.

Example 1

Set repositories for this Terraform project.

jf tfc

Example 2

Set repositories for all Terraform projects on this machine.

jf tfc --global

Step 2: Publish Terraform Modules to Artifactory

The terraform publish command packs and deploys the Terraform modules to the designated Terraform repository in Artifactory.

Before running the terraform publish command on a project for the first time, the project should be configured using the terraform-config command.

The modules are deployed to the configured Terraform repository according to the following layout.
Note that the moduleName is determined by the name of the module directory

namespace/moduleName/provider/tag.zip

To publish a specific module, access the Modules’ root directory.

Before running terraform publish, cd into the directory which contains the Terraform modules. Note that those modules will later share common layout arguments (namespace, provider, and tag) in Artifactory.

Packing modules
Rules and Guidelines for Packing modules

• The File system is scanned from the current working directory.

• A directory that contains at least one file with a .tf extension is considered as a Terraform module and all its content will be packed in one zip file (including the submodules directories) and will be deployed to Artifactory.

• Recursive scanning does not run inside the module directory after it is packed, as a result, the submodules will not be packed and deployed separately to Artifactory.

Adding Exclusions Using Patterns

There is an option to set patterns to exclude modules that may contain:

• A directory that matches the pattern will not be scanned.
• Files that match the pattern won’t be packed in the relevant zip file.

The following table lists the command arguments and flags:

An Example 

Prerequisite

Before running this command on a project for the first time, the project should be configured using the terraform-config command.

To pack and publish the Terraform module, run the following command.

This command packs and deploys all the modules under the current working directory.
The modules will be published to the configured repository, using this layout: tera/moduleName/aws/v0.1.2.zip.
Modules and files which include test and ignore will be excluded (read more in the “exclusions” section).

jf tf p -namespace=tera -provider=aws -tag=v0.1.2 -exclusions=”*test*;*ignore*"

For more information try this terraform project example.