Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Document migrating aws.s3.Bucket to aws.s3.BucketV2 #5444

Merged
merged 20 commits into from
Oct 7, 2024
Merged

Document migrating aws.s3.Bucket to aws.s3.BucketV2 #5444

merged 20 commits into from
Oct 7, 2024

Conversation

t0yv0
Copy link
Member

@t0yv0 t0yv0 commented Sep 17, 2024

Description

Add a migration guide for moving from aws.s3.Bucket to aws.s3.BucketV2.

Fixes https://github.com/pulumi/home/issues/3630

Adding a new package?

If this pull request adds a new package:

  • The package's schema URL in this PR is correct.
  • The package metadata file, if present, contains:
    • a supported category (one of Cloud, Infrastructure, Network, Database, Monitoring, or Utility).
    • a valid plugin download URL. See Publish Your Package.
    • a description that explains what the package does.
    • a valid logo URL that points to a PNG whose dimensions conform to the others in this repo (e.g., 100x100).
  • The package repo contains an Overview doc (/docs/_index.md) that includes:
    • a brief explanation of what the package is and what it does.
    • at least one representative example in all supported languages.
    • a front-matter property for the layout set to package.
  • The package repo contains an Installation and Configuration doc (/docs/installation-configuration.md) that includes:
    • links to SDKs in all supported languages.
    • a copyable command for installing the resource plugin if necessary.
    • an example of configuring the provider with pulumi config set.
    • an example of configuring the provider with environment variables.
  • The repository has:
    • a version tag prefixed with v that corresponds with a valid GitHub release and published package SDKs
  • A CODEOWNER has reviewed the PR.
  • A member of the @pulumi/docs team has reviewed all documentation.

@t0yv0
Copy link
Member Author

t0yv0 commented Sep 17, 2024

@interurban opening for early review, thanks a lot!

As an aside, I'm working to get examples formatted with the right <chooser> magic and I'm putting together a little script that updates the non-yaml sections automatically via pulumi convert. Would you all be interested in something like this or is there existing machinery to do this? Much appreciated.

@github-actions GitHub Actions
Copy link

Your site preview for commit 6812b5d is ready! 🎉

http://registry--origin-pr-5444-6812b5d7.s3-website.us-west-2.amazonaws.com/registry.

@github-actions GitHub Actions
Copy link

Your site preview for commit 95a25b7 is ready! 🎉

http://registry--origin-pr-5444-95a25b7f.s3-website.us-west-2.amazonaws.com/registry.

@github-actions GitHub Actions
Copy link

Your site preview for commit f7e5595 is ready! 🎉

http://registry--origin-pr-5444-f7e5595e.s3-website.us-west-2.amazonaws.com/registry.

@github-actions GitHub Actions
Copy link

Your site preview for commit 50358fc is ready! 🎉

http://registry--origin-pr-5444-50358fc1.s3-website.us-west-2.amazonaws.com/registry.

@t0yv0
Copy link
Member Author

t0yv0 commented Sep 17, 2024

Looks like something with choosers inside lists is not happy:

/home/runner/work/registry/registry/themes/default/content/registry/packages/aws/how-to-guides/bucketv2-migration.md:
Line 2417: Ordered list item prefix [Expected: 1; Actual: 6; Style: 1/2/3].
Line 2420: Ordered list item prefix [Expected: 2; Actual: 7; Style: 1/2/3].
Line 2422: Ordered list item prefix [Expected: 3; Actual: 8; Style: 1/2/3].

@github-actions GitHub Actions
Copy link

Your site preview for commit f9a1f60 is ready! 🎉

http://registry--origin-pr-5444-f9a1f600.s3-website.us-west-2.amazonaws.com/registry.

flostadler
flostadler reviewed Sep 18, 2024
View reviewed changes
themes/default/content/registry/packages/aws/how-to-guides/bucketv2-migration.md Outdated Show resolved Hide resolved
themes/default/content/registry/packages/aws/how-to-guides/bucketv2-migration.md Outdated Show resolved Hide resolved
themes/default/content/registry/packages/aws/how-to-guides/bucketv2-migration.md Outdated Show resolved Hide resolved
themes/default/content/registry/packages/aws/how-to-guides/bucketv2-migration.md Outdated
2. Perform `pulumi up` to replace (delete and re-create) the buckets in AWS.

