[Docs] Add note that using name property for CloudFront/PublicKey resource may cause dependency issues

[MitchellGerdisch]

When using the cloudfront/PublicKey resource, it is not uncommon to also use the cloudfront/KeyGroup resource.
If one sets the name property for the PublicKey resource (https://www.pulumi.com/registry/packages/aws/api-docs/cloudfront/publickey/#name_nodejs), the "delete-before-create" action that Pulumi takes will cause AWS to throw an error since Pulumi is trying to delete the PublicKey while it is still referenced by the KeyGroup. (See code below.)
Since KeyGroup references the PublicKey.id (which is AWS-generated), there is no way to avoid this problem by using dependsOn resource options or anything.

So, the work-arounds are:

• Let Pulumi autoname the resources.
• Set the namePrefix property and let the provider autoname the resources.

This leads to the suggestion that the documentation for the name property should come with a warning that explains that the setting the name property will lead to issues if the resource has to be replaced - for example because the encodedKey property value changes - and the PublicKey is referenced in another resource such as the cloudfront/keyGroup resource.
And suggest to use Pulumi autonaming as explained here, https://www.pulumi.com/docs/concepts/resources/names/#autonaming, or use the resoruce's namePrefix property instead.

If you want to see the driving issue in action:

// Test sequences
// 1) With specified name for PublicKey: 
//    A) pulumi up
//    B) change name of the tls.PrivateKey resource
//    C) pulumi up - see error as it tries to replace the cloudfront.PublicKey but it is still referenced by the KeyGroup.
// 2) With Pulumi dynamic naming (i.e. don't set `name` or `namePrefix` property): No problem.
// 3) With `namePrefix` set: No problem
import * as aws from "@pulumi/aws";
import * as tls from "@pulumi/tls";

const baseName = "mitch"

const tlsKey = new tls.PrivateKey(`${baseName}-tlskeyboo`, {
  algorithm: "RSA"
})

const cfPubKeyName = `${baseName}-cfPubKey`
const cfPubKey = new aws.cloudfront.PublicKey(cfPubKeyName, {
    comment: cfPubKeyName,
    encodedKey: tlsKey.publicKeyPem,
    // name: cfPubKeyName
    // namePrefix: cfPubKeyName
}
);

const cfKeyGroupName = `${baseName}-cfKeyGroup`
const cfKeyGroup = new aws.cloudfront.KeyGroup(cfKeyGroupName, {
    comment: cfKeyGroupName,
    items: [cfPubKey.id],
    name: cfKeyGroupName
});

[MitchellGerdisch]

Suggested text for the name property description:

The name for the public key. By default generated by this provider.
Note: Do not set if using the key's id in another resource (e.g. KeyGroup) since it will result in a dependency error from AWS. Instead, it is recommended to use Pulumi autonaming by leaving this property unset (default behavior) or set the namePrefix property to allow the provider to autoname the resource.

[pulumi-bot]

This issue has been addressed in PR #4088 and shipped in release v6.42.0.