[Docs] Adding v2 to v3 migration guide (Twingate#506)

* [Docs] Adding v2 to v3 migration guide * make docs * spellcheck * Update YAML in migration guides * fix format on older docs --------- Co-authored-by: Bob Lee <[email protected]> Co-authored-by: bertekintw <[email protected]>
vmanilo · Apr 18, 2024 · 4dcfe2c · 4dcfe2c
1 parent a321212
commit 4dcfe2c
Show file tree

Hide file tree

Showing 8 changed files with 132 additions and 12 deletions.
diff --git a/docs/guides/aws-deployment-guide.md b/docs/guides/aws-deployment-guide.md
@@ -1,8 +1,7 @@
 ---
 subcategory: "aws"
 page_title: "AWS EC2 Deployment Guide"
-description: |-
-This document walks you through a basic deployment using Twingate's Terraform provider on AWS
+description: "This document walks you through a basic deployment using Twingate's Terraform provider on AWS"
 ---
 
 # Deployment Guide

diff --git a/docs/guides/gke-helm-provider-deployment-guide.md b/docs/guides/gke-helm-provider-deployment-guide.md
@@ -1,8 +1,7 @@
 ---
 subcategory: "gke"
 page_title: "GKE Helm Provider Deployment Guide"
-description: |-
-This document walks you through a basic deployment using Twingate's Terraform provider on GKE using the Helm Terraform provider
+description: "This document walks you through a basic deployment using Twingate's Terraform provider on GKE using the Helm Terraform provider"
 ---
 
 # Deployment Guide

diff --git a/docs/guides/migration-v1-to-v2-guide.md b/docs/guides/migration-v1-to-v2-guide.md
@@ -1,8 +1,7 @@
 ---
 subcategory: "migration"
 page_title: "v1 to v2 Migration Guide"
-description: |-
-This document covers how to migrate from v1 to v2 of the Twingate Terraform provider.
+description: "This document covers how to migrate from v1 to v2 of the Twingate Terraform provider."
 ---
 
 # Migration Guide

diff --git a/docs/guides/migration-v2-to-v3-guide.md b/docs/guides/migration-v2-to-v3-guide.md
@@ -0,0 +1,63 @@
+---
+subcategory: "migration"
+page_title: "v2 to v3 Migration Guide"
+description: "This document covers how to migrate from v2 to v3 of the Twingate Terraform provider."
+---
+
+# Migration Guide
+
+This guide covers how to migrate from v2.x.x to v3.0.0 of the Twingate Terraform provider. Migration needs to be done for the following objects:
+- Resources
+    - `twingate_resource`
+
+## Migrating Resources
+
+The `access` block `twingate_resource` has been separated into two blocks: `access_group` and `access_service`. Access for Groups and Service Accounts is now specified separately. This change is primarily to enable specifying a Security Policy ID for a Group's access. 
+
+In v2.x.x, the following was valid:
+
+```terraform
+resource "twingate_resource" "resource" {
+  name = "resource"
+  address = "internal.int"
+  remote_network_id = twingate_remote_network.aws_network.id
+
+  access {
+    group_ids = [twingate_group.aws.id]
+    service_account_ids = [twingate_service_account.github_actions_prod.id]
+  }
+}
+```
+
+From v3.0.0 and onward, access must be specified using the `access_group` and `access_service` blocks. Further, `access_group` can only be specified for a single group and no longer uses a list of group IDs.
+
+```terraform
+resource "twingate_resource" "resource" {
+  name = "resource"
+  address = "internal.int"
+  remote_network_id = twingate_remote_network.aws_network.id
+
+  // Group access is now assigned via the `access_group` block
+  // Further, security policies may now (optionally) be specified within
+  // an `access_group` block.
+  access_group {
+      security_policy_id = twingate_security_policy.no_mfa.id
+      group_id = data.twingate_groups.devops.id
+  }
+  
+  // To assign access to multiple groups, use a `dynamic` block
+  dynamic access_group {
+    for_each = toset([twingate_groups.infra.id, twingate_groups.security.id])
+    content {
+      security_policy_id = twingate_security_policy.no_mfa.id
+      group_id = access.value.key
+    }
+  }
+  
+  // Service accounts are now assigned via the `service_access` block
+  // Service accounts do not use policies and, as such, one cannot be specified
+  access_service {
+    service_account_id = twingate_service_account.github_actions_prod.id
+  }
+```
+
diff --git a/templates/guides/aws-deployment-guide.md.tmpl b/templates/guides/aws-deployment-guide.md.tmpl
@@ -1,8 +1,7 @@
 ---
 subcategory: "aws"
 page_title: "AWS EC2 Deployment Guide"
-description: |-
-This document walks you through a basic deployment using Twingate's Terraform provider on AWS
+description: "This document walks you through a basic deployment using Twingate's Terraform provider on AWS"
 ---
 
 # Deployment Guide

diff --git a/templates/guides/gke-helm-provider-deployment-guide.md.tmpl b/templates/guides/gke-helm-provider-deployment-guide.md.tmpl
@@ -1,8 +1,7 @@
 ---
 subcategory: "gke"
 page_title: "GKE Helm Provider Deployment Guide"
-description: |-
-This document walks you through a basic deployment using Twingate's Terraform provider on GKE using the Helm Terraform provider
+description: "This document walks you through a basic deployment using Twingate's Terraform provider on GKE using the Helm Terraform provider"
 ---
 
 # Deployment Guide

diff --git a/templates/guides/migration-v1-to-v2-guide.md.tmpl b/templates/guides/migration-v1-to-v2-guide.md.tmpl
@@ -1,8 +1,7 @@
 ---
 subcategory: "migration"
 page_title: "v1 to v2 Migration Guide"
-description: |-
-This document covers how to migrate from v1 to v2 of the Twingate Terraform provider.
+description: "This document covers how to migrate from v1 to v2 of the Twingate Terraform provider."
 ---
 
 # Migration Guide

diff --git a/templates/guides/migration-v2-to-v3-guide.md.tmpl b/templates/guides/migration-v2-to-v3-guide.md.tmpl
@@ -0,0 +1,63 @@
+---
+subcategory: "migration"
+page_title: "v2 to v3 Migration Guide"
+description: "This document covers how to migrate from v2 to v3 of the Twingate Terraform provider."
+---
+
+# Migration Guide
+
+This guide covers how to migrate from v2.x.x to v3.0.0 of the Twingate Terraform provider. Migration needs to be done for the following objects:
+- Resources
+    - `twingate_resource`
+
+## Migrating Resources
+
+The `access` block `twingate_resource` has been separated into two blocks: `access_group` and `access_service`. Access for Groups and Service Accounts is now specified separately. This change is primarily to enable specifying a Security Policy ID for a Group's access. 
+
+In v2.x.x, the following was valid:
+
+```terraform
+resource "twingate_resource" "resource" {
+  name = "resource"
+  address = "internal.int"
+  remote_network_id = twingate_remote_network.aws_network.id
+
+  access {
+    group_ids = [twingate_group.aws.id]
+    service_account_ids = [twingate_service_account.github_actions_prod.id]
+  }
+}
+```
+
+From v3.0.0 and onward, access must be specified using the `access_group` and `access_service` blocks. Further, `access_group` can only be specified for a single group and no longer uses a list of group IDs.
+
+```terraform
+resource "twingate_resource" "resource" {
+  name = "resource"
+  address = "internal.int"
+  remote_network_id = twingate_remote_network.aws_network.id
+
+  // Group access is now assigned via the `access_group` block
+  // Further, security policies may now (optionally) be specified within
+  // an `access_group` block.
+  access_group {
+      security_policy_id = twingate_security_policy.no_mfa.id
+      group_id = data.twingate_groups.devops.id
+  }
+
+  // To assign access to multiple groups, use a `dynamic` block
+  dynamic access_group {
+    for_each = toset([twingate_groups.infra.id, twingate_groups.security.id])
+    content {
+      security_policy_id = twingate_security_policy.no_mfa.id
+      group_id = access.value.key
+    }
+  }
+
+  // Service accounts are now assigned via the `service_access` block
+  // Service accounts do not use policies and, as such, one cannot be specified
+  access_service {
+    service_account_id = twingate_service_account.github_actions_prod.id
+  }
+```
+