HCPE-1198: add CIDR guidance to HVN resource documentation (#160)

* add cidr guidance to HVN resource documentation * add guidance about allowed address space * add guidance on using first IP address of block * rearrange order to place overlap rules after cidr validity rules * bonus: remove migration banner
hashicorp · Jul 8, 2021 · 74b73af · 74b73af
1 parent 1cb9360
commit 74b73af
Show file tree

Hide file tree

Showing 4 changed files with 46 additions and 7 deletions.
diff --git a/docs/index.md b/docs/index.md
@@ -9,9 +9,6 @@ description: |-
 
 The HCP provider provides resources to manage [HashiCorp Cloud Platform](https://cloud.hashicorp.com/) (HCP) resources.
 
-~> **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.
-
 -> **Note:** Please refer to the provider's [Release Notes](https://github.com/hashicorp/terraform-provider-hcp/releases) for critical fixes.
 
 ## Authenticating with HCP

diff --git a/docs/resources/hvn.md b/docs/resources/hvn.md
@@ -1,5 +1,4 @@
 ---
-# generated by https://github.com/hashicorp/terraform-plugin-docs
 page_title: "hcp_hvn Resource - terraform-provider-hcp"
 subcategory: ""
 description: |-
@@ -10,6 +9,18 @@ description: |-
 
 The HVN resource allows you to manage a HashiCorp Virtual Network in HCP.
 
+We recommend the following when selecting the CIDR block of an HVN:
+
+- The CIDR block value must be a private IPv4 CIDR block within the [RFC1918](https://datatracker.ietf.org/doc/html/rfc1918) address space (10.*.*.*, 192.168.*.*, 172.[16-31].*.*).
+
+- The CIDR block value must be the first IP address of the desired CIDR block. The helper `cidrsubnet("172.16.1.1/24", 0, 0)` will specify the first address of the CIDR block in the first argument.
+
+- The CIDR block value must end between /16 and /25.
+
+- If the CIDR block values for your HVN and VPCs overlap, then you will not be able to establish a connection. Ensure that any VPCs you plan to connect do not have overlapping values.
+
+- The default HVN CIDR block value does not overlap with the default CIDR block value for AWS VPCs (172.31.0.0/16). However, if you are planning to use this HVN in production, we recommend adding a custom value instead of using the default.
+
 ## Example Usage
 
 ```terraform

diff --git a/templates/index.md.tmpl b/templates/index.md.tmpl
@@ -9,9 +9,6 @@ description: |-
 
 The HCP provider provides resources to manage [HashiCorp Cloud Platform](https://cloud.hashicorp.com/) (HCP) resources.
 
-~> **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.
-
 -> **Note:** Please refer to the provider's [Release Notes](https://github.com/hashicorp/terraform-provider-hcp/releases) for critical fixes.
 
 ## Authenticating with HCP

diff --git a/templates/resources/hvn.md.tmpl b/templates/resources/hvn.md.tmpl
@@ -0,0 +1,34 @@
+---
+page_title: "{{.Type}} {{.Name}} - {{.ProviderName}}"
+subcategory: ""
+description: |-
+{{ .Description | plainmarkdown | trimspace | prefixlines "  " }}
+---
+
+# {{.Type}} ({{.Name}})
+
+{{ .Description | trimspace }}
+
+We recommend the following when selecting the CIDR block of an HVN:
+
+- The CIDR block value must be a private IPv4 CIDR block within the [RFC1918](https://datatracker.ietf.org/doc/html/rfc1918) address space (10.*.*.*, 192.168.*.*, 172.[16-31].*.*).
+
+- The CIDR block value must be the first IP address of the desired CIDR block. The helper `cidrsubnet("172.16.1.1/24", 0, 0)` will specify the first address of the CIDR block in the first argument.
+
+- The CIDR block value must end between /16 and /25.
+
+- If the CIDR block values for your HVN and VPCs overlap, then you will not be able to establish a connection. Ensure that any VPCs you plan to connect do not have overlapping values.
+
+- The default HVN CIDR block value does not overlap with the default CIDR block value for AWS VPCs (172.31.0.0/16). However, if you are planning to use this HVN in production, we recommend adding a custom value instead of using the default.
+
+## Example Usage
+
+{{ tffile "examples/resources/hcp_hvn/resource.tf" }}
+
+{{ .SchemaMarkdown | trimspace }}
+
+## Import
+
+Import is supported using the following syntax:
+
+{{ codefile "shell" "examples/resources/hcp_hvn/import.sh" }}