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

aidan-mundy · 2023-05-30T19:20:30Z

🛠️ 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 · 2023-05-30T19:20:36Z

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.

internal/provider/resource_hvn_peering_connection.go

nywilken · 2023-05-30T20:14:23Z

docs/resources/hvn.md

+# 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}


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

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

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.)

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

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 · 2023-05-30T23:29:54Z

templates/data-sources/packer_image_iteration.md.tmpl

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

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 · 2023-05-31T18:57:20Z

docs/resources/hvn.md

+# 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}


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 · 2023-05-31T19:09:50Z

docs/resources/hvn.md

+# 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}


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 · 2023-05-31T19:18:27Z

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 · 2023-06-07T17:48:51Z

Thanks for doing this.

aidan-mundy added 3 commits May 30, 2023 14:19

Update contributing docs for multi-project support

9bfd763

Update individual resource docs to reflect multi-project support

9a1d30a

Regenerate docs with make gencheck

c746e10

aidan-mundy added the documentation Improvements or additions to documentation label May 30, 2023

aidan-mundy and others added 3 commits May 30, 2023 15:24

Adjust checklist wording

94f83f8

Add changelog for PR

6e7040d

Merge branch 'main' into aidan-mundy/multiproject-docs

7183b1b

aidan-mundy marked this pull request as ready for review May 30, 2023 19:27

aidan-mundy requested a review from a team as a code owner May 30, 2023 19:27

aidan-mundy requested a review from a team May 30, 2023 19:27

aidan-mundy requested review from a team as code owners May 30, 2023 19:27

aidan-mundy requested review from blueberry-pi, helenfufu, Ganeshrockz and abhishek-hashicorp May 30, 2023 19:27

nywilken suggested changes May 30, 2023

View reviewed changes

aidan-mundy added 2 commits May 30, 2023 17:56

Remove redundant custom schema

7b15fa6

Update packer_image_iteration docs

aabc57a

aidan-mundy commented May 30, 2023

View reviewed changes

nywilken approved these changes May 31, 2023

View reviewed changes

blueberry-pi requested review from himran92 and removed request for helenfufu June 5, 2023 19:56

aidan-mundy requested a review from aoripov June 6, 2023 15:13

aoripov approved these changes Jun 6, 2023

View reviewed changes

hanshasselberg approved these changes Jun 7, 2023

View reviewed changes

delores-hashicorp approved these changes Jun 7, 2023

View reviewed changes

This comment was marked as duplicate.

Sign in to view

Merge branch 'main' into aidan-mundy/multiproject-docs

c2b0c40

uruemu approved these changes Jun 7, 2023

View reviewed changes

aidan-mundy merged commit b097e57 into main Jun 7, 2023

aidan-mundy deleted the aidan-mundy/multiproject-docs branch June 7, 2023 17:51

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

aidan-mundy commented May 30, 2023

hashicorp-cla commented May 30, 2023 •

edited

Loading

nywilken left a comment

nywilken May 30, 2023

aidan-mundy May 30, 2023

aidan-mundy May 30, 2023 •

edited

Loading

nywilken May 31, 2023

nywilken May 31, 2023 •

edited

Loading

aidan-mundy May 30, 2023 •

edited

Loading

nywilken May 31, 2023

nywilken left a comment

nywilken May 31, 2023

nywilken May 31, 2023 •

edited

Loading

nywilken commented May 31, 2023

aoripov left a comment

hanshasselberg left a comment

delores-hashicorp left a comment

This comment was marked as duplicate.

uruemu commented Jun 7, 2023

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

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

Conversation

aidan-mundy commented May 30, 2023

🛠️ Description

🏗️ Acceptance tests

hashicorp-cla commented May 30, 2023 • edited Loading

nywilken left a comment

Choose a reason for hiding this comment

nywilken May 30, 2023

Choose a reason for hiding this comment

Import

aidan-mundy May 30, 2023

Choose a reason for hiding this comment

aidan-mundy May 30, 2023 • edited Loading

Choose a reason for hiding this comment

nywilken May 31, 2023

Choose a reason for hiding this comment

nywilken May 31, 2023 • edited Loading

Choose a reason for hiding this comment

aidan-mundy May 30, 2023 • edited Loading

Choose a reason for hiding this comment

nywilken May 31, 2023

Choose a reason for hiding this comment

nywilken left a comment

Choose a reason for hiding this comment

nywilken May 31, 2023

Choose a reason for hiding this comment

nywilken May 31, 2023 • edited Loading

Choose a reason for hiding this comment

nywilken commented May 31, 2023

aoripov left a comment

Choose a reason for hiding this comment

hanshasselberg left a comment

Choose a reason for hiding this comment

delores-hashicorp left a comment

Choose a reason for hiding this comment

This comment was marked as duplicate.

uruemu commented Jun 7, 2023

hashicorp-cla commented May 30, 2023 •

edited

Loading

aidan-mundy May 30, 2023 •

edited

Loading

nywilken May 31, 2023 •

edited

Loading

aidan-mundy May 30, 2023 •

edited

Loading

nywilken May 31, 2023 •

edited

Loading