Update Contributor Docs and Resource-Specific Import Examples to Reflect Multi-Project Support

.changelog/517.txt

@@ -0,0 +1,3 @@
+```release-note:improvement
+Documentation: Update contributor documentation and resource-specific import examples to reflect multi-project support.
+```

contributing/README.md

@@ -62,7 +62,7 @@ $ go generate
 
 ## Changelogs
 
-This repo requires that a chagnelog file be added in all pull requests. The name of the file must follow `[PR #].txt` and must reside in the `.changelog` directory. The contents must have the following formatting:
+This repo requires that a changelog file be added in all pull requests. The name of the file must follow `[PR #].txt` and must reside in the `.changelog` directory. The contents must have the following formatting:
 
 ~~~
 ```release-note:TYPE

contributing/checklist-resource-import.md

@@ -5,7 +5,7 @@ Adding import support for Terraform resources will allow existing infrastructure
 Comprehensive code examples and information about resource import support can be found in the [Extending Terraform documentation](https://www.terraform.io/docs/extend/resources/import.html).
 
 - [ ] __Uses Context-Aware Import Function__: The context-aware `StateContext` function should be used over the deprecated `State` function.
-- [ ] __Does Not Use Project ID In Import Identifier__: There should not be a project ID present in the import identifier. Instead of the user providing a project ID explicitly, the provider uses the authentication scope to determine which project is accessible. This prevents the user from needing to locate and provide their project ID. `client.Config.ProjectID` should be used to retrieve the implied project ID.
+- [ ] __Supports Optional Project ID In Import Identifier__: If the resource has multi-project support, there should be an optional `{project_id}:` prefix for the import identifier. If the user does not provide a project ID explicitly, `client.Config.ProjectID` should be used to retrieve the implied project ID from the provider. The user may provide a `project_id` to the provider, otherwise the provider uses the authentication scope to determine the oldest accessible project. This prevents the user from needing to locate and provide their project ID for single-project organizations.
 - [ ] __Uses Passthrough If Possible__: If the import identifier can match the `id` of the resource, and this does not violate any other guidelines, the `ImportStatePassthroughContext` passthrough should be used.
 - [ ] __Specifies Minimal Import Identifier__: If more than one value needs to be specified in the import identifier, the minimal number of values should be used, and those values should be colon (`:`) separated.
 - [ ] __Includes Import Documentation__: There should be an import example at `examples/resources/<resource>/import.sh`, which will be used when generating the docs. The docs should then be regenerated using `go generate`, which will update files in the `docs/` directory.

contributing/checklist-resource.md

@@ -12,7 +12,7 @@ Implementing a new resource is a good way to learn more about how Terraform inte
 - [ ] __Uses Globally Unique ID__: The `id` field needs to be globally unique. Since many of the HCP services use IDs that are only unique within a particular project, you may need to create an `id` for Terraform using the `linkURL()` helper function. This function will produce an `id` of the following format: `/project/<project_id>/<resource_type>/<resource_id>`. If the service uses `ID` for a resource ID that is not globally unique, the resource ID should be specified in the Terraform schema as `<resource_type>_id`.
 - [ ] __Validates Fields Where Possible__: All fields that can be validated client-side should include a `ValidateFunc` or `ValidateDiagFunc`.
 These validations should favor validators provided by this project, or [Terraform `helper/validation` package](https://godoc.org/github.com/hashicorp/terraform/helper/validation) functions.
-- [ ] __Does Not Use Project ID Input__: There should not be an input field for `project_id` in the schema. Instead of the user providing a `project_id` explicitly, the provider uses the authentication scope to determine which project is accessible. This prevents the user from needing to locate and provide their project ID. `client.Config.ProjectID` should be used to retrieve the implied project ID.
+- [ ] __Supports Optional Project ID Input__: If the resource has multi-project support, there should be an optional input field for `project_id` in the schema. If the user does not provide a `project_id` for the resource, `client.Config.ProjectID` should be used to retrieve the implied project ID from the provider. The user may provide a `project_id` to the provider, otherwise the provider uses the authentication scope to determine the oldest accessible project. This prevents the user from needing to locate and provide their project ID for single-project organizations.
 
 ## CRUD Operations
 

docs/resources/aws_network_peering.md

@@ -93,6 +93,10 @@ Optional:
 Import is supported using the following syntax:
 
 ```shell
