doc: deprecate in-module VPN gateway and introduce site-to-site-vpn module

.docs/migration_guide.md

@@ -0,0 +1,99 @@
+# Migration Guide
+
+## ⚠️ Deprecation Notice
+
+In the upcoming version, the direct use of `ibm_is_vpn_gateway` resources in the root module will be **deprecated**.
+These resources have been refactored into the reusable [`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.
+
+
+## Changes
+
+Below changes are planned :
+
+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
+
+### Before:
+
+```hcl
+resource "ibm_is_vpn_gateway" "vpn_gateway" {
+  for_each = local.vpn_gateway_map
+  ...
+}
+```
+
+**Resource address:** `module.slz_vpc.ibm_is_vpn_gateway.vpn_gateway["<key>"]`
+
+### After:
+
+```hcl
+module "vpn_gateways" {
+  source                = "terraform-ibm-modules/site-to-site-vpn/ibm"
+  version               = "3.0.0"
+  for_each              = local.vpn_gateway_map
+  resource_group_id     = each.value.resource_group == null ? var.resource_group_id : each.value.resource_group
+  tags                  = var.tags
+
+  vpn_gateway_name      = var.prefix != null ? "${var.prefix}-${each.key}" : each.key
+  vpn_gateway_subnet_id = local.subnets["${local.vpc_name}-${each.value.subnet_name}"].id
+  vpn_gateway_mode      = each.value.mode
+}
+```
+
+**Resource address:** `module.slz_vpc.module.vpn_gateways["<key>"].ibm_is_vpn_gateway.vpn_gateway[0]`
+
+## Migration Command
+
+Use the terraform state mv command to migrate each gateway:
+
+```sh
+terraform state mv 'module.slz_vpc.ibm_is_vpn_gateway.vpn_gateway[<key>]' 'module.slz_vpc.module.vpn_gateways[<key>].ibm_is_vpn_gateway.vpn_gateway[0]'
+```
+
+**Example:**
+
+If the name of `vpn_gateway` is `"vpg1"`, i.e.
+
+```hcl
+vpn_gateways = [{
+      name           = "vpg1"
+      subnet_name    = "subnet-a"
+  }]
+```
+
+Then terraform state moved command that can be used is:
+
+```sh
+terraform state mv \
+  'module.slz_vpc.ibm_is_vpn_gateway.vpn_gateway["vpg1"]' \
+  'module.slz_vpc.module.vpn_gateways["vpg1"].ibm_is_vpn_gateway.vpn_gateway[0]'
+```
+
+Repeat this for all the keys in `local.vpn_gateway_map`.
+
+## 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
+  ]
+}
+```

README.md

@@ -128,7 +128,41 @@ module.subnets.ibm_is_vpc_address_prefix.subnet_prefix["gcat-multizone-subnet-b"
 module.subnets.ibm_is_vpc_address_prefix.subnet_prefix["gcat-multizone-subnet-c"]
 ```
 
+## ​ Upgrade Guide: Migrating VPN from Landing Zone VPC Module to Standalone Site-to-Site VPN Module
+
+### Overview
+
+The `terraform-ibm-landing-zone-vpc` module previously included built-in VPN provisioning via the `vpn_gateways` variable. That functionality has now been extracted into a dedicated `terraform-ibm-site-to-site-vpn` module for better modularity, flexibility, and maintainability.
+
+> **Note:** The legacy VPN logic within the IBM Cloud Landing Zone VPC module is **deprecated** and will be removed in an upcoming major release.
+
+## Migration Steps
+
+### 1. Retain Legacy Behavior (Deprecated)
+
+If you are still using `vpn_gateways` within the IBM Cloud Landing Zone VPC module, it will continue to work for now. However, you should see a deprecation warning:
+
+```hcl
+module "landing_zone_vpc" {
+  source  = "terraform-ibm-modules/landing-zone-vpc/ibm"
+  version = "X.Y.Z"
+
+  # Legacy VPN provisioning logic (Deprecated)
+  vpn_gateways =   ["vpn-gateway1", "vpn-gateway2"]
+
+  # ​​ Deprecated: VPN provisioning in this module ⚠️
+  #
+  # Note: This functionality will be removed in the upcoming release.
+  # Please migrate to the standalone [terraform-ibm-site-to-site-vpn](https://github.com/terraform-ibm-modules/terraform-ibm-site-to-site-vpn/blob/main) module.
+}
+```
+
+### 2. Add the New Site-to-Site VPN Module
+
+Refer [usage](https://github.com/terraform-ibm-modules/terraform-ibm-site-to-site-vpn/blob/main/README.md#usage) section as mentioned in the [terraform-ibm-site-to-site-vpn](https://github.com/terraform-ibm-modules/terraform-ibm-site-to-site-vpn/blob/main) module.
+
 ### Required IAM access policies
+
 You need the following permissions to run this module.
 
 - IAM services
@@ -247,7 +281,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) | 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, "route")<br/>      resource_group = optional(string)<br/>      access_tags    = optional(list(string), [])<br/>    })<br/>  )</pre> | `[]` | no |
 
 ### Outputs
 

dynamic_values/config_modules/list_to_map/variables.tf

@@ -26,7 +26,7 @@ variable "lookup_field" {
 }
 
 variable "lookup_value_regex" {
-  description = "regular expression for reurned value"
+  description = "regular expression for returned value"
   type        = string
   default     = null
 }

main.tf

@@ -433,6 +433,8 @@ locals {
 ##############################################################################
 # Create VPN Gateways
 ##############################################################################
+# ⚠️ Provisioning of VPN Gateways will soon be deprecated.
+# Please refer [IBM Cloud site-to-site VPN](https://github.com/terraform-ibm-modules/terraform-ibm-site-to-site-vpn/blob/main/README.md#usage) module.
 
 locals {
   # Convert the vpn_gateway input from list to a map

variables.tf

@@ -808,7 +808,7 @@ variable "vpn_gateways" {
     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), [])
     })