HVN route migration guide (#129)

* add note to changelog * update readme * add hvn route migration guide * id -> ID * bonus: fix error typo * go gen * add context to HVN route intro * update link in banner to registry migration guide * update changelog * update version in examples * add warning banner to hvn route doc
hashicorp · Jun 4, 2021 · 6073695 · 6073695
1 parent b2eb158
commit 6073695
Show file tree

Hide file tree

Showing 14 changed files with 379 additions and 9 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,19 @@
+## 0.7.0 (Unreleased)
+
+⚠️ Note: This version contains breaking changes to the `hcp_aws_transit_gateway_attachment` and `hcp_aws_network_peering` resources and data sources. Please pin to the previous version and follow [this migration guide](https://github.com/hashicorp/terraform-provider-hcp/pull/128) when you're ready to migrate. ⚠️
+
+FEATURES:
+* **New resource** `hcp_hvn_route` (#122)
+
+IMPROVEMENTS:
+* resource/hcp_aws_transit_gateway_attachment: released as Generally Available (#121)
+
+BREAKING CHANGES:
+* resource/hcp_aws_network_peering: now requires `peering_id` to be specified and doesn't accept `peer_vpc_cidr_block` as input (#128)
+* datasource/hcp_aws_network_peering: no longer returns `peer_vpc_cidr_block` as output (#128)
+* resource/hcp_aws_transit_gateway_attachment: doesn't accept `destination_cidrs` as input (#128)
+* datasource/hcp_aws_transit_gateway_attachment: no longer returns `destination_cidrs` as output (#128)
+
 ## 0.6.1 (June 03, 2021)
 
 IMPROVEMENTS:

diff --git a/README.md b/README.md
@@ -61,7 +61,14 @@ resource "hcp_aws_network_peering" "example" {
   peer_vpc_id         = aws_vpc.peer.id
   peer_account_id     = aws_vpc.peer.owner_id
   peer_vpc_region     = "us-west-2"
-  peer_vpc_cidr_block = aws_vpc.peer.cidr_block
+}
+
+// Create an HVN route that targets your HCP network peering and matches your AWS VPC's CIDR block.
+resource "hcp_hvn_route" "example" {
+  hvn_link         = hcp_hvn.hvn.self_link
+  hvn_route_id     = "peer-route-id"
+  destination_cidr = aws_vpc.peer.cidr_block
+  target_link      = hcp_aws_network_peering.example.self_link
 }
 
 // Accept the VPC peering within your AWS account.

diff --git a/docs/guides/hvn-route-migration-guide.md b/docs/guides/hvn-route-migration-guide.md
@@ -0,0 +1,162 @@
+---
+subcategory: ""
+page_title: "HVN Route Migration Guide - HCP Provider"
+description: |-
+    An guide to migrating HCP networking resources to use HVN routes.
+---
+
+# Introducing HVN routes
+
+The HVN route is a new resource that belongs to an HVN. It contains a CIDR block and targets a networking connection: 
+either a peering or transit gateway attachment.
+
+HVN routes provide a general view on how an HVN's traffic is routed across all networking connections and create a flexible way of managing these routing rules.
+
+## Migrating existing peerings and transit gateway attachments
+
+There are two ways to migrate existing peerings and transit gateway attachments managed by Terraform:
+
+ 1. Recreate Resources with Updated Schema
+    * This option is quicker but will result in downtime and possible data loss. Best for test environments. Will allow you to specify human-readable ids for the resources.
+    * Comment out all `hcp_aws_network_peering` and `hcp_aws_transit_gateway_attachment` resources.
+    * Run `terraform apply` to destroy currently existing connections.
+    * Uncomment and update all `hcp_aws_network_peering` and `hcp_aws_transit_gateway_attachment` resource definitions to match the new schema. 
+    * Add corresponding `hcp_hvn_route` resources for each CIDR targeting corresponding peering connections or transit gateway attachment.
+    * Run `terraform apply` to recreate connections.
+
+ 2. Re-Import with Updated Syntax:
+    * This option allows you to avoid downtime or data loss.
+    * Update any `hcp_aws_network_peering` and `hcp_aws_transit_gateway_attachment` resource definitions to match the new schema. All values needed can be found on the details pages of Peerings and TGW attachment in the HCP Portal.
+    * Add corresponding `hcp_hvn_route` resources for each CIDR targeting corresponding peering connections or transit gateway attachments.
+    * Run `terraform import hcp_hvn_route.<route-name> <hvn-id>:<hvn-route-id>` for each `hcp_hvn_route`. The `<hvn-route-id>` can be found on the details pages of the corresponding HVN connection in the HCP Portal.
+    * Run `terraform plan` and make sure that there are no changes detected by the Terraform.
+
+The examples below walk through the schema upgrade and re-import steps.
+
+### Peering example
+
+Given:
+```terraform
+resource "hcp_hvn" "hvn" {
+  hvn_id         = "prod-hvn"
+  region         = "us-west-2"
+  cloud_provider = "aws"
+}
+
+resource "hcp_aws_network_peering" "peering" {
+  hvn_id              = hcp_hvn.hvn.hvn_id
+  peer_vpc_id         = "vpc-845f29fc"
+  peer_account_id     = "572816266891"
+  peer_vpc_region     = "us-west-2"
+  peer_vpc_cidr_block = "172.31.0.0/16"
+}
+```
+
+Rewrite it to the new schema and add corresponding HVN route:
+```terraform
+resource "hcp_hvn" "hvn" {
+  hvn_id         = "prod-hvn"
+  region         = "us-west-2"
+  cloud_provider = "aws"
+}
+
+resource "hcp_aws_network_peering" "peering" {
+  hvn_id = hcp_hvn.hvn.hvn_id
+  // add `peering_id` that you can find in the HCP Portal
+  peering_id      = "f03324a9-4377-4a54-9c15-958fd07ad77b"
+  peer_vpc_id     = "vpc-845f29fc"
+  peer_account_id = "572816266891"
+  peer_vpc_region = "us-west-2"
+  // remove `peer_vpc_cidr_block`
+  // peer_vpc_cidr_block = "172.31.0.0/16"
+}
+
+// Add a `hcp_hvn_route` resource for the peering's CIDR
+resource "hcp_hvn_route" "peering-route" {
+  hvn_link = hcp_hvn.hvn.self_link
+  // you can find this ID in the HCP Portal in the peering details page in the list of routes
+  hvn_route_id     = "a8dda9a8-0f69-4fa0-b38c-55be302fdddb"
+  destination_cidr = "172.31.0.0/16"
+  target_link      = hcp_aws_network_peering.peering.self_link
+}
+```
+
+Run `import` for the `hcp_hvn_route`:
+```shell
+$ terraform import hcp_hvn_route.peering-route prod-hvn:a8dda9a8-0f69-4fa0-b38c-55be302fdddb
+```
+
+Run `terraform plan` to make sure there are no changes detected by the Terraform:
+```shell
+$ terraform plan
+No changes. Infrastructure is up-to-date.
+```
+
+### Transit gateway attachment example
+
+Given:
+```terraform
+resource "hcp_hvn" "hvn" {
+  hvn_id         = "prod-hvn"
+  region         = "us-west-2"
+  cloud_provider = "aws"
+}
+
+resource "hcp_aws_transit_gateway_attachment" "prod" {
+  hvn_id                        = hcp_hvn.hvn.hvn_id
+  transit_gateway_attachment_id = "prod-tgw-attachment"
+  transit_gateway_id            = "tgw-0ee94b1a1167cf89d"
+  resource_share_arn            = "arn:aws:ram:us-west-2:..."
+  destination_cidrs             = ["10.1.0.0/24", "10.2.0.0/24"]
+}
+```
+
+Rewrite it to the new schema and add corresponding HVN route:
+```terraform
+resource "hcp_hvn" "hvn" {
+  hvn_id         = "prod-hvn"
+  region         = "us-west-2"
+  cloud_provider = "aws"
+}
+
+resource "hcp_aws_transit_gateway_attachment" "prod" {
+  hvn_id                        = hcp_hvn.hvn.hvn_id
+  transit_gateway_attachment_id = "prod-tgw-attachment"
+  transit_gateway_id            = "tgw-0ee94b1a1167cf89d"
+  resource_share_arn            = "arn:aws:ram:us-west-2:..."
+  // remove `destination_cidrs`
+  // destination_cidrs             = ["10.1.0.0/24", "10.2.0.0/24"]
+}
+
+// add a new `hcp_hvn_route` for each CIDR associated with the transit gateway attachment
+resource "hcp_hvn_route" "tgw-route-1" {
+  hvn_link = hcp_hvn.hvn.self_link
+  // you can find this ID in the HCP Portal in the TGW attachment details page in the list of Routes
+  hvn_route_id     = "35392425-215a-44ec-bbd0-051bb777ce5f"
+  destination_cidr = "10.1.0.0/24"
+  target_link      = hcp_aws_transit_gateway_attachment.prod.self_link
+}
+
+resource "hcp_hvn_route" "tgw-route-2" {
+  hvn_link = hcp_hvn.hvn.self_link
+  // you can find this ID in the HCP Portal in the transit gateway attachment details page in the list of routes
+  hvn_route_id     = "9867959a-d81b-4e52-ae8e-ca56f9dd06fc"
+  destination_cidr = "10.2.0.0/24"
+  target_link      = hcp_aws_transit_gateway_attachment.prod.self_link
+}
+```
+
+Run `import` for each `hcp_hvn_route` you've added:
+```shell
+$ terraform import hcp_hvn_route.tgw-route-1 prod-hvn:35392425-215a-44ec-bbd0-051bb777ce5f
+...
+
+$ terraform import hcp_hvn_route.tgw-route-2 prod-hvn:9867959a-d81b-4e52-ae8e-ca56f9dd06fc
+...
+```
+
+Run `terraform plan` to make sure there are no changes detected by the Terraform:
+```shell
+$ terraform plan
+No changes. Infrastructure is up-to-date.
+```
diff --git a/docs/index.md b/docs/index.md
@@ -9,8 +9,8 @@ description: |-
 
 The HCP provider provides resources to manage [HashiCorp Cloud Platform](https://cloud.hashicorp.com/) (HCP) resources.
 
-~> **Upcoming Migration:** The upcoming release of HVN Routes will include breaking changes that affect `hcp_aws_network_peering` and `hcp_aws_transit_gateway_attachment`. [This PR](https://github.com/hashicorp/terraform-provider-hcp/pull/128) contains a migration guide.
-Please pin to the current version to avoid disruption until you are ready to migrate.
+~> **Upcoming Migration:** The upcoming release of HVN Routes in v0.7.0 will include breaking changes that affect `hcp_aws_network_peering` and `hcp_aws_transit_gateway_attachment`. [This guide](https://registry.terraform.io/providers/hashicorp/hcp/latest/docs/guides/hvn-route-migration-guide) walks through how to migrate to the new resource syntax.
+Please pin to the previous version to avoid disruption until you are ready to migrate.
 
 -> **Note:** Please refer to the provider's [Release Notes](https://github.com/hashicorp/terraform-provider-hcp/releases) for critical fixes.
 
@@ -37,7 +37,7 @@ terraform {
   required_providers {
     hcp = {
       source  = "hashicorp/hcp"
-      version = "~> 0.6.0"
+      version = "~> 0.7.0"
     }
   }
 }

diff --git a/docs/resources/hvn_route.md b/docs/resources/hvn_route.md
@@ -1,5 +1,4 @@
 ---
-# generated by https://github.com/hashicorp/terraform-plugin-docs
 page_title: "hcp_hvn_route Resource - terraform-provider-hcp"
 subcategory: ""
 description: |-
@@ -8,6 +7,9 @@ description: |-
 
 # hcp_hvn_route (Resource)
 
+~> **Migration Required:** The release of HVN Routes in v0.7.0 includes breaking changes that affect `hcp_aws_network_peering` and `hcp_aws_transit_gateway_attachment`. [This guide](https://registry.terraform.io/providers/hashicorp/hcp/latest/docs/guides/hvn-route-migration-guide) walks through how to migrate to the new resource syntax.
+Please pin to the previous version to avoid disruption until you are ready to migrate.
+
 The HVN route resource allows you to manage an HVN route.
 
 ## Example Usage

diff --git a/examples/guides/hvn_route_migration_guide/after-peering.tf b/examples/guides/hvn_route_migration_guide/after-peering.tf
@@ -0,0 +1,25 @@
+resource "hcp_hvn" "hvn" {
+  hvn_id         = "prod-hvn"
+  region         = "us-west-2"
+  cloud_provider = "aws"
+}
+
+resource "hcp_aws_network_peering" "peering" {
+  hvn_id = hcp_hvn.hvn.hvn_id
+  // add `peering_id` that you can find in the HCP Portal
+  peering_id      = "f03324a9-4377-4a54-9c15-958fd07ad77b"
+  peer_vpc_id     = "vpc-845f29fc"
+  peer_account_id = "572816266891"
+  peer_vpc_region = "us-west-2"
+  // remove `peer_vpc_cidr_block`
+  // peer_vpc_cidr_block = "172.31.0.0/16"
+}
+
+// Add a `hcp_hvn_route` resource for the peering's CIDR
+resource "hcp_hvn_route" "peering-route" {
+  hvn_link = hcp_hvn.hvn.self_link
+  // you can find this ID in the HCP Portal in the peering details page in the list of routes
+  hvn_route_id     = "a8dda9a8-0f69-4fa0-b38c-55be302fdddb"
+  destination_cidr = "172.31.0.0/16"
+  target_link      = hcp_aws_network_peering.peering.self_link
+}
diff --git a/examples/guides/hvn_route_migration_guide/after-tgw.tf b/examples/guides/hvn_route_migration_guide/after-tgw.tf
@@ -0,0 +1,31 @@
+resource "hcp_hvn" "hvn" {
+  hvn_id         = "prod-hvn"
+  region         = "us-west-2"
+  cloud_provider = "aws"
+}
+
+resource "hcp_aws_transit_gateway_attachment" "prod" {
+  hvn_id                        = hcp_hvn.hvn.hvn_id
+  transit_gateway_attachment_id = "prod-tgw-attachment"
+  transit_gateway_id            = "tgw-0ee94b1a1167cf89d"
+  resource_share_arn            = "arn:aws:ram:us-west-2:..."
+  // remove `destination_cidrs`
+  // destination_cidrs             = ["10.1.0.0/24", "10.2.0.0/24"]
+}
+
+// add a new `hcp_hvn_route` for each CIDR associated with the transit gateway attachment
+resource "hcp_hvn_route" "tgw-route-1" {
+  hvn_link = hcp_hvn.hvn.self_link
+  // you can find this ID in the HCP Portal in the TGW attachment details page in the list of Routes
+  hvn_route_id     = "35392425-215a-44ec-bbd0-051bb777ce5f"
+  destination_cidr = "10.1.0.0/24"
+  target_link      = hcp_aws_transit_gateway_attachment.prod.self_link
+}
+
+resource "hcp_hvn_route" "tgw-route-2" {
+  hvn_link = hcp_hvn.hvn.self_link
+  // you can find this ID in the HCP Portal in the transit gateway attachment details page in the list of routes
+  hvn_route_id     = "9867959a-d81b-4e52-ae8e-ca56f9dd06fc"
+  destination_cidr = "10.2.0.0/24"
+  target_link      = hcp_aws_transit_gateway_attachment.prod.self_link
+}
diff --git a/examples/guides/hvn_route_migration_guide/before-peering.tf b/examples/guides/hvn_route_migration_guide/before-peering.tf
@@ -0,0 +1,13 @@
+resource "hcp_hvn" "hvn" {
+  hvn_id         = "prod-hvn"
+  region         = "us-west-2"
+  cloud_provider = "aws"
+}
+
+resource "hcp_aws_network_peering" "peering" {
+  hvn_id              = hcp_hvn.hvn.hvn_id
+  peer_vpc_id         = "vpc-845f29fc"
+  peer_account_id     = "572816266891"
+  peer_vpc_region     = "us-west-2"
+  peer_vpc_cidr_block = "172.31.0.0/16"
+}
diff --git a/examples/guides/hvn_route_migration_guide/before-tgw.tf b/examples/guides/hvn_route_migration_guide/before-tgw.tf
@@ -0,0 +1,13 @@
+resource "hcp_hvn" "hvn" {
+  hvn_id         = "prod-hvn"
+  region         = "us-west-2"
+  cloud_provider = "aws"
+}
+
+resource "hcp_aws_transit_gateway_attachment" "prod" {
+  hvn_id                        = hcp_hvn.hvn.hvn_id
+  transit_gateway_attachment_id = "prod-tgw-attachment"
+  transit_gateway_id            = "tgw-0ee94b1a1167cf89d"
+  resource_share_arn            = "arn:aws:ram:us-west-2:..."
+  destination_cidrs             = ["10.1.0.0/24", "10.2.0.0/24"]
+}
diff --git a/examples/provider/provider.tf b/examples/provider/provider.tf
@@ -3,7 +3,7 @@ terraform {
   required_providers {
     hcp = {
       source  = "hashicorp/hcp"
-      version = "~> 0.6.0"
+      version = "~> 0.7.0"
     }
   }
 }

diff --git a/internal/provider/resource_hvn.go b/internal/provider/resource_hvn.go
@@ -132,7 +132,7 @@ func resourceHvnCreate(ctx context.Context, d *schema.ResourceData, meta interfa
 
 		log.Printf("[INFO] HVN (%s) not found, proceeding with create", hvnID)
 	} else {
-		return diag.Errorf("unable to create HVN (%s) - an HVN with this ID already exists; see resouce documentation for hcp_hvn for instructions on how to add an already existing HVN to the state", hvnID)
+		return diag.Errorf("unable to create HVN (%s) - an HVN with this ID already exists; see resource documentation for hcp_hvn for instructions on how to add an already existing HVN to the state", hvnID)
 	}
 
 	createNetworkParams := network_service.NewCreateParams()