-# The import ID is {hvn_id}:{peering_id}
+# Using an explicit project ID, the import ID is:
+# {project_id}:{hvn_id}:{peering_id}
+terraform import hcp_aws_network_peering.peer f709ec73-55d4-46d8-897d-816ebba28778:main-hvn:11eb60b3-d4ec-5eed-aacc-0242ac120015
+# Using the provider-default project ID, the import ID is:
+# {hvn_id}:{peering_id}
 terraform import hcp_aws_network_peering.peer main-hvn:11eb60b3-d4ec-5eed-aacc-0242ac120015
 ```

docs/resources/aws_transit_gateway_attachment.md

@@ -115,6 +115,10 @@ Optional:
 Import is supported using the following syntax:
 
 ```shell
-# The import ID is {hvn_id}:{transit_gateway_attachment_id}
+# Using an explicit project ID, the import ID is:
+# {project_id}:{hvn_id}:{transit_gateway_attachment_id}
+terraform import hcp_aws_transit_gateway_attachment.example f709ec73-55d4-46d8-897d-816ebba28778:main-hvn:example-tgw-attachment
+# Using the provider-default project ID, the import ID is:
+# {hvn_id}:{transit_gateway_attachment_id}
 terraform import hcp_aws_transit_gateway_attachment.example main-hvn:example-tgw-attachment
 ```

docs/resources/azure_peering_connection.md

@@ -142,6 +142,10 @@ Optional:
 Import is supported using the following syntax:
 
 ```shell
-# The import ID is {hvn_id}:{peering_id}
+# Using an explicit project ID, the import ID is:
+# {project_id}:{hvn_id}:{peering_id}
+terraform import hcp_azure_peering_connection.peer f709ec73-55d4-46d8-897d-816ebba28778:main-hvn:199e7e96-4d5f-4456-91f3-b6cc71f1e561
+# Using the provider-default project ID, the import ID is:
+# {hvn_id}:{peering_id}
 terraform import hcp_azure_peering_connection.peer main-hvn:199e7e96-4d5f-4456-91f3-b6cc71f1e561
 ```

docs/resources/boundary_cluster.md

@@ -73,6 +73,10 @@ Optional:
 Import is supported using the following syntax:
 
 ```shell
-# The import ID is {cluster_id}
+# Using an explicit project ID, the import ID is:
+# {project_id}:{cluster_id}
+terraform import hcp_boundary_cluster.example f709ec73-55d4-46d8-897d-816ebba28778:boundary-cluster
+# Using the provider-default project ID, the import ID is:
+# {cluster_id}
 terraform import hcp_boundary_cluster.example boundary-cluster
 ```

docs/resources/consul_cluster.md

@@ -96,6 +96,10 @@ Optional:
 Import is supported using the following syntax:
 
 ```shell
-# The import ID is {cluster_id}
+# Using an explicit project ID, the import ID is:
+# {project_id}:{cluster_id}
+terraform import hcp_consul_cluster.example f709ec73-55d4-46d8-897d-816ebba28778:consul-cluster
+# Using the provider-default project ID, the import ID is:
+# {cluster_id}
 terraform import hcp_consul_cluster.example consul-cluster
 ```

docs/resources/hvn.md

@@ -70,6 +70,10 @@ Optional:
 Import is supported using the following syntax:
 
 ```shell
-# The import ID is {hvn_id}
+# Using an explicit project ID, the import ID is:
+# {project_id}:{hvn_id}
+terraform import hcp_hvn.example f709ec73-55d4-46d8-897d-816ebba28778:main-hvn
+# Using the provider-default project ID, the import ID is:
+# {hvn_id}
 terraform import hcp_hvn.example main-hvn
 ```

docs/resources/hvn_peering_connection.md

@@ -70,6 +70,12 @@ Optional:
 Import is supported using the following syntax:
 
 ```shell
-# The import ID requires the first HVN ID in the format {hvn_1_id}:{peering_id}
+# Only the first HVN ID is required (hvn_1_id), HVN 2 will be populated after import.
+
+# Using an explicit project ID, the import ID is:
+# {project_id}:{hvn_1_id}:{peering_id}
+terraform import hcp_hvn_peering_connection.peer_1 f709ec73-55d4-46d8-897d-816ebba28778:hvn-1:peer-1
+# Using the provider-default project ID, the import ID is:
+# {hvn_1_id}:{peering_id}
 terraform import hcp_hvn_peering_connection.peer_1 hvn-1:peer-1
 ```

docs/resources/hvn_route.md

@@ -91,6 +91,10 @@ Optional:
 Import is supported using the following syntax:
 
 ```shell
