From f7692632b55559b6b17c1f2f3bfc2cc04ac3cdd5 Mon Sep 17 00:00:00 2001
From: Volodymyr Manilo <wmanilo@gmail.com>
Date: Tue, 12 Dec 2023 22:38:35 +0100
Subject: [PATCH] added migration guide

---
 docs/guides/migrate-guide-v1-to-v2.md         | 59 +++++++++++++++++++
 .../guides/migrate-guide-v1-to-v2.md.tmpl     | 59 +++++++++++++++++++
 .../internal/provider/resource/resource.go    |  3 +-
 3 files changed, 120 insertions(+), 1 deletion(-)
 create mode 100644 docs/guides/migrate-guide-v1-to-v2.md
 create mode 100644 templates/guides/migrate-guide-v1-to-v2.md.tmpl

diff --git a/docs/guides/migrate-guide-v1-to-v2.md b/docs/guides/migrate-guide-v1-to-v2.md
new file mode 100644
index 00000000..c0cbda9c
--- /dev/null
+++ b/docs/guides/migrate-guide-v1-to-v2.md
@@ -0,0 +1,59 @@
+---
+subcategory: "migration"
+page_title: "Migrate Guide from v1 to v2"
+description: |-
+This document walks you through a migration process from v1 to v2
+---
+
+# Migration Guide
+
+Migration needs to be done only for Twingate Resource objects in Terraform code. 
+
+Changes affected schema of Resource `protocols` section, it was changed from block to object attribute.
+
+For example, you may have Resource like this:
+
+```terraform
+resource "twingate_resource" "resource" {
+  name = "resource"
+  address = "internal.int"
+  remote_network_id = twingate_remote_network.aws_network.id
+
+  protocols {
+    allow_icmp = true
+    tcp {
+      policy = "RESTRICTED"
+      ports = ["80", "82-83"]
+    }
+    udp {
+      policy = "ALLOW_ALL"
+    }
+  }
+}
+```
+
+Main changes are about:
+`protocols {` -> `protocols = {`
+`tcp {` -> `tcp = {`
+`udp {` -> `udp = {`
+
+After changes, your Resource will look like this:
+
+```terraform
+resource "twingate_resource" "resource" {
+  name = "resource"
+  address = "internal.int"
+  remote_network_id = twingate_remote_network.aws_network.id
+
+  protocols = {
+    allow_icmp = true
+    tcp = {
+      policy = "RESTRICTED"
+      ports = ["80", "82-83"]
+    }
+    udp = {
+      policy = "ALLOW_ALL"
+    }
+  }
+}
+```
\ No newline at end of file
diff --git a/templates/guides/migrate-guide-v1-to-v2.md.tmpl b/templates/guides/migrate-guide-v1-to-v2.md.tmpl
new file mode 100644
index 00000000..c0cbda9c
--- /dev/null
+++ b/templates/guides/migrate-guide-v1-to-v2.md.tmpl
@@ -0,0 +1,59 @@
+---
+subcategory: "migration"
+page_title: "Migrate Guide from v1 to v2"
+description: |-
+This document walks you through a migration process from v1 to v2
+---
+
+# Migration Guide
+
+Migration needs to be done only for Twingate Resource objects in Terraform code. 
+
+Changes affected schema of Resource `protocols` section, it was changed from block to object attribute.
+
+For example, you may have Resource like this:
+
+```terraform
+resource "twingate_resource" "resource" {
+  name = "resource"
+  address = "internal.int"
+  remote_network_id = twingate_remote_network.aws_network.id
+
+  protocols {
+    allow_icmp = true
+    tcp {
+      policy = "RESTRICTED"
+      ports = ["80", "82-83"]
+    }
+    udp {
+      policy = "ALLOW_ALL"
+    }
+  }
+}
+```
+
+Main changes are about:
+`protocols {` -> `protocols = {`
+`tcp {` -> `tcp = {`
+`udp {` -> `udp = {`
+
+After changes, your Resource will look like this:
+
+```terraform
+resource "twingate_resource" "resource" {
+  name = "resource"
+  address = "internal.int"
+  remote_network_id = twingate_remote_network.aws_network.id
+
+  protocols = {
+    allow_icmp = true
+    tcp = {
+      policy = "RESTRICTED"
+      ports = ["80", "82-83"]
+    }
+    udp = {
+      policy = "ALLOW_ALL"
+    }
+  }
+}
+```
\ No newline at end of file
diff --git a/twingate/internal/provider/resource/resource.go b/twingate/internal/provider/resource/resource.go
index ae03b9a3..0a802b51 100644
--- a/twingate/internal/provider/resource/resource.go
+++ b/twingate/internal/provider/resource/resource.go
@@ -364,7 +364,8 @@ func (r *twingateResource) UpgradeState(ctx context.Context) map[int64]resource.
 
 				resp.Diagnostics.Append(resp.State.Set(ctx, upgradedState)...)
 
-				resp.Diagnostics.AddWarning("Please upgrade protocols sections", "Follow this docs to update protocols from blocks to attributes")
+				resp.Diagnostics.AddWarning("Please update the protocols sections format from a block to an object",
+					"See the v1 to v2 migration guide in the Twingate Terraform Provider documentation https://registry.terraform.io/providers/Twingate/twingate/latest/docs/guides/migrate-guide-v1-to-v2")
 			},
 		},
 	}