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

[t0yv0]

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]

@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[bot]]

Your site preview for commit 6812b5d7 is ready! :tada:

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

[github-actions[bot]]

Your site preview for commit 95a25b7f is ready! :tada:

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

[github-actions[bot]]

Your site preview for commit f7e5595e is ready! :tada:

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

[github-actions[bot]]

Your site preview for commit 50358fc1 is ready! :tada:

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

[t0yv0]

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[bot]]

Your site preview for commit f9a1f600 is ready! :tada:

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

[github-actions[bot]]

Your site preview for commit a26fefd1 is ready! :tada:

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

[github-actions[bot]]

Your site preview for commit f1725541 is ready! :tada:

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

[t0yv0]

@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 https://github.com/pulumi/pulumi-aws/issues/4471 as this seems to have regressed.

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

[github-actions[bot]]

Your site preview for commit e7f99a0d is ready! :tada:

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

[georgberky]

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.

The confusing things for me were to find the old migration guide and

• the full explanation being in a video instead of in text
• the video showing a technique that my Typescript compiler forbids (redeclaring a variable)
• the guide not being too clear that you have to declare a v2 resource next to the v1 resource instead of replacing v1 with v2 even though they have the same Pulumi resource name
• the whole mechanism not working anymore
• an IaC tool trying to delete my resource (luckily failing because the old bucket wasn't empty, but this doesn't raise confidence)

If the mechanism doesn't work anymore, remove the guide or clearly state on top that it stopped working with v12345 of Pulumi.

[t0yv0]

Thanks for your feedback @georgberky that's a good point; we don't edit old blog content but we have a way to marking it obsolete and pointing to new material, I'll make sure we do this to https://www.pulumi.com/blog/announcing-v5.0.0-of-the-pulumi-aws-provider/#can-i-migrate-from-awss3bucket-to-awss3bucketv2

[github-actions[bot]]

Your site preview for commit e21ce5e9 is ready! :tada:

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

[github-actions[bot]]

Your site preview for commit 92056f2a is ready! :tada:

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

[cnunciato]

@t0yv0 @mjeffryes Correct me if I'm wrong, but wouldn't it possible to write a tool to take care of this for users automatically? This seems like an awful lot of manual (and potentially risky) work to distribute to all of our users (times all of their buckets) for something that looks, on the surface, to be readily amenable to automation. Have we considered that?

[mjeffryes]

It might be possible, to automate this, but TBH, we're not 100% convinced that upstream is going to follow through on pushing everyone to the side-car resources, so it doesn't make sense to invest in an automation for a migration that may not be needed.

The purpose of these docs is just to have a reference of what's currently required to migrate. We're not telling users they should migrate at this time.

[t0yv0]

@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:

• https://github.com/pulumi/pulumi-aws/issues/4471
• https://github.com/pulumi/pulumi-aws/issues/4475
• https://github.com/pulumi/pulumi-aws/issues/4470

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.

[github-actions[bot]]

Your site preview for commit 27c92fc3 is ready! :tada:

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

[github-actions[bot]]

Site previews for this pull request have been removed. ✨