From 4dcfe2cbd91862c28dd6593f94af96fcc3320e40 Mon Sep 17 00:00:00 2001 From: alexb-twingate <110070580+alexb-twingate@users.noreply.github.com> Date: Thu, 18 Apr 2024 08:58:11 -0700 Subject: [PATCH] [Docs] Adding v2 to v3 migration guide (#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 Co-authored-by: bertekintw <101608051+bertekintw@users.noreply.github.com> --- docs/guides/aws-deployment-guide.md | 3 +- .../gke-helm-provider-deployment-guide.md | 3 +- docs/guides/migration-v1-to-v2-guide.md | 3 +- docs/guides/migration-v2-to-v3-guide.md | 63 +++++++++++++++++++ templates/guides/aws-deployment-guide.md.tmpl | 3 +- ...gke-helm-provider-deployment-guide.md.tmpl | 3 +- .../guides/migration-v1-to-v2-guide.md.tmpl | 3 +- .../guides/migration-v2-to-v3-guide.md.tmpl | 63 +++++++++++++++++++ 8 files changed, 132 insertions(+), 12 deletions(-) create mode 100644 docs/guides/migration-v2-to-v3-guide.md create mode 100644 templates/guides/migration-v2-to-v3-guide.md.tmpl diff --git a/docs/guides/aws-deployment-guide.md b/docs/guides/aws-deployment-guide.md index 4c228cce..50c4b918 100644 --- 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 index 441d7e06..5d3427a0 100644 --- 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 index fbecac4a..6f855e1e 100644 --- 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 new file mode 100644 index 00000000..680cb8b5 --- /dev/null +++ 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 index 3aa84a10..f72063b2 100644 --- 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 index 441d7e06..5d3427a0 100644 --- 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 index fbecac4a..6f855e1e 100644 --- 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 new file mode 100644 index 00000000..680cb8b5 --- /dev/null +++ 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 + } +``` +