In Pulumi, what happens when you change the string logical name passed to a resource constructor — for example renaming `new aws.s3.Bucket("assets")` to `"assets-bucket"` — and how do you make that rename without destroying the resource?

## URN as identity Every Pulumi resource has a URN of roughly the shape `urn:pulumi:stack::project::type::name` — extended with the parent chain when a resource is nested. That URN is the primary key linking three things: the resource declared in your program, the entry recorded in state, and the object in the cloud. The `name` component is the first argument to the constructor. It is *logical*: distinct from the physical name in the cloud, which is either what you set explicitly in the args or one Pulumi auto-generates by appending a random suffix to the logical name. So the string you thought was a variable label is the identity of the resource. ## What a rename does When the engine walks your program it looks up each registered resource by URN in the state snapshot. After a rename: - The new URN has no state entry, so the resource is planned as a **create**. - The old URN is in state but no longer registered by the program, so it is planned as a **delete**. The preview shows both. For a stateless resource — a security group rule, an IAM policy attachment — this is mildly wasteful. For an RDS instance, an S3 bucket with objects, or a persistent disk, it is destruction of production data dressed up as a refactor. This is exactly the class of change that gets waved through in review because the code diff looks like a tidy-up. A useful side note: auto-naming is what makes the create-before-delete even possible without a name collision, because the replacement gets a different physical name. If you pinned the physical name explicitly, you may instead get a hard failure mid-deploy — a resource already exists error — which is at least louder. ## Aliases, the intended fix The `aliases` resource option lists prior identities: ```typescript const bucket = new aws.s3.Bucket("assets-bucket", {}, { aliases: [{ name: "assets" }], }); ``` On the next preview the engine matches the old URN through the alias and reports an update or no change rather than a replace. An alias entry can also specify `type`, `parent` or a full `urn`, which covers the less obvious identity changes: - **Adopting into a component.** Wrapping existing resources in a `ComponentResource` re-parents them, and the parent is part of the URN, so every child needs `aliases: [{ parent: pulumi.rootStackResource }]` or an explicit old URN. This is the most common reason a "pure refactor" into components proposes to delete the estate. - **Renaming the component.** The component's own name is in its children's URNs, so renaming the component renames all of them. A good practice is to keep aliases in place for at least a deployment cycle across all stacks, then remove them once every stack has been updated — an alias only helps a stack whose state still holds the old URN. ## The loop trap The worst version of this problem is not a deliberate rename at all: ```typescript const subnets = ["10.0.1.0/24", "10.0.2.0/24", "10.0.3.0/24"]; subnets.forEach((cidr, i) => new aws.ec2.Subnet(`subnet-${i}`, { vpcId: vpc.id, cidrBlock: cidr, })); ``` Insert a new CIDR at the front and every subnet shifts index: `subnet-0` now means a different CIDR, `subnet-2` is new, and the engine plans updates or replacements across the whole set. The remedy is the same one every IaC tool converges on — derive the logical name from something stable about the item rather than its position: ```typescript for (const cidr of subnets) { new aws.ec2.Subnet(`subnet-${cidr.replace(/[./]/g, "-")}`, { vpcId: vpc.id, cidrBlock: cidr }); } ``` Because a Pulumi program is real code, nothing stops you writing the index version; the language will not warn you. That freedom is the model's strength and this is its sharpest edge. ## Guardrails - **Read the preview, particularly the replace and delete lines.** A rename that is safe and a rename that destroys a database look identical in the source diff and completely different in the preview. - **`protect: true`** on resources that must never be deleted turns an accidental destroy into a refused operation. Removing protection is then a deliberate, visible act. - **`retainOnDelete: true`** is the softer variant: Pulumi forgets the resource without asking the provider to delete it. Useful during a migration, dangerous as a habit because it leaks untracked infrastructure. - If a resource has already been destroyed and recreated by accident, the recovery path is `pulumi import` to bring an existing cloud object back under management — with the *correct* logical name this time.