From 773d883b4bdce5f4cc6fe4353cbd3105e88cd1c2 Mon Sep 17 00:00:00 2001 From: richardblack-Harness Date: Thu, 27 Feb 2025 15:34:50 +0000 Subject: [PATCH 1/4] IAC-3227 Add module registry structure and submodule usage docs --- .../module-registry-code-structure.md | 53 +++++++++++++ .../module-registry/module-registry-tabs.md | 15 +--- .../module-registry/module-registry.md | 2 +- .../module-registry/root-sub-module-usage.md | 77 +++++++++++++++++++ 4 files changed, 132 insertions(+), 15 deletions(-) create mode 100644 docs/infra-as-code-management/iacm-features/module-registry/module-registry-code-structure.md create mode 100644 docs/infra-as-code-management/iacm-features/module-registry/root-sub-module-usage.md diff --git a/docs/infra-as-code-management/iacm-features/module-registry/module-registry-code-structure.md b/docs/infra-as-code-management/iacm-features/module-registry/module-registry-code-structure.md new file mode 100644 index 00000000000..eddd60caf7f --- /dev/null +++ b/docs/infra-as-code-management/iacm-features/module-registry/module-registry-code-structure.md @@ -0,0 +1,53 @@ +--- +title: Code Structure +description: Learn about the required code structure for module registry. +sidebar_position: 10 +sidebar_label: Module Code Structure +--- + +To ensure compatibility and ease of use within the Harness module registry, it is essential to follow a specific code structure when developing your modules. This structure helps maintain consistency and facilitates the integration of modules into your infrastructure as code workflows. + +## Directory Layout + +Each module should be organized into a directory that contains all the necessary files for the module to function. The recommended directory layout is as follows: + +``` +module-name/ +├── main.tf +├── variables.tf +├── outputs.tf +├── README.md +``` + +### Main Configuration File (`main.tf`) + +The `main.tf` file is the primary configuration file for the module. It should contain the core logic and resources that define the module's functionality. This file is the entry point for the module and should be well-organized and documented. + +### Variables Definition File (`variables.tf`) + +The `variables.tf` file defines the input variables for the module. These variables allow users to customize the module's behavior by providing different values. Each variable should have a clear description and, if applicable, a default value. + +### Outputs Definition File (`outputs.tf`) + +The `outputs.tf` file specifies the outputs of the module. Outputs are values that are exposed to the user after the module is applied. These values can be used to reference resources created by the module in other parts of your infrastructure. + +### Module Documentation (`README.md`) + +The `README.md` file provides documentation for the module. It should include an overview of the module, usage instructions, input variables, outputs, and examples. Clear and comprehensive documentation helps users understand how to use the module effectively. + +### Examples Directory (`examples/`) + +The `examples/` directory contains example configurations that demonstrate how to use the module. These examples should cover common use cases and provide a starting point for users. Each example should be a complete, working configuration that can be deployed independently. + +### Nested Modules Directory (`modules/`) + +The `modules/` directory is used to organize nested or submodules. Submodules are smaller modules that are used internally by the main module. This directory helps keep the main module directory clean and organized. + +## Best Practices + +- **Consistency:** Follow a consistent naming convention and structure across all your modules. +- **Documentation:** Provide clear and comprehensive documentation for each module, including usage instructions and examples. +- **Modularity:** Break down complex configurations into smaller, reusable modules. +- **Version Control:** Use version control to manage changes to your modules and track their history. + +By adhering to this structure and best practices, you can create well-organized and maintainable modules that integrate seamlessly with the Harness module registry. diff --git a/docs/infra-as-code-management/iacm-features/module-registry/module-registry-tabs.md b/docs/infra-as-code-management/iacm-features/module-registry/module-registry-tabs.md index 1029f9eb8fa..018647dcd4d 100644 --- a/docs/infra-as-code-management/iacm-features/module-registry/module-registry-tabs.md +++ b/docs/infra-as-code-management/iacm-features/module-registry/module-registry-tabs.md @@ -1,26 +1,13 @@ --- title: Registered module settings description: Explore each tab of a registered module to understand its data, settings, and usage in detail. -sidebar_position: 20 +sidebar_position: 40 sidebar_label: Registered module settings --- - - import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -:::warning pending release -IaCM Module Registry is currently pending release and will be available soon! [Learn more](https://www.harness.io/blog/harness-iacm-module-registry). -::: - ## Prerequisites - A registered *tf* modules, to register a new module, go to [Register a module](https://developer.harness.io/docs/infra-as-code-management/iacm-features/module-registry#register-a-module) diff --git a/docs/infra-as-code-management/iacm-features/module-registry/module-registry.md b/docs/infra-as-code-management/iacm-features/module-registry/module-registry.md index 31131b08483..a51253106d2 100644 --- a/docs/infra-as-code-management/iacm-features/module-registry/module-registry.md +++ b/docs/infra-as-code-management/iacm-features/module-registry/module-registry.md @@ -1,7 +1,7 @@ --- title: Module Registry description: Learn how to register a module in Harness IaCM -sidebar_position: 10 +sidebar_position: 20 sidebar_label: Register modules --- diff --git a/docs/infra-as-code-management/iacm-features/module-registry/root-sub-module-usage.md b/docs/infra-as-code-management/iacm-features/module-registry/root-sub-module-usage.md new file mode 100644 index 00000000000..64a7395fdf0 --- /dev/null +++ b/docs/infra-as-code-management/iacm-features/module-registry/root-sub-module-usage.md @@ -0,0 +1,77 @@ +--- +title: Root & Submodule Usage +description: Learn about the requirements and correct usage of root modules and nested submodules. +sidebar_position: 30 +sidebar_label: Root & Submodule Usage +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + +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. + + + + +## 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`: + +```hcl +module "native-module" { + source = "app.harness.io//native-module/aws" + version = "1.2.1" # This matches your repository's Git tags. +} +``` + + + +## 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 +│ │ ├── ... +│ ├── native-module/ +│ │ │── 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: + +```hcl +module "native-submodule" { + source = "app.harness.io//native-module//modules/native-submodule" +} +``` +:::info +Note that submodules cannot have a version attached, as Git tags do not apply to anything beyond the root level. +::: + + From 4050585e4f7414e8f9eae1c0c4ce0e258d7c9726 Mon Sep 17 00:00:00 2001 From: richardblack-Harness Date: Fri, 28 Feb 2025 16:28:44 +0000 Subject: [PATCH 2/4] IAC-3227 Add module registry structure and submodule guidance --- .../module-registry-code-structure.md | 137 ++++++++++++++---- .../module-registry/module-registry-tabs.md | 13 +- .../module-registry/module-registry.md | 26 +--- .../module-registry/root-sub-module-usage.md | 4 +- 4 files changed, 115 insertions(+), 65 deletions(-) diff --git a/docs/infra-as-code-management/iacm-features/module-registry/module-registry-code-structure.md b/docs/infra-as-code-management/iacm-features/module-registry/module-registry-code-structure.md index eddd60caf7f..873f816a334 100644 --- a/docs/infra-as-code-management/iacm-features/module-registry/module-registry-code-structure.md +++ b/docs/infra-as-code-management/iacm-features/module-registry/module-registry-code-structure.md @@ -5,49 +5,132 @@ sidebar_position: 10 sidebar_label: Module Code Structure --- -To ensure compatibility and ease of use within the Harness module registry, it is essential to follow a specific code structure when developing your modules. This structure helps maintain consistency and facilitates the integration of modules into your infrastructure as code workflows. +OpenTofu or Terraform modules are reusable units of infrastructure configuration that help standardize deployment patterns and improve maintainability. A well-structured module simplifies usage and promotes best practices. This guide outlines the essential components of a Terraform module and how to structure it effectively. -## Directory Layout - -Each module should be organized into a directory that contains all the necessary files for the module to function. The recommended directory layout is as follows: +## Module Layout +A typical OpenTofu or Terraform module consists of a set of configuration files that define resources, variables, outputs, and dependencies. Below is a recommended directory structure: ``` module-name/ -├── main.tf -├── variables.tf -├── outputs.tf -├── README.md +├── main.tf # Primary resource configurations +├── variables.tf # Input variable definitions +├── outputs.tf # Output values +├── README.md # Documentation for the module +├── provider.tf # Provider configuration (if needed) +├── versions.tf # Required Terraform and provider versions +├── modules/ # Nested submodules (if applicable) +├── examples/ # Usage examples for reference +└── tests/ # Automated tests for the module ``` -### Main Configuration File (`main.tf`) - -The `main.tf` file is the primary configuration file for the module. It should contain the core logic and resources that define the module's functionality. This file is the entry point for the module and should be well-organized and documented. +## Key Components +### Root Module (Required) +All OpenTofu or Terraform configurations consist of at least one module, known as the root module, which is the only required element. The most common name for this file is `main.tf`. This file serves as the entry point for OpenTofu or Terraform execution and contains all the necessary configurations to provision the desired infrastructure. -### Variables Definition File (`variables.tf`) +--- +### `variables.tf` (Input Variables) +- Declares configurable inputs for the module. +- Variables should include descriptions and, when applicable, default values. + +Example: +```hcl +variable "instance_type" { + description = "EC2 instance type" + type = string + default = "t2.micro" +} +``` +Also see [variable usage](/docs/infra-as-code-management/project-setup/input-variables) for more information. -The `variables.tf` file defines the input variables for the module. These variables allow users to customize the module's behavior by providing different values. Each variable should have a clear description and, if applicable, a default value. +--- +### `outputs.tf` (Output Values) +- Defines values that the module will return upon execution. +- Helps users access relevant module data. + +Example: +```hcl +output "instance_id" { + description = "ID of the created EC2 instance" + value = aws_instance.example.id +} +``` -### Outputs Definition File (`outputs.tf`) +--- +### `README.md` (Module Documentation) +- Provides an overview of the module’s purpose and usage. +- Includes example configurations and descriptions of variables and outputs. -The `outputs.tf` file specifies the outputs of the module. Outputs are values that are exposed to the user after the module is applied. These values can be used to reference resources created by the module in other parts of your infrastructure. +--- +### `provider.tf` (Provider Configuration) +If a module requires provider settings, define them here. Avoid hardcoding provider settings within a module to allow flexibility. + +Example: +```hcl +tofu { + required_providers { + aws = { + source = "hashicorp/aws" + version = "~> 4.0" + } + } +} +``` -### Module Documentation (`README.md`) +--- +### `versions.tf` (Version Constraints) +- Specifies compatible OpenTofu or Terraform and provider versions. +- Ensures module stability by preventing incompatible updates. + +Example: +```hcl +tofu { + required_version = ">= 1.0.0" +} +``` -The `README.md` file provides documentation for the module. It should include an overview of the module, usage instructions, input variables, outputs, and examples. Clear and comprehensive documentation helps users understand how to use the module effectively. +--- +### `modules/` (Nested Modules / Submodules) +If a module is composed of multiple submodules, organize them within this directory to improve modularity and reusability. -### Examples Directory (`examples/`) +:::info module folder +Submodules are only recognized if they are placed within the `modules` folder. +::: -The `examples/` directory contains example configurations that demonstrate how to use the module. These examples should cover common use cases and provide a starting point for users. Each example should be a complete, working configuration that can be deployed independently. +--- +### `examples/` (Usage Examples) +Provide working examples demonstrating how to use the module in different scenarios. This helps users understand its implementation. -### Nested Modules Directory (`modules/`) +--- +### `tests/` (Automated Testing) +Testing ensures the module functions as expected. Use tools like `tofu test` or external frameworks such as `Terratest`. + +Example test using `tofu test`: +```hcl +tofu { + test { + assert { + condition = resource.aws_instance.example.instance_type == "t2.micro" + error_message = "Unexpected instance type" + } + } +} +``` -The `modules/` directory is used to organize nested or submodules. Submodules are smaller modules that are used internally by the main module. This directory helps keep the main module directory clean and organized. +--- +## Best practices +To ensure your modules are well-structured and maintainable, follow these best practices: -## Best Practices +**Root Module:** Always include a `main.tf` file at the root level of your repository. This file serves as the entry point for [OpenTofu](https://opentofu.org/docs/language/modules/) or Terraform execution. +**Modules Folder:** Place all submodules within a `modules/` folder. Submodules are only recognized if they are placed within this folder. +**Consistent Naming:** Use consistent naming conventions for files and directories to improve readability and maintainability. +**Documentation:** Provide comprehensive documentation in the README.md file, including an overview, usage instructions, and examples. +**Version Constraints:** Specify compatible OpenTofu or Terraform and provider versions in the `versions.tf` file to ensure module stability. +**Testing:** Include automated tests in the tests/ directory to verify the functionality of your module. -- **Consistency:** Follow a consistent naming convention and structure across all your modules. -- **Documentation:** Provide clear and comprehensive documentation for each module, including usage instructions and examples. -- **Modularity:** Break down complex configurations into smaller, reusable modules. -- **Version Control:** Use version control to manage changes to your modules and track their history. +--- +## Conclusion +A well-structured IaC module enhances reusability, maintainability, and collaboration. By following these guidelines, you can create reliable and scalable modules for your infrastructure needs. -By adhering to this structure and best practices, you can create well-organized and maintainable modules that integrate seamlessly with the Harness module registry. +For more details, refer to the following documentation: +- [Register a Module](/docs/infra-as-code-management/iacm-features/module-registry/module-registry) +- [Root and Submodule Usage](/docs/infra-as-code-management/iacm-features/module-registry/root-sub-module-usage) \ No newline at end of file diff --git a/docs/infra-as-code-management/iacm-features/module-registry/module-registry-tabs.md b/docs/infra-as-code-management/iacm-features/module-registry/module-registry-tabs.md index 018647dcd4d..509cbf87e14 100644 --- a/docs/infra-as-code-management/iacm-features/module-registry/module-registry-tabs.md +++ b/docs/infra-as-code-management/iacm-features/module-registry/module-registry-tabs.md @@ -113,18 +113,7 @@ Submodules can provide users with the flexibility to override or customize certa ## Top level overview - + diff --git a/docs/infra-as-code-management/iacm-features/module-registry/module-registry.md b/docs/infra-as-code-management/iacm-features/module-registry/module-registry.md index a51253106d2..72e5f320298 100644 --- a/docs/infra-as-code-management/iacm-features/module-registry/module-registry.md +++ b/docs/infra-as-code-management/iacm-features/module-registry/module-registry.md @@ -21,18 +21,7 @@ Follow the steps in the guide below to register a new module. - + 1. Login to [Harness](https://app.harness.io). @@ -56,19 +45,8 @@ Follow the steps in the guide below to register a new module. ## Review module settings Harness pulls various details from your module and makes it easy to review them. - + :::info syncing module versions The Sync button checks your registered module in Harness against the latest release in your repository and configured connector branch. If a newer version exists, it will sync it. diff --git a/docs/infra-as-code-management/iacm-features/module-registry/root-sub-module-usage.md b/docs/infra-as-code-management/iacm-features/module-registry/root-sub-module-usage.md index 64a7395fdf0..f1de91ed128 100644 --- a/docs/infra-as-code-management/iacm-features/module-registry/root-sub-module-usage.md +++ b/docs/infra-as-code-management/iacm-features/module-registry/root-sub-module-usage.md @@ -70,8 +70,8 @@ module "native-submodule" { source = "app.harness.io//native-module//modules/native-submodule" } ``` -:::info -Note that submodules cannot have a version attached, as Git tags do not apply to anything beyond the root level. +:::info submodule versions +Note that **submodules cannot have a version included**, as Git tags do not apply to anything beyond the root level. ::: From 67e671cd91eeb13551e7c8dbfe3910e2e2f41645 Mon Sep 17 00:00:00 2001 From: richardblack-Harness Date: Fri, 28 Feb 2025 16:37:55 +0000 Subject: [PATCH 3/4] IAC-3227 Update casing --- .../module-registry/module-registry-code-structure.md | 4 ++-- .../iacm-features/module-registry/module-registry-tabs.md | 2 +- .../iacm-features/module-registry/module-registry.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/infra-as-code-management/iacm-features/module-registry/module-registry-code-structure.md b/docs/infra-as-code-management/iacm-features/module-registry/module-registry-code-structure.md index 873f816a334..30f3c4c3a29 100644 --- a/docs/infra-as-code-management/iacm-features/module-registry/module-registry-code-structure.md +++ b/docs/infra-as-code-management/iacm-features/module-registry/module-registry-code-structure.md @@ -1,5 +1,5 @@ --- -title: Code Structure +title: Module Code Structure description: Learn about the required code structure for module registry. sidebar_position: 10 sidebar_label: Module Code Structure @@ -25,7 +25,7 @@ module-name/ ## Key Components ### Root Module (Required) -All OpenTofu or Terraform configurations consist of at least one module, known as the root module, which is the only required element. The most common name for this file is `main.tf`. This file serves as the entry point for OpenTofu or Terraform execution and contains all the necessary configurations to provision the desired infrastructure. +All OpenTofu or Terraform configurations consist of at least one module, known as the root module, which is **the only required element**. The most common name for this file is `main.tf`. This file serves as the entry point for [OpenTofu](https://opentofu.org/) or Terraform execution and contains all the necessary configurations to provision the desired infrastructure. --- ### `variables.tf` (Input Variables) diff --git a/docs/infra-as-code-management/iacm-features/module-registry/module-registry-tabs.md b/docs/infra-as-code-management/iacm-features/module-registry/module-registry-tabs.md index 509cbf87e14..aa9d2f5e7de 100644 --- a/docs/infra-as-code-management/iacm-features/module-registry/module-registry-tabs.md +++ b/docs/infra-as-code-management/iacm-features/module-registry/module-registry-tabs.md @@ -2,7 +2,7 @@ title: Registered module settings description: Explore each tab of a registered module to understand its data, settings, and usage in detail. sidebar_position: 40 -sidebar_label: Registered module settings +sidebar_label: Registered Module Settings --- import Tabs from '@theme/Tabs'; diff --git a/docs/infra-as-code-management/iacm-features/module-registry/module-registry.md b/docs/infra-as-code-management/iacm-features/module-registry/module-registry.md index 72e5f320298..a6a947abf1b 100644 --- a/docs/infra-as-code-management/iacm-features/module-registry/module-registry.md +++ b/docs/infra-as-code-management/iacm-features/module-registry/module-registry.md @@ -2,7 +2,7 @@ title: Module Registry description: Learn how to register a module in Harness IaCM sidebar_position: 20 -sidebar_label: Register modules +sidebar_label: Register Modules --- import Tabs from '@theme/Tabs'; From 6983399081b3aa7c2990da118f2143af8ac536e4 Mon Sep 17 00:00:00 2001 From: richardblack-Harness Date: Fri, 28 Feb 2025 16:52:50 +0000 Subject: [PATCH 4/4] IAC-3227 Move important usage requirement to the top --- .../module-registry-code-structure.md | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/docs/infra-as-code-management/iacm-features/module-registry/module-registry-code-structure.md b/docs/infra-as-code-management/iacm-features/module-registry/module-registry-code-structure.md index 30f3c4c3a29..a6150763a5d 100644 --- a/docs/infra-as-code-management/iacm-features/module-registry/module-registry-code-structure.md +++ b/docs/infra-as-code-management/iacm-features/module-registry/module-registry-code-structure.md @@ -7,6 +7,16 @@ sidebar_label: Module Code Structure OpenTofu or Terraform modules are reusable units of infrastructure configuration that help standardize deployment patterns and improve maintainability. A well-structured module simplifies usage and promotes best practices. This guide outlines the essential components of a Terraform module and how to structure it effectively. +## Requirements +### Root Module +All OpenTofu or Terraform configurations consist of at least one module, known as the root module, which is **the only required element**. The most common name for this file is `main.tf`. This file serves as the entry point for [OpenTofu](https://opentofu.org/) or Terraform execution and contains all the necessary configurations to provision the desired infrastructure. + +:::info modules folder +When using submodules, note that they are only recognized if they are placed within the `modules` folder at the root directory. +Go to [submodule usage](/docs/infra-as-code-management/iacm-features/module-registry/root-sub-module-usage) for more information. +::: + +--- ## Module Layout A typical OpenTofu or Terraform module consists of a set of configuration files that define resources, variables, outputs, and dependencies. Below is a recommended directory structure: @@ -23,11 +33,7 @@ module-name/ └── tests/ # Automated tests for the module ``` -## Key Components -### Root Module (Required) -All OpenTofu or Terraform configurations consist of at least one module, known as the root module, which is **the only required element**. The most common name for this file is `main.tf`. This file serves as the entry point for [OpenTofu](https://opentofu.org/) or Terraform execution and contains all the necessary configurations to provision the desired infrastructure. - ---- +## Other key components ### `variables.tf` (Input Variables) - Declares configurable inputs for the module. - Variables should include descriptions and, when applicable, default values.