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

[aidan-mundy]

🛠️ Description

Updates contributor documentation and resource-specific import examples to reflect multi-project support added by #454

The new resource and resource import checklists previously prohibited project_id arguments. This PR updates the checklists to require optional project_id attributes (for resources) and import ID prefixes (for importing) on all resources that have multi-project support.

Resources with multi-project support did not have documented examples for importing with non-default project IDs, this PR adds those examples.

🏗️ Acceptance tests

N/A, documentation only change

[hashicorp-cla]

All committers have signed the CLA.

[nywilken]

This is off to a good start. The docs are generated using the contents of the example directory so these changes need to be made there.

[nywilken]

So I believe these changes need to be added into the respective import.sh file within the resource example docs https://github.com/hashicorp/terraform-provider-hcp/tree/main/examples/resources/hcp_hvn.

These files are auto generated using templates.

Instead of relying on comments with the code block. What about creating a separate code block for the multi-project example

For example

Import

Import is supported using the following syntax:

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

[aidan-mundy]

The changes to the .md files come from running make gencheck which regenerates the docs directory. The source for the changes in this PR are the import.sh files as you noted. I think you may have missed the edits to the .sh files because the sort order places them below the .md files in the GitHub file browser

[aidan-mundy]

I was avoiding creating resource-specific templates if there are other clear ways of representing the information because AFAIK it prevents resources from being automatically adjusted if/when the default template changes.

I'm not sure if there actually is a scenario where we would update the default template. If there isn't one, then there's no harm in creating custom templates here.

Edit: An example of custom templates leading to drift from the default: packer_image_iteration and packer_image data sources are slightly out of sync with the format used by other data sources. Specifically, the page_title field is in a different order. (This is also the case for many of the resources with custom templates.)

[nywilken]

Got it.. thanks for calling this out. I realize now that when I clicked into the import.sh file I was looking at the one on main and not the import.sh associated with this branch.

I understand your point about using custom templates I was under the impression that each of the resources already had a custom template. But I see that is not true.

This is a nit for sure but not one worth rocking the boat for if the import details work for folks

[nywilken]

Alternatively you can do something like the following to reduce the context of the code block

# {project_id}:{hvn_id}
terraform import hcp_hvn.example f709ec73-55d4-46d8-897d-816ebba28778:main-hvn
# {project_id} not required when setting a provider-default project ID:
terraform import hcp_hvn.example main-hvn

[aidan-mundy]

This file requires manual updating. This is because descriptions are not supported for nested objects in the docs generator. This is the case at least with SDKv2, but I think it is possible with Framework. See here for more

[nywilken]

Yeah thanks for this. At some point I think we might need to deprecate this data source as it has been replace by the hcp_packer_image and hcp_packer_iteration data sources.

[nywilken]

Nicely done. This looks good to me. I left a nit on the import section. I find the comments to be a bit confusing but I just might need to get use to it.

[nywilken]

Got it.. thanks for calling this out. I realize now that when I clicked into the import.sh file I was looking at the one on main and not the import.sh associated with this branch.

I understand your point about using custom templates I was under the impression that each of the resources already had a custom template. But I see that is not true.

This is a nit for sure but not one worth rocking the boat for if the import details work for folks

[nywilken]

Alternatively you can do something like the following to reduce the context of the code block

# {project_id}:{hvn_id}
terraform import hcp_hvn.example f709ec73-55d4-46d8-897d-816ebba28778:main-hvn
# {project_id} not required when setting a provider-default project ID:
terraform import hcp_hvn.example main-hvn

[nywilken]

pinging @hashicorp/vault-cloud and @hashicorp/boundary-cloud for review on this as well.

[aoripov]

Looks good to me! I'm approving on behalf @hashicorp/vault-cloud

[hanshasselberg]

LGTM

[delores-hashicorp]

LGTM. Thank you!

[uruemu]

Thanks for doing this.