Update Contributor Docs and Resource-Specific Import Examples to Reflect Multi-Project Support (#517)

* Update contributing docs for multi-project support

* Update individual resource docs to reflect multi-project support

* Regenerate docs with `make gencheck`

* Adjust checklist wording

* Add changelog for PR

* Remove redundant custom schema

* Update packer_image_iteration docs

Author: aidan-mundy

.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/data-sources/packer_image_iteration.md

@@ -1,5 +1,5 @@
 ---
-page_title: "Data Source hcp_packer_image_iteration - terraform-provider-hcp"
+page_title: "hcp_packer_image_iteration Data Source - terraform-provider-hcp"
 subcategory: ""
 description: |-
   The Packer Image data source iteration gets the most recent iteration (or build) of an image, given a channel.
@@ -22,51 +22,52 @@ data "hcp_packer_image_iteration" "alpine" {
 
 ### Required
 
-- **bucket_name** (String) The slug of the HCP Packer Registry image bucket to pull from.
-- **channel** (String) The channel that points to the version of the image you want.
+- `bucket_name` (String) The slug of the HCP Packer Registry image bucket to pull from.
+- `channel` (String) The channel that points to the version of the image you want.
 
 ### Optional
 
-- **id** (String) The ID of this resource.
-- **timeouts** (Block, Optional) (see [below for nested schema](#nestedblock--timeouts))
+- `project_id` (String) The ID of the HCP project where the HCP Packer registry is located.
+- `timeouts` (Block, Optional) (see [below for nested schema](#nestedblock--timeouts))
 
 ### Read-Only
 
-- **builds** (List of Object) Builds for this iteration. An iteration can have more than one build if it took more than one go to build all images. (see [below for nested schema](#nestedatt--builds))
-- **created_at** (String) Creation time of this iteration
-- **incremental_version** (Number) Incremental version of this iteration
-- **organization_id** (String) The ID of the organization this HCP Packer registry is located in.
-- **project_id** (String) The ID of the project this HCP Packer registry is located in.
+- `builds` (List of Object) Builds for this iteration. An iteration can have more than one build if it took more than one go to build all images. (see [below for nested schema](#nestedatt--builds))
+- `created_at` (String) Creation time of this iteration
+- `id` (String) The ID of this resource.
+- `incremental_version` (Number) Incremental version of this iteration
+- `organization_id` (String) The ID of the organization this HCP Packer registry is located in.
+- `revoke_at` (String) The revocation time of this iteration. This field will be null for any iteration that has not been revoked or scheduled for revocation.
 
 <a id="nestedblock--timeouts"></a>
 ### Nested Schema for `timeouts`
 
 Optional:
 
-- **default** (String)
+- `default` (String)
 
 
 <a id="nestedatt--builds"></a>
 ### Nested Schema for `builds`
 
 Read-Only:
 
-- **cloud_provider** (String) Name of the cloud provider this image is stored-in, if any.
-- **component_type** (String) Name of the builder that built this. Ex: 'amazon-ebs.example'.
-- **created_at** (String) Creation time of this build.
-- **id** (String) HCP ID of this build.
-- **images** (List of Object) (see [below for nested schema](#nestedobjatt--builds--images))
-- **labels** (Map of String) Labels for this build.
-- **packer_run_uuid** (String) Packer generated UUID of this build.
-- **status** (String) Status of this build. DONE means that all images tied to this build were successfully built.
-- **updated_at** (String) Time this build was last updated.
+- `cloud_provider` (String) Name of the cloud provider this image is stored-in, if any.
+- `component_type` (String) Name of the builder that built this. Ex: 'amazon-ebs.example'.
+- `created_at` (String) Creation time of this build.
+- `id` (String) HCP ID of this build.
+- `images` (List of Object) (see [below for nested schema](#nestedobjatt--builds--images))
+- `labels` (Map of String) Labels for this build.
+- `packer_run_uuid` (String) Packer generated UUID of this build.
+- `status` (String) Status of this build. DONE means that all images tied to this build were successfully built.
+- `updated_at` (String) Time this build was last updated.
 
 <a id="nestedobjatt--builds--images"></a>
 ### Nested Schema for `builds.images`
 
 Read-Only:
 
-- **created_at** (String) Creation time of this image.
-- **id** (String) HCP ID of this image.
-- **image_id** (String) Cloud Image ID, URL string identifying this image for the builder that built it.
-- **region** (String) Region this image was built from. If any.
+- `created_at` (String) Creation time of this image.
+- `id` (String) HCP ID of this image.
+- `image_id` (String) Cloud Image ID, URL string identifying this image for the builder that built it.
+- `region` (String) Region this image was built from. If any.

docs/data-sources/packer_iteration.md

@@ -1,5 +1,6 @@
 ---
-page_title: "Data Source hcp_packer_iteration - terraform-provider-hcp"
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "hcp_packer_iteration Data Source - terraform-provider-hcp"
 subcategory: ""
 description: |-
   The Packer Image data source iteration gets the most recent iteration (or build) of an image, given a channel.
@@ -49,3 +50,5 @@ data "hcp_packer_iteration" "hardened-source" {
 Optional:
 
 - `default` (String)
+
+

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

@@ -110,6 +110,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

@@ -279,9 +279,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)