feat: several updates to module template (#848)

.github/CODEOWNERS

@@ -1,2 +1,2 @@
 # Primary owner should be listed first in list of global owners, followed by any secondary owners
-*       @SirSpidey @ocofaigh
+*       @ocofaigh @daniel-butler-irl

.secrets.baseline

@@ -3,7 +3,7 @@
     "files": "go.sum|^.secrets.baseline$",
     "lines": null
   },
-  "generated_at": "2023-12-09T06:39:44Z",
+  "generated_at": "2024-11-22T17:36:38Z",
   "plugins_used": [
     {
       "name": "AWSKeyDetector"
@@ -76,7 +76,18 @@
       "name": "TwilioKeyDetector"
     }
   ],
-  "results": {},
+  "results": {
+    "README.md": [
+      {
+        "hashed_secret": "ff9ee043d85595eb255c05dfe32ece02a53efbb2",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 74,
+        "type": "Secret Keyword",
+        "verified_result": null
+      }
+    ]
+  },
   "version": "0.13.1+ibm.62.dss",
   "word_list": {
     "file": null,

README.md

@@ -56,7 +56,32 @@ unless real values don't help users know what to change.
 -->
 
 ```hcl
-
+terraform {
+  required_version = ">= 1.9.0"
+  required_providers {
+    ibm = {
+      source  = "IBM-Cloud/ibm"
+      version = "X.Y.Z"  # Lock into a provider version that satisfies the module constraints
+    }
+  }
+}
+
+locals {
+    region = "us-south"
+}
+
+provider "ibm" {
+  ibmcloud_api_key = "XXXXXXXXXX"  # replace with apikey value
+  region           = local.region
+}
+
+module "module_template" {
+  source            = "terraform-ibm-modules/<replace>/ibm"
+  version           = "X.Y.Z" # Replace "X.Y.Z" with a release version to lock into a specific release
+  region            = local.region
+  name              = "instance-name"
+  resource_group_id = "xxXXxxXXxXxXXXXxxXxxxXXXXxXXXXX" # Replace with the actual ID of resource group to use
+}
 ```
 
 ### Required access policies
@@ -97,23 +122,36 @@ statement instead the previous block.
 
 | Name | Version |
 |------|---------|
-| <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.3.0 |
+| <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.9.0 |
+| <a name="requirement_ibm"></a> [ibm](#requirement\_ibm) | >= 1.71.2, < 2.0.0 |
 
 ### Modules
 
 No modules.
 
 ### Resources
 
-No resources.
+| Name | Type |
+|------|------|
+| [ibm_resource_instance.cos_instance](https://registry.terraform.io/providers/IBM-Cloud/ibm/latest/docs/resources/resource_instance) | resource |
 
 ### Inputs
 
-No inputs.
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| <a name="input_name"></a> [name](#input\_name) | A descriptive name used to identify the resource instance. | `string` | n/a | yes |
+| <a name="input_plan"></a> [plan](#input\_plan) | The name of the plan type supported by service. | `string` | `"standard"` | no |
+| <a name="input_resource_group_id"></a> [resource\_group\_id](#input\_resource\_group\_id) | The ID of the resource group where you want to create the service. | `string` | n/a | yes |
+| <a name="input_resource_tags"></a> [resource\_tags](#input\_resource\_tags) | List of resource tag to associate with the instance. | `list(string)` | `[]` | no |
 
 ### Outputs
 
-No outputs.
+| Name | Description |
+|------|-------------|
+| <a name="output_account_id"></a> [account\_id](#output\_account\_id) | An alpha-numeric value identifying the account ID. |
+| <a name="output_crn"></a> [crn](#output\_crn) | The CRN of the resource instance. |
+| <a name="output_guid"></a> [guid](#output\_guid) | The GUID of the resource instance. |
+| <a name="output_id"></a> [id](#output\_id) | The unique identifier of the resource instance. |
 <!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
 
 <!-- Leave this section as is so that your module has a link to local development environment set-up steps for contributors to follow -->

cra-config.yaml

@@ -1,11 +1,17 @@
-# 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
+#
+# Developer tips:
+#   - CRA = Code Risk Analyzer (more info on CRA: https://cloud.ibm.com/docs/code-risk-analyzer-cli-plugin?topic=code-risk-analyzer-cli-plugin-cra-cli-plugin)
+#   - Multiple directories can be scanned by CRA. Ensure if there are any deployable architecture in the repository that they are all scanned
+#   - More info about supported configurations 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/advanced" # 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`
-    PROFILE_ID: "0e6e7b5a-817d-4344-ab6f-e5d7a9c49520" # SCC profile ID (currently set to the FSCloud 1.4.0 profile).
+    CRA_IGNORE_RULES_FILE: "cra-tf-validate-ignore-rules.json"
+    PROFILE_ID: "fe96bd4d-9b37-40f2-b39f-a62760e326a3" # SCC profile ID (currently set to 'IBM Cloud Framework for Financial Services' '1.7.0' profile).
     # SCC_INSTANCE_ID: "" # The SCC instance ID to use to download profile for CRA scan. If not provided, a default global value will be used.
     # SCC_REGION: "" # The IBM Cloud region that the SCC instance is in. If not provided, a default global value will be used.
-    # 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"
-    #   TF_VAR_other:  "another value"
+    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_prefix: "mock"
+      TF_VAR_region: "us-south"

examples/advanced/main.tf

@@ -1,3 +1,32 @@
-##############################################################################
-# Complete example
-##############################################################################
+########################################################################################################################
+# Resource group
+########################################################################################################################
+
+module "resource_group" {
+  source  = "terraform-ibm-modules/resource-group/ibm"
+  version = "1.1.6"
+  # 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
+########################################################################################################################
+
+#
+# Developer tips:
+#   - Call the local module / modules in the example to show how they can be consumed
+#   - Include the actual module source as a code comment like below so consumers know how to consume from correct location
+#
+
+module "cos" {
+  source = "../.."
+  # remove the above line and uncomment the below 2 lines to consume the module from the registry
+  # source            = "terraform-ibm-modules/<replace>/ibm"
+  # version           = "X.Y.Z" # Replace "X.Y.Z" with a release version to lock into a specific release
+  name              = "${var.prefix}-cos"
+  resource_group_id = module.resource_group.resource_group_id
+  resource_tags     = var.resource_tags
+  plan              = "cos-one-rate-plan"
+}

examples/advanced/outputs.tf

@@ -2,22 +2,37 @@
 # Outputs
 ##############################################################################
 
-output "region" {
-  description = "The region all resources were provisioned in"
-  value       = var.region
+#
+# Developer tips:
+#   - Include all relevant outputs from the modules being called in the example
+#
+
+output "account_id" {
+  description = "An alpha-numeric value identifying the account ID."
+  value       = module.cos.account_id
+}
+
+output "guid" {
+  description = "The GUID of the resource instance."
+  value       = module.cos.account_id
+}
+
+output "id" {
+  description = "The unique identifier of the resource instance."
+  value       = module.cos.id
 }
 
-output "prefix" {
-  description = "The prefix used to name all provisioned resources"
-  value       = var.prefix
+output "crn" {
+  description = "The CRN of the resource instance."
+  value       = module.cos.crn
 }
 
 output "resource_group_name" {
-  description = "The name of the resource group used"
-  value       = var.resource_group
+  description = "Resource group name."
+  value       = module.resource_group.resource_group_name
 }
 
-output "resource_tags" {
-  description = "List of resource tags"
-  value       = var.resource_tags
+output "resource_group_id" {
+  description = "Resource group ID."
+  value       = module.resource_group.resource_group_id
 }

examples/advanced/variables.tf

@@ -1,29 +1,39 @@
+########################################################################################################################
+# Input variables
+########################################################################################################################
+
+#
+# Module developer tips:
+#   - Examples are references that consumers can use to see how the module can be consumed. They are not designed to be
+#     flexible re-usable solutions for general consumption, so do not expose any more variables here and instead hard
+#     code things in the example main.tf with code comments explaining the different configurations.
+#   - For the same reason as above, do not add default values to the example inputs.
+#
+
 variable "ibmcloud_api_key" {
   type        = string
-  description = "The IBM Cloud API Key"
+  description = "The IBM Cloud API Key."
   sensitive   = true
 }
 
 variable "region" {
   type        = string
-  description = "Region to provision all resources created by this example"
-  default     = "us-south"
+  description = "Region to provision all resources created by this example."
 }
 
 variable "prefix" {
   type        = string
-  description = "Prefix to append to all resources created by this example"
-  default     = "complete"
+  description = "A string value to prefix to all resources created by this example."
 }
 
 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
 }
 
 variable "resource_tags" {
   type        = list(string)
-  description = "Optional list of tags to be added to created resources"
+  description = "List of resource tag to associate with all resource instances created by this example."
   default     = []
 }

examples/advanced/version.tf

@@ -1,12 +1,16 @@
 terraform {
-  required_version = ">= 1.3.0"
+  required_version = ">= 1.9.0"
+
+  #
+  # Developer tips:
+  #   - 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.
+  #
 
-  # 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"
+      version = ">= 1.71.2, < 2.0.0"
     }
   }
 }

examples/basic/README.md

@@ -8,4 +8,4 @@ The text below should describe exactly what resources are provisioned / configur
 
 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.
+- A new standard plan Cloud Object Storage instance using the root level module.

examples/basic/main.tf

@@ -11,14 +11,21 @@ module "resource_group" {
 }
 
 ########################################################################################################################
-# COS instance
+# COS
 ########################################################################################################################
 
-resource "ibm_resource_instance" "cos_instance" {
+#
+# Developer tips:
+#   - Call the local module / modules in the example to show how they can be consumed
+#   - include the actual module source as a code comment like below so consumers know how to consume from correct location
+#
+
+module "cos" {
+  source = "../.."
+  # remove the above line and uncomment the below 2 lines to consume the module from the registry
+  # source            = "terraform-ibm-modules/<replace>/ibm"
+  # version           = "X.Y.Z" # Replace "X.Y.Z" with a release version to lock into a specific release
   name              = "${var.prefix}-cos"
   resource_group_id = module.resource_group.resource_group_id
-  service           = "cloud-object-storage"
-  plan              = "standard"
-  location          = "global"
-  tags              = var.resource_tags
+  resource_tags     = var.resource_tags
 }

examples/basic/outputs.tf

@@ -2,17 +2,37 @@
 # Outputs
 ########################################################################################################################
 
-output "cos_instance_id" {
-  description = "COS instance id"
-  value       = ibm_resource_instance.cos_instance.id
+#
+# Developer tips:
+#   - Include all relevant outputs from the modules being called in the example
+#
+
+output "account_id" {
+  description = "An alpha-numeric value identifying the account ID."
+  value       = module.cos.account_id
+}
+
+output "guid" {
+  description = "The GUID of the resource instance."
+  value       = module.cos.account_id
+}
+
+output "id" {
+  description = "The unique identifier of the resource instance."
+  value       = module.cos.id
+}
+
+output "crn" {
+  description = "The CRN of the resource instance."
+  value       = module.cos.crn
 }
 
 output "resource_group_name" {
-  description = "Resource group name"
+  description = "Resource group name."
   value       = module.resource_group.resource_group_name
 }
 
 output "resource_group_id" {
-  description = "Resource group ID"
+  description = "Resource group ID."
   value       = module.resource_group.resource_group_id
 }