feat: module template refactor (#587)

.gitignore

@@ -40,9 +40,6 @@ terraform.rc
 # Ignore .tfsec
 .tfsec/
 
-# Ignore brew lock
-Brewfile.lock.json
-
 # Ignore Mac files
 .DS_Store
 

.secrets.baseline

@@ -3,7 +3,7 @@
     "files": "go.sum|^.secrets.baseline$",
     "lines": null
   },
-  "generated_at": "2023-06-03T04:41:19Z",
+  "generated_at": "2023-06-03T04:42:19Z",
   "plugins_used": [
     {
       "name": "AWSKeyDetector"

README.md

@@ -35,7 +35,7 @@ Follow this process to create and submit a Terraform module.
 1.  Create a repository from this repository template by clicking `Use this template` in the upper right of the GitHub UI.
 &emsp;&emsp;&emsp;&emsp;<br>For more information about creating a repository from a template, see the [GitHub docs](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template).
 1.  Select `terraform-ibm-modules` as the owner.
-1.  Enter a name for the module in format `terraform-ibm-<NAME>`, where `<NAME>` reflects the type of infrastructure that the module manages.
+1.  Enter a name for the module in format `terraform-ibm-<name>`, where `<name>` reflects the type of infrastructure that the module manages.
 &emsp;&emsp;&emsp;&emsp;<br>Use hyphens as delimiters for names with multiple words (for example, terraform-ibm-`activity-tracker`).
 1.  Provide a short description of the module.
 &emsp;&emsp;&emsp;&emsp;<br>The description is displayed under the repository name on the [organization page](https://github.com/terraform-ibm-modules) and in the **About** section of the repository. Use the description to help users understand the purpose of your module. For more information, see [module names and descriptions](https://terraform-ibm-modules.github.io/documentation/#/implementation-guidelines?id=module-names-and-descriptions) in the docs.
@@ -79,8 +79,6 @@ After you implement the logic for your module and create examples and tests, upd
 
 After the first PR for your module is merged, follow these post-merge steps:
 
-1.  Create a PR to enable the upgrade test by removing the `t.Skip` line in `tests/pr_test.go`.
-
 <!-- Remove the content in this previous H2 heading -->
 ## Reference architectures
 
@@ -136,16 +134,15 @@ statement instead the previous block.
 <!-- BEGIN EXAMPLES HOOK -->
 ## Examples
 
-- [ Default example](examples/default)
-- [ Example that uses existing resources](examples/existing-resources)
-- [ Non default example](examples/non-default)
+- [ Basic example](examples/basic)
+- [ Complete example](examples/complete)
 <!-- END EXAMPLES HOOK -->
 <!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
 ## Requirements
 
 | Name | Version |
 |------|---------|
-| <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.0.0 |
+| <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.3, < 1.6 |
 
 ## Modules
 

cra-config.yaml

@@ -1,7 +1,7 @@
 # More info about this file at https://github.com/terraform-ibm-modules/common-pipeline-assets/blob/main/.github/workflows/terraform-test-pipeline.md#cra-config-yaml
 version: "v1"
 CRA_TARGETS:
-  - CRA_TARGET: "examples/default" # Target directory for CRA scan. If not provided, the CRA Scan will not be run.
+  - CRA_TARGET: "examples/basic" # Target directory for CRA scan. If not provided, the CRA Scan will not be run.
     CRA_IGNORE_RULES_FILE: "cra-tf-validate-ignore-rules.json" # CRA Ignore file to use. If not provided, it checks the repo root directory for `cra-tf-validate-ignore-rules.json`
     # CRA_ENVIRONMENT_VARIABLES:  # An optional map of environment variables for CRA, where the key is the variable name and value is the value. Useful for providing TF_VARs.
     #   TF_VAR_sample: "sample value"

examples/basic/README.md

@@ -0,0 +1,8 @@
+# Basic example
+
+<!-- There is a pre-commit hook that will take the title of each example add include it in the repos main README.md  -->
+<!-- The text below should describe exactly what resources are provisioned / configured by the example  -->
+
+An end-to-end basic example that will provision the following:
+- A new resource group if one is not passed in.
+- A new Cloud Object Storage instance.

examples/default/main.tf → examples/basic/main.tf

@@ -1,14 +1,19 @@
 ##############################################################################
-# Resource Group
+# Resource group
 ##############################################################################
 
 module "resource_group" {
-  source = "git::https://github.com/terraform-ibm-modules/terraform-ibm-resource-group.git?ref=v1.0.5"
+  source  = "terraform-ibm-modules/resource-group/ibm"
+  version = "1.0.5"
   # if an existing resource group is not set (null) create a new one using prefix
   resource_group_name          = var.resource_group == null ? "${var.prefix}-resource-group" : null
   existing_resource_group_name = var.resource_group
 }
 
+##############################################################################
+# COS instance
+##############################################################################
+
 resource "ibm_resource_instance" "cos_instance" {
   name              = "${var.prefix}-cos"
   resource_group_id = module.resource_group.resource_group_id

examples/existing-resources/outputs.tf → examples/basic/provider.tf

@@ -1,8 +1,8 @@
 ##############################################################################
-# Outputs
+# Provider config
 ##############################################################################
 
-output "vpc_id" {
-  description = "ID of the existing VPC"
-  value       = data.ibm_is_vpc.example.id
+provider "ibm" {
+  ibmcloud_api_key = var.ibmcloud_api_key
+  region           = var.region
 }

examples/default/variables.tf → examples/basic/variables.tf

@@ -1,3 +1,7 @@
+##############################################################################
+# Input variables
+##############################################################################
+
 variable "ibmcloud_api_key" {
   type        = string
   description = "The IBM Cloud API Key"
@@ -13,12 +17,12 @@ variable "region" {
 variable "prefix" {
   type        = string
   description = "Prefix to append to all resources created by this example"
-  default     = "terraform"
+  default     = "basic"
 }
 
 variable "resource_group" {
   type        = string
-  description = "An existing resource group name to use for this example, if unset a new resource group will be created"
+  description = "The name of an existing resource group to provision resources in to. If not set a new resource group will be created using the prefix variable"
   default     = null
 }
 

examples/basic/version.tf

@@ -0,0 +1,13 @@
+terraform {
+  # Since hashicorp can include breaking changes in minor version updates, ensure to lock into a range here.
+  required_version = ">= 1.3, < 1.6"
+
+  # Ensure that there is always 1 example locked into the lowest provider version of the range defined in the main
+  # module's version.tf (usually a basic example), and 1 example that will always use the latest provider version.
+  required_providers {
+    ibm = {
+      source  = "IBM-Cloud/ibm"
+      version = "1.49.0"
+    }
+  }
+}

examples/complete/README.md

@@ -0,0 +1,4 @@
+# Complete example
+
+<!-- There is a pre-commit hook that will take the title of each example add include it in the repos main README.md  -->
+<!-- Add text below should describe exactly what resources are provisioned / configured by the example  -->

examples/complete/main.tf

@@ -0,0 +1,3 @@
+##############################################################################
+# Complete example
+##############################################################################

examples/non-default/outputs.tf → examples/complete/outputs.tf

@@ -3,21 +3,21 @@
 ##############################################################################
 
 output "region" {
-  description = "Region"
+  description = "The region all resources were provisioned in"
   value       = var.region
 }
 
 output "prefix" {
-  description = "Prefix"
+  description = "The prefix used to name all provisioned resources"
   value       = var.prefix
 }
 
 output "resource_group_name" {
-  description = "RG name"
+  description = "The name of the resource group used"
   value       = var.resource_group
 }
 
 output "resource_tags" {
-  description = "Tags"
+  description = "List of resource tags"
   value       = var.resource_tags
 }

examples/complete/provider.tf

@@ -0,0 +1,8 @@
+##############################################################################
+# Provider config
+##############################################################################
+
+provider "ibm" {
+  ibmcloud_api_key = var.ibmcloud_api_key
+  region           = var.region
+}

examples/non-default/variables.tf → examples/complete/variables.tf

@@ -13,7 +13,7 @@ variable "region" {
 variable "prefix" {
   type        = string
   description = "Prefix to append to all resources created by this example"
-  default     = "terraform"
+  default     = "complete"
 }
 
 variable "resource_group" {

examples/complete/version.tf

@@ -0,0 +1,13 @@
+terraform {
+  # Since hashicorp can include breaking changes in minor version updates, ensure to lock into a range here.
+  required_version = ">= 1.3, < 1.6"
+
+  # Ensure that there is always 1 example locked into the lowest provider version of the range defined in the main
+  # module's version.tf (usually a basic example), and 1 example that will always use the latest provider version.
+  required_providers {
+    ibm = {
+      source  = "IBM-Cloud/ibm"
+      version = ">= 1.49.0, < 2.0.0"
+    }
+  }
+}

module-metadata.json

@@ -3,7 +3,7 @@
   "variables": {},
   "outputs": {},
   "required_core": [
-    "\u003e= 1.0.0"
+    "\u003e= 1.3, \u003c 1.6"
   ],
   "required_providers": {},
   "managed_resources": {},

outputs.tf

@@ -6,5 +6,3 @@
 #  description = "Description of my output"
 #  value       = "value"
 #}
-
-##############################################################################

tests/other_test.go

@@ -7,12 +7,10 @@ import (
 	"github.com/stretchr/testify/assert"
 )
 
-const nonDefaultExampleTerraformDir = "examples/non-default"
-
-func TestRunNonDefaultExample(t *testing.T) {
+func TestRunBasicExample(t *testing.T) {
 	t.Parallel()
 
-	options := setupOptions(t, "non-default-tmp", nonDefaultExampleTerraformDir)
+	options := setupOptions(t, "mod-template-basic", "examples/basic")
 
 	output, err := options.RunTestConsistency()
 	assert.Nil(t, err, "This should not have errored")

tests/pr_test.go

@@ -1,4 +1,4 @@
-// Tests in this file are run in the PR pipeline
+// Tests in this file are run in the PR pipeline and the continuous testing pipeline
 package test
 
 import (
@@ -10,7 +10,7 @@ import (
 
 // Use existing resource group
 const resourceGroup = "geretain-test-resources"
-const defaultExampleTerraformDir = "examples/default"
+const completeExampleDir = "examples/complete"
 
 func setupOptions(t *testing.T, prefix string, dir string) *testhelper.TestOptions {
 	options := testhelper.TestOptionsDefaultWithVars(&testhelper.TestOptions{
@@ -22,10 +22,10 @@ func setupOptions(t *testing.T, prefix string, dir string) *testhelper.TestOptio
 	return options
 }
 
-func TestRunDefaultExample(t *testing.T) {
+func TestRunCompleteExample(t *testing.T) {
 	t.Parallel()
 
-	options := setupOptions(t, "mod-template", defaultExampleTerraformDir)
+	options := setupOptions(t, "mod-template", completeExampleDir)
 
 	output, err := options.RunTestConsistency()
 	assert.Nil(t, err, "This should not have errored")
@@ -35,10 +35,7 @@ func TestRunDefaultExample(t *testing.T) {
 func TestRunUpgradeExample(t *testing.T) {
 	t.Parallel()
 
-	// TODO: Remove this line after the first merge to primary branch is complete to enable upgrade test
-	t.Skip("Skipping upgrade test until initial code is in primary branch")
-
-	options := setupOptions(t, "mod-template-upg", defaultExampleTerraformDir)
+	options := setupOptions(t, "mod-template-upg", completeExampleDir)
 
 	output, err := options.RunTestUpgrade()
 	if !options.UpgradeTestSkipped {

variables.tf

@@ -2,10 +2,8 @@
 # Input Variables
 ##############################################################################
 
-#variable "myvariable" {
+#variable "my_variable" {
 #  type        = string
 #  description = "A description of my variable"
-#  default     = ""
+#  default     = "default_value"
 #}
-
-##############################################################################