If replacement is not acceptable, it is possible to perform a manual migration with `pulumi import` (see Avoiding
replacement).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should be able to link to the section like this: [Avoiding Replacement](#avoiding-replacement). Not 100% sure though whether Hugo supports that syntax

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's been failing builds. Looks like this only works in GitHub markdown. @interurban might have some pointers here.

themes/default/content/registry/packages/aws/how-to-guides/bucketv2-migration.md Outdated Show resolved Hide resolved
themes/default/content/registry/packages/aws/how-to-guides/bucketv2-migration.md Outdated Show resolved Hide resolved
themes/default/content/registry/packages/aws/how-to-guides/bucketv2-migration.md Outdated
against the actual cloud account. While the details will vary depending on your use case, this procedure generally
involves the following steps:

- Find URNs for legacy Bucket Pulumi resources using `pulumi stack export`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should be able to extract those with jq, right? Could be a nice addition to add that here

@t0yv0 t0yv0 mentioned this pull request Sep 18, 2024
Open
@github-actions GitHub Actions
Copy link

Your site preview for commit a26fefd is ready! 🎉

http://registry--origin-pr-5444-a26fefd1.s3-website.us-west-2.amazonaws.com/registry.

@github-actions GitHub Actions
Copy link

Your site preview for commit f172554 is ready! 🎉

http://registry--origin-pr-5444-f1725541.s3-website.us-west-2.amazonaws.com/registry.

@t0yv0 t0yv0 requested a review from flostadler September 18, 2024 20:07
@t0yv0
Copy link
Member Author

t0yv0 commented Sep 18, 2024

@flostadler I went ahead and took a larger bucket example for a spin through the import-based migration procedure. It worked but highlighted a few extra steps, this was useful.

For alternative upgrade procedures.

I have filed pulumi/pulumi-aws#4471 as this seems to have regressed.

I've also had a slack conversation with a user trying this today and filed pulumi/pulumi-aws#4470 - sounds like we could do a bit more possibly, depending on interest here.

@github-actions GitHub Actions
Copy link

Your site preview for commit e7f99a0 is ready! 🎉

http://registry--origin-pr-5444-e7f99a0d.s3-website.us-west-2.amazonaws.com/registry.

t0yv0 added 20 commits September 30, 2024 16:58
@t0yv0 t0yv0 force-pushed the t0yv0/bucketv2-migration branch from 92056f2 to 27c92fc Compare September 30, 2024 21:04
@t0yv0
Copy link
Member Author

t0yv0 commented Sep 30, 2024

@cnunciato we have considered some possibilities here but they remain much more complicated that appears on the surface. I'm tracking some relevant issues here in pulumi-aws:

For the moment I think our recommendation is to proceed with the documentation updates, incorporating Matt's latest comment the stance is:

  • encourage new users to use BucketV2 vs Bucket
  • offer instructions for users opting to migrate existing Bucket code to BucketV2 code on how to do this

At the time of pulumi-aws v7 major at some point in the future mostly driven by upstream decisions on breaking changes we'll reconsider the above tooling ideas. Possibly we'll also have a little bit more user signal on importance of this by that time.

@t0yv0 t0yv0 requested a review from mjeffryes September 30, 2024 21:08
@github-actions GitHub Actions
Copy link

Your site preview for commit 27c92fc is ready! 🎉

http://registry--origin-pr-5444-27c92fc3.s3-website.us-west-2.amazonaws.com/registry.

@t0yv0 t0yv0 merged commit 2c5ca12 into master Oct 7, 2024
3 checks passed
@t0yv0 t0yv0 deleted the t0yv0/bucketv2-migration branch October 7, 2024 17:18
@github-actions GitHub Actions
Copy link

github-actions bot commented Oct 7, 2024

Site previews for this pull request have been removed. ✨

t0yv0 added a commit to pulumi/pulumi-aws that referenced this pull request Oct 16, 2024
@t0yv0
Update aws.s3.Bucket notes to point to aws.s3.BucketV2 (#4491)
df36089 
Add a note for the aws.s3.Bucket page to direct users to
aws.s3.BucketV2.

Fixes pulumi/home#3629

Fix an issue with documentation override: due to a bug
`docs/resource/aws_s3_bucket_legacy.md` was not being picked up and the
`aws.s3.Bucket` page was incorrectly serving docs for the
`aws.s3.BucketV2` resource. This is fixed here.

This PR should not merge until
pulumi/registry#5444 gets published.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@interurban interurban interurban approved these changes

@cnunciato cnunciato Awaiting requested review from cnunciato

@flostadler flostadler Awaiting requested review from flostadler

@corymhall corymhall Awaiting requested review from corymhall

@mjeffryes mjeffryes Awaiting requested review from mjeffryes

Assignees

@t0yv0 t0yv0

Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
7 participants
@t0yv0 @georgberky @cnunciato @mjeffryes @interurban @flostadler @corymhall