Terraform Modules Repository

Cloudsmith provides public & private repositories for Terraform Modules

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 and paste snippets (with your namespace/repo/rsa-key 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.

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 git@github.com: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 web app

Please see Upload a Package for details of how to upload via the Cloudsmith web app.

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"
}

Warning

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 upgrade to the most recent version of this module matching your version constraints by running:

terraform init -upgrade=true

Upstream Proxying / Caching

Key Signing Support

Troubleshooting

Please see the Troubleshooting page for further help and information.