-# The import ID is {hvn_id}:{hvn_route_id}
+# Using an explicit project ID, the import ID is:
+# {project_id}:{hvn_id}:{hvn_route_id}
+terraform import hcp_hvn_route.example f709ec73-55d4-46d8-897d-816ebba28778:main-hvn:example-hvn-route
+# Using the provider-default project ID, the import ID is:
+# {hvn_id}:{hvn_route_id}
 terraform import hcp_hvn_route.example main-hvn:example-hvn-route
 ```

docs/resources/packer_channel.md

@@ -113,6 +113,10 @@ Optional:
 Import is supported using the following syntax:
 
 ```shell
-# The import ID requires the bucket and channel name in the following format {bucket_name}:{name}
+# Using an explicit project ID, the import ID is:
+# {project_id}:{bucket_name}:{channel_name}
+terraform import hcp_packer_channel.staging f709ec73-55d4-46d8-897d-816ebba28778:alpine:staging
+# Using the provider-default project ID, the import ID is:
+# {bucket_name}:{channel_name}
 terraform import hcp_packer_channel.staging alpine:staging
 ```

docs/resources/vault_cluster.md

@@ -132,7 +132,11 @@ Optional:
 Import is supported using the following syntax:
 
 ```shell
-# The import ID is {cluster_id}
+# Using an explicit project ID, the import ID is:
+# {project_id}:{cluster_id}
+terraform import hcp_vault_cluster.example f709ec73-55d4-46d8-897d-816ebba28778:vault-cluster
+# Using the provider-default project ID, the import ID is:
+# {cluster_id}
 terraform import hcp_vault_cluster.example vault-cluster
 ```
 

examples/resources/hcp_aws_network_peering/import.sh

@@ -1,2 +1,6 @@
-# The import ID is {hvn_id}:{peering_id}
+# Using an explicit project ID, the import ID is:
+# {project_id}:{hvn_id}:{peering_id}
+terraform import hcp_aws_network_peering.peer f709ec73-55d4-46d8-897d-816ebba28778:main-hvn:11eb60b3-d4ec-5eed-aacc-0242ac120015
+# Using the provider-default project ID, the import ID is:
+# {hvn_id}:{peering_id}
 terraform import hcp_aws_network_peering.peer main-hvn:11eb60b3-d4ec-5eed-aacc-0242ac120015

examples/resources/hcp_aws_transit_gateway_attachment/import.sh

@@ -1,2 +1,6 @@
-# The import ID is {hvn_id}:{transit_gateway_attachment_id}
+# Using an explicit project ID, the import ID is:
+# {project_id}:{hvn_id}:{transit_gateway_attachment_id}
+terraform import hcp_aws_transit_gateway_attachment.example f709ec73-55d4-46d8-897d-816ebba28778:main-hvn:example-tgw-attachment
+# Using the provider-default project ID, the import ID is:
+# {hvn_id}:{transit_gateway_attachment_id}
 terraform import hcp_aws_transit_gateway_attachment.example main-hvn:example-tgw-attachment

examples/resources/hcp_azure_peering_connection/import.sh

@@ -1,2 +1,6 @@
-# The import ID is {hvn_id}:{peering_id}
-terraform import hcp_azure_peering_connection.peer main-hvn:199e7e96-4d5f-4456-91f3-b6cc71f1e561
+# Using an explicit project ID, the import ID is:
+# {project_id}:{hvn_id}:{peering_id}
+terraform import hcp_azure_peering_connection.peer f709ec73-55d4-46d8-897d-816ebba28778:main-hvn:199e7e96-4d5f-4456-91f3-b6cc71f1e561
+# Using the provider-default project ID, the import ID is:
+# {hvn_id}:{peering_id}
+terraform import hcp_azure_peering_connection.peer main-hvn:199e7e96-4d5f-4456-91f3-b6cc71f1e561

examples/resources/hcp_boundary_cluster/import.sh

@@ -1,2 +1,6 @@
-# The import ID is {cluster_id}
-terraform import hcp_boundary_cluster.example boundary-cluster
+# Using an explicit project ID, the import ID is:
+# {project_id}:{cluster_id}
+terraform import hcp_boundary_cluster.example f709ec73-55d4-46d8-897d-816ebba28778:boundary-cluster
+# Using the provider-default project ID, the import ID is:
+# {cluster_id}
+terraform import hcp_boundary_cluster.example boundary-cluster

examples/resources/hcp_consul_cluster/import.sh

@@ -1,2 +1,6 @@
-# The import ID is {cluster_id}
-terraform import hcp_consul_cluster.example consul-cluster
+# Using an explicit project ID, the import ID is:
+# {project_id}:{cluster_id}
+terraform import hcp_consul_cluster.example f709ec73-55d4-46d8-897d-816ebba28778:consul-cluster
+# Using the provider-default project ID, the import ID is:
+# {cluster_id}
+terraform import hcp_consul_cluster.example consul-cluster

examples/resources/hcp_hvn/import.sh

@@ -1,2 +1,6 @@
-# The import ID is {hvn_id}
+# Using an explicit project ID, the import ID is:
+# {project_id}:{hvn_id}
+terraform import hcp_hvn.example f709ec73-55d4-46d8-897d-816ebba28778:main-hvn
+# Using the provider-default project ID, the import ID is:
+# {hvn_id}
 terraform import hcp_hvn.example main-hvn

examples/resources/hcp_hvn_peering_connection/import.sh

@@ -1,2 +1,8 @@
-# The import ID requires the first HVN ID in the format {hvn_1_id}:{peering_id}
+# Only the first HVN ID is required (hvn_1_id), HVN 2 will be populated after import.
+
+# Using an explicit project ID, the import ID is:
+# {project_id}:{hvn_1_id}:{peering_id}
+terraform import hcp_hvn_peering_connection.peer_1 f709ec73-55d4-46d8-897d-816ebba28778:hvn-1:peer-1
+# Using the provider-default project ID, the import ID is:
+# {hvn_1_id}:{peering_id}
 terraform import hcp_hvn_peering_connection.peer_1 hvn-1:peer-1

examples/resources/hcp_hvn_route/import.sh

@@ -1,2 +1,6 @@
-# The import ID is {hvn_id}:{hvn_route_id}
+# Using an explicit project ID, the import ID is:
+# {project_id}:{hvn_id}:{hvn_route_id}
+terraform import hcp_hvn_route.example f709ec73-55d4-46d8-897d-816ebba28778:main-hvn:example-hvn-route
+# Using the provider-default project ID, the import ID is:
+# {hvn_id}:{hvn_route_id}
 terraform import hcp_hvn_route.example main-hvn:example-hvn-route

examples/resources/hcp_packer_channel/import.sh

@@ -1,2 +1,6 @@
-# The import ID requires the bucket and channel name in the following format {bucket_name}:{name}
+# Using an explicit project ID, the import ID is:
+# {project_id}:{bucket_name}:{channel_name}
+terraform import hcp_packer_channel.staging f709ec73-55d4-46d8-897d-816ebba28778:alpine:staging
+# Using the provider-default project ID, the import ID is:
+# {bucket_name}:{channel_name}
 terraform import hcp_packer_channel.staging alpine:staging

examples/resources/hcp_vault_cluster/import.sh

@@ -1,2 +1,6 @@
-# The import ID is {cluster_id}
-terraform import hcp_vault_cluster.example vault-cluster
+# Using an explicit project ID, the import ID is:
+# {project_id}:{cluster_id}
+terraform import hcp_vault_cluster.example f709ec73-55d4-46d8-897d-816ebba28778:vault-cluster
+# Using the provider-default project ID, the import ID is:
+# {cluster_id}
+terraform import hcp_vault_cluster.example vault-cluster

internal/provider/resource_hvn_peering_connection.go

@@ -271,9 +271,9 @@ func resourceHvnPeeringConnectionDelete(ctx context.Context, d *schema.ResourceD
 func resourceHvnPeeringConnectionImport(ctx context.Context, d *schema.ResourceData, meta interface{}) ([]*schema.ResourceData, error) {
 	// with multi-projects, import arguments must become dynamic:
 	// use explicit project ID with terraform import:
-	//   terraform import hcp_hvn_peering_connection.test {project_id}:{hvn_id}:{peering_id}
+	//   terraform import hcp_hvn_peering_connection.test {project_id}:{hvn_1_id}:{peering_id}
 	// use default project ID from provider:
-	//   terraform import hcp_hvn_peering_connection.test {hvn_id}:{peering_id}
+	//   terraform import hcp_hvn_peering_connection.test {hvn_1_id}:{peering_id}
 
 	client := meta.(*clients.Client)
 	projectID, hvnID, peeringID, err := parsePeeringResourceID(d.Id(), client.Config.ProjectID)