Root & Submodule Usage

This document provides an overview of the requirements and best practices for using root modules and nested submodules in your infrastructure-as-code setup. It explains the structure and configuration needed for single-module repositories and how to properly reference submodules within your code. Understanding these concepts will help ensure consistency and maintainability in your module usage.

Authentication for Local Usage

To authenticate with the Harness Module Registry when working locally, set the TF_TOKEN_<subdomain>_harness_io environment variable with your personal access token (PAT) before running the init command. This allows Terraform to access private modules securely. For example, TF_TOKEN_app_harness_io.

export TF_TOKEN_<subdomain>_harness_io=your_pat_token
tofu init

Single modules

Root Level Modules

If you are using only a single module, you must have a main.tf file at the root level of your repository. Below is an example of the typical structure for a single-module repository:

.
├── README.md
├── main.tf
├── variables.tf
├── outputs.tf

Here is an example of defining a single module in main.tf:

module "native-module" {
  source  = "app.harness.io/<account_id>/native-module/aws"
  version = "1.2.1"  # This matches your repository's Git tags.
}

Submodules

Submodule Usage

info

While there is no set limit on nested submodule paths, metadata collection is only carried out one level deep.

Submodules are only recognized if they are placed within the modules folder.

Here is an example of the repository tree with submodules:

.
├── README.md
├── main.tf
├── variables.tf
├── outputs.tf
├── ...
├── modules/
│   ├── submoduleA/
│   │   ├── main.tf
│   │   ├── ...
│   ├── submoduleB/
│   │   │── README.md
│   │   │── main.tf
│   │   │── variables.tf
│   │   │── outputs.tf

They can be referenced in your root module main.tf file as shown below. Notice the // syntax, which indicates the path to the submodule:

module "native-submodule" {
  source  = "app.harness.io/<account-id>/native-module//modules/native-submodule"
}

submodule versions

Note that submodules cannot have a version included, as Git tags do not apply to anything beyond the root level.