feat: add working examples using root module (#289)

Author: vburckhardt

.gitmodules

@@ -1,3 +1,4 @@
 [submodule "common-dev-assets"]
 	path = common-dev-assets
 	url = https://github.com/terraform-ibm-modules/common-dev-assets
+	branch = main

README.md

@@ -136,7 +136,7 @@ statement instead the previous block.
 | Name | Version |
 |------|---------|
 | <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >=1.3 |
-| <a name="requirement_ibm"></a> [ibm](#requirement\_ibm) | ~>1.43.0 |
+| <a name="requirement_ibm"></a> [ibm](#requirement\_ibm) | >=1.43.0 |
 
 ## Modules
 
@@ -161,7 +161,7 @@ No modules.
 | <a name="input_resource_group_id"></a> [resource\_group\_id](#input\_resource\_group\_id) | ID of the resource group where endpoint gateways will be provisioned | `string` | `null` | no |
 | <a name="input_security_group_ids"></a> [security\_group\_ids](#input\_security\_group\_ids) | List of security group ids to attach to each endpoint gateway. | `list(string)` | `null` | no |
 | <a name="input_service_endpoints"></a> [service\_endpoints](#input\_service\_endpoints) | Service endpoints to use to create endpoint gateways. Can be `public`, or `private`. | `string` | `"private"` | no |
-| <a name="input_subnet_zone_list"></a> [subnet\_zone\_list](#input\_subnet\_zone\_list) | List of subnets in the VPC where gateways and reserved IPs will be provisioned. This value is intended to use the `subnet_zone_list` output from the ICSE VPC Subnet Module (https://github.com/Cloud-Schematics/vpc-subnet-module) or from templates using that module for subnet creation. | <pre>list(<br>    object({<br>      name = string<br>      id   = string<br>      zone = optional(string)<br>      cidr = optional(string)<br>    })<br>  )</pre> | `[]` | no |
+| <a name="input_subnet_zone_list"></a> [subnet\_zone\_list](#input\_subnet\_zone\_list) | List of subnets in the VPC where gateways and reserved IPs will be provisioned. This value is intended to use the `subnet_zone_list` output from the Landing Zone VPC Subnet Module (https://github.com/terraform-ibm-modules/terraform-ibm-landing-zone-vpc) or from templates using that module for subnet creation. | <pre>list(<br>    object({<br>      name = string<br>      id   = string<br>      zone = optional(string)<br>      cidr = optional(string)<br>    })<br>  )</pre> | `[]` | no |
 | <a name="input_vpc_id"></a> [vpc\_id](#input\_vpc\_id) | ID of the VPC where the Endpoint Gateways will be created | `string` | `null` | no |
 | <a name="input_vpc_name"></a> [vpc\_name](#input\_vpc\_name) | Name of the VPC where the Endpoint Gateways will be created. This value is used to dynamically generate VPE names. | `string` | `"vpc"` | no |
 

examples/default/main.tf

@@ -1,103 +1,53 @@
 ##############################################################################
-# VPE Locals
+# Resource Group
 ##############################################################################
-
-locals {
-  # List of Gateways to create
-  gateway_list = var.vpc_id == null ? [] : concat([
-    # Create object for each service
-    for service in var.cloud_services :
-    {
-      name    = "${var.vpc_name}-${service}"
-      service = service
-      crn     = null
-    }
-    ],
-    [
-      for service in var.cloud_service_by_crn :
-      {
-        name    = "${var.vpc_name}-${service.name}"
-        service = null
-        crn     = service.crn
-      }
-    ]
-  )
-
-  # List of IPs to create
-  endpoint_ip_list = var.vpc_id == null ? [] : flatten([
-    # Create object for each subnet
-    for subnet in var.subnet_zone_list :
-    [
-      for service in var.cloud_services :
-      {
-        ip_name      = "${subnet.name}-${service}-gateway-${replace(subnet.zone, "/${var.region}-/", "")}-ip"
-        subnet_id    = subnet.id
-        gateway_name = "${var.vpc_name}-${service}"
-      }
-    ]
-  ])
-
-  # Map of Services to endpoints
-  service_to_endpoint_map = {
-    kms                  = "crn:v1:bluemix:public:kms:${var.region}:::endpoint:${var.service_endpoints}.${var.region}.kms.cloud.ibm.com"
-    hs-crypt             = "crn:v1:bluemix:public:hs-crypto:${var.region}:::endpoint:api.${var.service_endpoints}.${var.region}.hs-crypto.cloud.ibm.com"
-    cloud-object-storage = "crn:v1:bluemix:public:cloud-object-storage:global:::endpoint:s3.direct.${var.region}.cloud-object-storage.appdomain.cloud"
-    container-registry   = "crn:v1:bluemix:public:container-registry:${var.region}:::endpoint:vpe.${var.region}.container-registry.cloud.ibm.com"
-  }
+module "resource_group" {
+  source = "git::https://github.com/terraform-ibm-modules/terraform-ibm-resource-group.git?ref=v1.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
 }
 
 ##############################################################################
 
 ##############################################################################
-# Create Reserved IPs
+# Create VPC
 ##############################################################################
 
-resource "ibm_is_subnet_reserved_ip" "ip" {
-  for_each = {
-    # Create a map based on endpoint IP name
-    for gateway_ip in local.endpoint_ip_list :
-    (gateway_ip.ip_name) => gateway_ip
-  }
-  subnet = each.value.subnet_id
+locals {
+  # input variable validation
+  # tflint-ignore: terraform_unused_declarations
+  validate_vpc_inputs = var.vpc_id == null && !var.create_vpc ? tobool("var.create_vpc should be set to true if var.vpc_id is set to null") : true
+  # tflint-ignore: terraform_unused_declarations
+  validate_vpc_id_and_create_vpc_both_not_set_inputs = var.vpc_id != null && var.create_vpc ? tobool("var.vpc_id cannot be set whilst var.create_vpc is set to true") : true
+  vpc_instance_id                                    = var.vpc_id == null ? tolist(ibm_is_vpc.vpc[*].id)[0] : var.vpc_id
 }
 
 ##############################################################################
-
-##############################################################################
-# Create Endpoint Gateways
+# Create a VPC for this example
 ##############################################################################
 
-resource "ibm_is_virtual_endpoint_gateway" "vpe" {
-  for_each = {
-    # Create map based on gateway name if enabled
-    for gateway in local.gateway_list :
-    (gateway.name) => gateway
-  }
-
-  name            = "${var.prefix}-${each.key}-endpoint-gateway"
-  vpc             = var.vpc_id
-  resource_group  = var.resource_group_id
-  security_groups = var.security_group_ids
-  target {
-    crn           = each.value.service == null ? each.value.crn : local.service_to_endpoint_map[each.value.service]
-    resource_type = "provider_cloud_service"
-  }
+resource "ibm_is_vpc" "vpc" {
+  count          = var.create_vpc ? 1 : 0
+  name           = "${var.prefix}-${var.vpc_name}"
+  resource_group = module.resource_group.resource_group_id
 }
 
 ##############################################################################
-
-##############################################################################
-# Attach Endpoint Gateways to Reserved IPs
-##############################################################################
-
-resource "ibm_is_virtual_endpoint_gateway_ip" "endpoint_gateway_ip" {
-  for_each = {
-    # Create a map based on endpoint IP
-    for gateway_ip in local.endpoint_ip_list :
-    (gateway_ip.ip_name) => gateway_ip
-  }
-  gateway     = ibm_is_virtual_endpoint_gateway.vpe[each.value.gateway_name].id
-  reserved_ip = ibm_is_subnet_reserved_ip.ip[each.key].reserved_ip
+# Create VPEs in the VPC
+##############################################################################
+module "vpes" {
+  source               = "../../"
+  region               = var.region
+  prefix               = var.prefix
+  vpc_name             = var.vpc_name
+  vpc_id               = local.vpc_instance_id
+  subnet_zone_list     = var.subnet_zone_list
+  resource_group_id    = module.resource_group.resource_group_id
+  security_group_ids   = var.security_group_ids
+  cloud_services       = var.cloud_services
+  cloud_service_by_crn = var.cloud_service_by_crn
+  service_endpoints    = var.service_endpoints
 }
 
 ##############################################################################

examples/default/provider.tf

@@ -0,0 +1,4 @@
+provider "ibm" {
+  ibmcloud_api_key = var.ibmcloud_api_key
+  region           = var.region
+}

examples/default/variables.tf

@@ -1,6 +1,8 @@
-##############################################################################
-# VPC Variables
-##############################################################################
+variable "ibmcloud_api_key" {
+  type        = string
+  description = "The IBM Cloud API Key"
+  sensitive   = true
+}
 
 variable "region" {
   description = "The region where VPC and services are deployed"
@@ -14,10 +16,20 @@ variable "prefix" {
   default     = "vpe"
 }
 
+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"
+  default     = null
+}
+
+##############################################################################
+# VPC Variables
+##############################################################################
+
 variable "vpc_name" {
   description = "Name of the VPC where the Endpoint Gateways will be created. This value is used to dynamically generate VPE names."
   type        = string
-  default     = "vpc"
+  default     = "my-vpc-instance"
 }
 
 variable "vpc_id" {
@@ -26,6 +38,18 @@ variable "vpc_id" {
   default     = null
 }
 
+variable "create_vpc" {
+  description = "Create a VPC instance."
+  type        = bool
+  default     = true
+}
+
+##############################################################################
+
+##############################################################################
+# VPE Variables
+##############################################################################
+
 variable "subnet_zone_list" {
   description = "List of subnets in the VPC where gateways and reserved IPs will be provisioned. This value is intended to use the `subnet_zone_list` output from the ICSE VPC Subnet Module (https://github.com/Cloud-Schematics/vpc-subnet-module) or from templates using that module for subnet creation."
   type = list(
@@ -39,18 +63,6 @@ variable "subnet_zone_list" {
   default = []
 }
 
-##############################################################################
-
-##############################################################################
-# VPE Variables
-##############################################################################
-
-variable "resource_group_id" {
-  description = "ID of the resource group where endpoint gateways will be provisioned"
-  type        = string
-  default     = null
-}
-
 variable "security_group_ids" {
   description = "List of security group ids to attach to each endpoint gateway."
   type        = list(string)

examples/default/versions.tf

@@ -3,13 +3,14 @@
 ##############################################################################
 
 terraform {
+  required_version = ">= 1.3.0"
   required_providers {
+    # Pin to the lowest provider version of the range defined in the main module's version.tf to ensure lowest version still works
     ibm = {
       source  = "IBM-Cloud/ibm"
-      version = "~>1.43.0"
+      version = "1.51.0"
     }
   }
-  required_version = ">=1.3"
 }
 
 ##############################################################################

examples/security-group/main.tf

@@ -0,0 +1,66 @@
+##############################################################################
+# Resource Group
+##############################################################################
+module "resource_group" {
+  source = "git::https://github.com/terraform-ibm-modules/terraform-ibm-resource-group.git?ref=v1.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
+}
+
+##############################################################################
+
+##############################################################################
+# Create VPC
+##############################################################################
+
+locals {
+  # input variable validation
+  # tflint-ignore: terraform_unused_declarations
+  validate_vpc_inputs = var.vpc_id == null && !var.create_vpc ? tobool("var.create_vpc should be set to true if var.vpc_id is set to null") : true
+  # tflint-ignore: terraform_unused_declarations
+  validate_vpc_id_and_create_vpc_both_not_set_inputs = var.vpc_id != null && var.create_vpc ? tobool("var.vpc_id cannot be set whilst var.create_vpc is set to true") : true
+  vpc_instance_id                                    = var.vpc_id == null ? tolist(ibm_is_vpc.vpc[*].id)[0] : var.vpc_id
+}
+
+##############################################################################
+# Create a VPC for this example
+##############################################################################
+
+resource "ibm_is_vpc" "vpc" {
+  count          = var.create_vpc ? 1 : 0
+  name           = "${var.prefix}-${var.vpc_name}"
+  resource_group = module.resource_group.resource_group_id
+}
+
+##############################################################################
+# Update security group
+##############################################################################
+
+module "create_sgr_rule" {
+  source                       = "git::https://github.com/terraform-ibm-modules/terraform-ibm-security-group.git?ref=v1.0.0"
+  add_ibm_cloud_internal_rules = var.add_ibm_cloud_internal_rules
+  security_group_name          = "${var.prefix}-1"
+  security_group_rules         = var.security_group_rules
+  resource_group               = module.resource_group.resource_group_id
+  vpc_id                       = local.vpc_instance_id
+}
+
+##############################################################################
+# Create VPEs in the VPC
+##############################################################################
+module "vpes" {
+  source               = "../../"
+  region               = var.region
+  prefix               = var.prefix
+  vpc_name             = var.vpc_name
+  vpc_id               = local.vpc_instance_id
+  subnet_zone_list     = var.subnet_zone_list
+  cloud_services       = var.cloud_services
+  cloud_service_by_crn = var.cloud_service_by_crn
+  service_endpoints    = var.service_endpoints
+  security_group_ids   = [module.create_sgr_rule.security_group_id]
+  resource_group_id    = module.resource_group.resource_group_id
+}
+
+##############################################################################

examples/security-group/outputs.tf

@@ -0,0 +1,3 @@
+##############################################################################
+# Please open an issue to suggest outputs for this module
+##############################################################################

examples/security-group/provider.tf

@@ -0,0 +1,4 @@
+provider "ibm" {
+  ibmcloud_api_key = var.ibmcloud_api_key
+  region           = var.region
+}