Terraform Modules Repository

Terraform is an infrastructure-as-code tool to provision and manage any cloud, infrastructure, or service by the awesome folks over at Hashicorp.

For more information on Terraform, please see:

• Terraform: The official website for Terraform
• Terraform Documentation: The official docs for Terraform

Contextual Documentation

The examples in this document are generic. Cloudsmith provides contextual setup instructions within each repository, complete with copy n' paste snippets (with your namespace/repo pre-configured).

In the following examples:

Upload a Module

Upload via the Cloudsmith CLI or Website

To upload via the Cloudsmith API/CLI, you'll need to generate a module first. While we expect the tooling in this area to improve over time, currently the process is a manual one, and can be a little tricky.

You can build a package with standard command-line tooling like tar. To illustrate the process we'll use the terraform vault module for AWS as an example:

First, check out the version of the module we want to pack (0.13.6 for example purposes):

git clone [email protected]:hashicorp/terraform-aws-vault.git
cd terraform-aws-vault
git checkout 0.13.6

Next, create an archive using:

tar --exclude='.terraform' --exclude='*.tfstate*' --exclude='*_override.tf*' -czvf terraform-aws-vault-0.13.6.tar.gz .

📘

NOTE: Only lowercase alphanumeric characters, underscores and hyphens are supported for the module name. Please see the official Terraform documentation for more information on building your own modules.

Upload via Cloudsmith CLI

For full details of how to install and setup the Cloudsmith CLI, see Command Line Interface.

The command to upload a Terraform Module via the Cloudsmith CLI is:

cloudsmith push terraform OWNER/REPOSITORY terraform-MODULE_PROVIDER-MODULE_NAME-MODULE_VERSION.tar.gz

Example:

cloudsmith push terraform demo/examples-repo terraform-aws-vault-0.13.6.tar.gz

Upload via Cloudsmith Website

Please see Upload a Package for details of how to upload via the Website UI.

Download / Install a Module

Setup

Assuming you have Terraform already installed (if not, see the official docs), it is straightforward to add a Cloudsmith-based Terraform module.

First, the namespace, repository and credentials must be added to your .terraformrc or terraform.rc file. The token must contain the name of the organization which owns the module, the repository containing the module and the credentials required to authenticate with the API, delimited by a /:

credentials "terraform.cloudsmith.io" {
  token = "OWNER/REPOSITORY/TOKEN"
}

credentials "terraform.cloudsmith.io" {
  token = "OWNER/REPOSITORY/API-KEY"
}

🚧

Entitlement Tokens, User Credentials and API-Keys should be treated as secrets, and you should ensure that you do not commit them in configurations files along with source code or expose them in any logs.

Install a Module

Once configured as above, your module can then depend on a module from your registry by specifying the module's source in your Terraform file(s) using the syntax as outlined by Terraform:

module "my_module" {
  source = "terraform.cloudsmith.io/REPOSITORY/MODULE_NAME/local"
  version = "MODULE_VERSION"
}

Example:

module "my_module" {
  source = "terraform.cloudsmith.io/examples-repo/terraform-aws-vault-v0136targz/local"
  version = "v0.13.6"
}

Once added, terraform will download the module to your project's .terraform directory after running:

terraform init

You can install the latest version of this crate by removing the version variable from its declaration in your source code.

You can upgrade to the most recent version of this module matching your version constraints by running:

terraform init -upgrade=true

Upstream Proxying / Caching

Not Supported

Key Signing Support

Not Supported by Format

Troubleshooting

Please see the Troubleshooting page for further help and information.