fix: add deprecation notice for the vpn_gateways input (see [VPN Gateway migration steps](https://github.com/terraform-ibm-modules/terraform-ibm-landing-zone-vpc/blob/main/docs/migration_guide.md) (#1041)

imprateeksh · web-flow · commit 7f953b881c42 · 2026-01-20T12:50:39.000Z
diff --git a/README.md b/README.md
@@ -6,6 +6,8 @@
 [![latest release](https://img.shields.io/github/v/release/terraform-ibm-modules/terraform-ibm-landing-zone-vpc?logo=GitHub&sort=semver)](https://github.com/terraform-ibm-modules/terraform-ibm-landing-zone-vpc/releases/latest)
 [![Renovate enabled](https://img.shields.io/badge/renovate-enabled-brightgreen.svg)](https://renovatebot.com/)
 
+> ⚠️ In `v9.0.0` this module will no longer support VPN gateway functionality. Please see [migration guide](https://github.com/terraform-ibm-modules/terraform-ibm-landing-zone-vpc/blob/main/docs/migration_guide.md) for steps on how to migrate to the [terraform-ibm-site-to-site-vpn](https://github.com/terraform-ibm-modules/terraform-ibm-site-to-site-vpn) module.
+
 This module creates the following IBM Cloud&reg; Virtual Private Cloud (VPC) network components:
 
 - VPC: Creates a VPC in a resource group. The VPC and components are specified in the [main.tf](main.tf) file.
@@ -131,6 +133,7 @@ module.subnets.ibm_is_vpc_address_prefix.subnet_prefix["gcat-multizone-subnet-c"
 ```
 
 ### Required IAM access policies
+
 You need the following permissions to run this module.
 
 - IAM services
@@ -188,6 +191,7 @@ To attach access management tags to resources in this module, you need the follo
 | [ibm_is_vpc_routing_table_route.routing_table_routes](https://registry.terraform.io/providers/IBM-Cloud/ibm/latest/docs/resources/is_vpc_routing_table_route) | resource |
 | [ibm_is_vpn_gateway.vpn_gateway](https://registry.terraform.io/providers/IBM-Cloud/ibm/latest/docs/resources/is_vpn_gateway) | resource |
 | [ibm_resource_instance.dns_instance_hub](https://registry.terraform.io/providers/IBM-Cloud/ibm/latest/docs/resources/resource_instance) | resource |
+| [terraform_data.deprecation_warning](https://registry.terraform.io/providers/hashicorp/terraform/latest/docs/resources/data) | resource |
 | [time_sleep.wait_for_authorization_policy](https://registry.terraform.io/providers/hashicorp/time/latest/docs/resources/sleep) | resource |
 | [time_sleep.wait_for_vpc_creation_data](https://registry.terraform.io/providers/hashicorp/time/latest/docs/resources/sleep) | resource |
 | [ibm_iam_account_settings.iam_account_settings](https://registry.terraform.io/providers/IBM-Cloud/ibm/latest/docs/data-sources/iam_account_settings) | data source |
@@ -249,7 +253,7 @@ To attach access management tags to resources in this module, you need the follo
 | <a name="input_use_existing_dns_instance"></a> [use\_existing\_dns\_instance](#input\_use\_existing\_dns\_instance) | Whether to use an existing dns instance. If true, existing\_dns\_instance\_id must be set. | `bool` | `false` | no |
 | <a name="input_use_public_gateways"></a> [use\_public\_gateways](#input\_use\_public\_gateways) | Create a public gateway in any of the three zones with `true`. | <pre>object({<br/>    zone-1 = optional(bool)<br/>    zone-2 = optional(bool)<br/>    zone-3 = optional(bool)<br/>  })</pre> | <pre>{<br/>  "zone-1": true,<br/>  "zone-2": true,<br/>  "zone-3": true<br/>}</pre> | no |
 | <a name="input_vpc_flow_logs_name"></a> [vpc\_flow\_logs\_name](#input\_vpc\_flow\_logs\_name) | The name to give the provisioned VPC flow logs. If not set, the module generates a name based on the `prefix` and `name` variables. | `string` | `null` | no |
-| <a name="input_vpn_gateways"></a> [vpn\_gateways](#input\_vpn\_gateways) | List of VPN gateways to create. | <pre>list(<br/>    object({<br/>      name           = string<br/>      subnet_name    = string # Do not include prefix, use same name as in `var.subnets`<br/>      mode           = optional(string)<br/>      resource_group = optional(string)<br/>      access_tags    = optional(list(string), [])<br/>    })<br/>  )</pre> | `[]` | no |
+| <a name="input_vpn_gateways"></a> [vpn\_gateways](#input\_vpn\_gateways) | [DEPRECATED] List of VPN gateways to create. For more information please refer the [migration guide](https://github.com/terraform-ibm-modules/terraform-ibm-landing-zone-vpc/blob/main/docs/migration_guide.md). | <pre>list(<br/>    object({<br/>      name           = string<br/>      subnet_name    = string # Do not include prefix, use same name as in `var.subnets`<br/>      mode           = optional(string, "route")<br/>      resource_group = optional(string)<br/>      access_tags    = optional(list(string), [])<br/>    })<br/>  )</pre> | `[]` | no |
 
 ### Outputs
 
@@ -277,8 +281,8 @@ To attach access management tags to resources in this module, you need the follo
 | <a name="output_vpc_flow_logs"></a> [vpc\_flow\_logs](#output\_vpc\_flow\_logs) | Details of VPC flow logs collector |
 | <a name="output_vpc_id"></a> [vpc\_id](#output\_vpc\_id) | ID of VPC created |
 | <a name="output_vpc_name"></a> [vpc\_name](#output\_vpc\_name) | Name of VPC created |
-| <a name="output_vpn_gateways_data"></a> [vpn\_gateways\_data](#output\_vpn\_gateways\_data) | Details of VPN gateways data. |
-| <a name="output_vpn_gateways_name"></a> [vpn\_gateways\_name](#output\_vpn\_gateways\_name) | List of names of VPN gateways. |
+| <a name="output_vpn_gateways_data"></a> [vpn\_gateways\_data](#output\_vpn\_gateways\_data) | [DEPRECATED] Details of VPN gateways data. For more information please refer the [migration guide](https://github.com/terraform-ibm-modules/terraform-ibm-landing-zone-vpc/blob/main/docs/migration_guide.md). |
+| <a name="output_vpn_gateways_name"></a> [vpn\_gateways\_name](#output\_vpn\_gateways\_name) | [DEPRECATED] List of names of VPN gateways. For more information please refer the [migration guide](https://github.com/terraform-ibm-modules/terraform-ibm-landing-zone-vpc/blob/main/docs/migration_guide.md). |
 <!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
 
 ## Contributing
diff --git a/docs/migration_guide.md b/docs/migration_guide.md
@@ -0,0 +1,106 @@
+# VPN Gateway migration steps
+
+## VPN Gateway changes in `v9.0.0`
+
+* Starting with version `v9.0.0`, direct use of the VPN gateway in the main setup will be **removed**.
+* Instead of defining the VPN gateway resources, reference the [`terraform-ibm-modules/site-to-site-vpn`](https://github.com/terraform-ibm-modules/terraform-ibm-site-to-site-vpn) module.
+* Users must migrate their Terraform state and update outputs to avoid resource recreation and broken references.
+
+## Overview
+
+This change improves maintainability and consistency by consolidating VPN gateway logic into a dedicated module.
+Because resource addresses and outputs have changed, you must migrate your Terraform state and update any dependent references.
+
+This release introduces the following changes:
+
+1. Resource address migration (using `terraform state mv` and new helper resources).
+2. Output block changes (deprecation of `vpn_gateways_name` and link to new outputs).
+
+## Resource Address Migration
+
+The module to create VPN gateways can now be used as shown in the below example.
+
+```hcl
+module "vpn_gateways" {
+  source                = "terraform-ibm-modules/site-to-site-vpn/ibm"
+  version               = "3.0.4" # Replace with the version of site to site VPN Module
+  for_each              = {
+    vpn_gw_1 = {
+      resource_group_id     = "xxXXxxXXxXxXXXXxxXxxxXXXXxXXXXX" # Replace with your resource group id.
+      name      = "gateway-1"
+      mode      = "route"
+      subnet_id = "xxXXxxXXxXxXXXXxxXxxxXXXXxXXXXX" # Replace with the subnet id where VPN Gateway will be created.
+    }
+    vpn_gw_2 = {
+      resource_group_id     = "xxXXxxXXxXxXXXXxxXxxxXXXXxXXXXX" # Replace with your resource group id.
+      name      = "gateway-2"
+      mode      = "policy"
+      subnet_id = "xxXXxxXXxXxXXXXxxXxxxXXXXxXXXXX" # Replace with the subnet id where VPN Gateway will be created.
+    }
+  }
+  resource_group_id     = each.value.resource_group_id
+  vpn_gateway_name      = each.value.name
+  vpn_gateway_subnet_id = each.value.subnet_id
+  vpn_gateway_mode      = each.value.mode
+}
+```
+
+**Resource address (current):** `module.<module-name>.ibm_is_vpn_gateway.vpn_gateway["<gateway-name>"]`
+**Resource address (after migration):** `module.<module-name>.module.vpn_gateways["<gateway-name>"]`.ibm_is_vpn_gateway.vpn_gateway[0]`
+
+## Migration Command
+
+If you are upgrading an existing environment, you need to tell Terraform that the resource has moved so it doesn’t try to recreate it.
+
+**Option 1: Using moved block :**
+
+```hcl
+moved {
+  from = module.<module-name>.ibm_is_vpn_gateway.vpn_gateway["gateway-1"]
+  to   = module.<module-name>.module.vpn_gateways["gateway-1"].ibm_is_vpn_gateway.vpn_gateway[0]
+}
+```
+
+**Option 2: Using terraform state mv (manual alternative):**
+
+Use the terraform state mv command to migrate each gateway:
+
+```sh
+terraform state mv 'module.<module-name>.ibm_is_vpn_gateway.vpn_gateway[<gateway-name>]' 'module.<module-name>.module.vpn_gateways[<gateway-name>].ibm_is_vpn_gateway.vpn_gateway[0]'
+```
+
+**Example:**
+
+If the name of `vpn_gateway` is `gateway-1`, i.e.
+
+```hcl
+vpn_gateways = [{
+      name           = "gateway-1"
+      subnet_name    = "subnet-a"
+  }]
+```
+
+Then terraform state moved command that can be used is:
+
+```sh
+terraform state mv 'module.<module-name>.ibm_is_vpn_gateway.vpn_gateway["gateway-1"]' 'module.<module-name>.module.vpn_gateways["gateway-1"].ibm_is_vpn_gateway.vpn_gateway[0]'
+```
+
+## New Resources
+
+The vpn_gateways module introduces helper resources (e.g., `time_sleep.wait_for_gateway_creation`). This is new and will be created automatically on the next apply. No migration is required.
+
+## Output block changes
+
+* The `site‑to‑site-vpn` module does not expose VPN names directly thus the output `vpn_gateways_name` will no longer be available.
+
+* The existing `vpn_gateways_data` will be updated to consume the module, i.e.
+
+``` hcl
+output "vpn_gateways_data" {
+  description = "Details of VPN gateways data."
+  value = [
+    for gateway in module.vpn_gateways : gateway
+  ]
+}
+```
diff --git a/main.tf b/main.tf
@@ -433,6 +433,7 @@ locals {
 ##############################################################################
 # Create VPN Gateways
 ##############################################################################
+# ⚠️ [DEPRECATED]. Refer the [migration guide](https://github.com/terraform-ibm-modules/terraform-ibm-landing-zone-vpc/blob/main/docs/migration_guide.md) for more information.
 
 locals {
   # Convert the vpn_gateway input from list to a map
@@ -454,4 +455,20 @@ resource "ibm_is_vpn_gateway" "vpn_gateway" {
   }
 }
 
+# This block will be removed once the migration to the [terraform-ibm-site-to-site-vpn](https://github.com/terraform-ibm-modules/terraform-ibm-site-to-site-vpn) module is completed.
+
+resource "terraform_data" "deprecation_warning" {
+
+  count = length(var.vpn_gateways) > 0 ? 1 : 0
+
+  triggers_replace = {
+    always_run = timestamp()
+  }
+  provisioner "local-exec" {
+    command = <<EOT
+echo "[WARNING] DEPRECATED variable 'vpn_gateways' is in use. Please migrate to the new variable.
+See migration guide: https://github.com/terraform-ibm-modules/terraform-ibm-landing-zone-vpc/blob/main/docs/migration_guide.md"
+EOT
+  }
+}
 ##############################################################################
diff --git a/outputs.tf b/outputs.tf
@@ -203,15 +203,15 @@ output "dns_record_ids" {
 ##############################################################################
 
 output "vpn_gateways_name" {
-  description = "List of names of VPN gateways."
+  description = "[DEPRECATED] List of names of VPN gateways. For more information please refer the [migration guide](https://github.com/terraform-ibm-modules/terraform-ibm-landing-zone-vpc/blob/main/docs/migration_guide.md)."
   value = [
     for gateway in ibm_is_vpn_gateway.vpn_gateway :
     gateway.name
   ]
 }
 
 output "vpn_gateways_data" {
-  description = "Details of VPN gateways data."
+  description = "[DEPRECATED] Details of VPN gateways data. For more information please refer the [migration guide](https://github.com/terraform-ibm-modules/terraform-ibm-landing-zone-vpc/blob/main/docs/migration_guide.md)."
   value = [
     for gateway in ibm_is_vpn_gateway.vpn_gateway :
     gateway
diff --git a/tests/pr_test.go b/tests/pr_test.go
@@ -58,6 +58,16 @@ var dnsZoneMap = []map[string]interface{}{
 	{"name": "slz.com"},
 }
 
+var IgnoreUpdates = []string{
+	"module.slz_vpc.terraform_data.deprecation_warning",
+	"module.vpc.terraform_data.deprecation_warning[0]",
+}
+
+var IgnoreDestroys = []string{
+	"module.slz_vpc.terraform_data.deprecation_warning",
+	"module.vpc.terraform_data.deprecation_warning[0]",
+}
+
 func TestMain(m *testing.M) {
 	// Read the YAML file contents
 	var err error
@@ -78,6 +88,12 @@ func setupOptions(t *testing.T, prefix string, terraformDir string) *testhelper.
 		TerraformVars: map[string]interface{}{
 			"access_tags": permanentResources["accessTags"],
 		},
+		IgnoreUpdates: testhelper.Exemptions{ // Ignore for consistency check
+			List: IgnoreUpdates,
+		},
+		IgnoreDestroys: testhelper.Exemptions{ // Ignore for consistency check
+			List: IgnoreDestroys,
+		},
 	})
 
 	return options
@@ -280,6 +296,12 @@ func TestFullyConfigurableWithFlowLogs(t *testing.T) {
 		DeleteWorkspaceOnFail:  false,
 		WaitJobCompleteMinutes: 120,
 		TerraformVersion:       terraformVersion,
+		IgnoreUpdates: testhelper.Exemptions{ // Ignore for consistency check
+			List: IgnoreUpdates,
+		},
+		IgnoreDestroys: testhelper.Exemptions{ // Ignore for consistency check
+			List: IgnoreDestroys,
+		},
 	})
 
 	options.TerraformVars = []testschematic.TestSchematicTerraformVar{
diff --git a/variables.tf b/variables.tf
@@ -817,13 +817,13 @@ variable "dns_records" {
 ##############################################################################
 
 variable "vpn_gateways" {
-  description = "List of VPN gateways to create."
+  description = "[DEPRECATED] List of VPN gateways to create. For more information please refer the [migration guide](https://github.com/terraform-ibm-modules/terraform-ibm-landing-zone-vpc/blob/main/docs/migration_guide.md)."
   nullable    = false
   type = list(
     object({
       name           = string
       subnet_name    = string # Do not include prefix, use same name as in `var.subnets`
-      mode           = optional(string)
+      mode           = optional(string, "route")
       resource_group = optional(string)
       access_tags    = optional(list(string), [])
     })
