Pulumi Aliases: Rename Resources Without Replacement (2026)

Pulumi Aliases let you rename resources in your infrastructure code without forcing Pulumi to destroy and recreate them.

Let’s see this in action. Imagine you have a Pulumi program that defines an AWS S3 bucket.

import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";

const myBucket = new aws.s3.Bucket("my-old-bucket-name", {
    bucket: "my-awesome-bucket-12345", // The actual S3 bucket name
});

export const bucketName = myBucket.bucket;

If you run pulumi up, Pulumi will create an S3 bucket named my-awesome-bucket-12345. Now, let’s say you decide my-old-bucket-name is a bit clunky and you want to rename it to my-new-bucket-resource.

Without Aliases, if you simply change the resource name in your code:

import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";

const myBucket = new aws.s3.Bucket("my-new-bucket-resource", { // Renamed resource name
    bucket: "my-awesome-bucket-12345",
});

export const bucketName = myBucket.bucket;

And run pulumi up again, Pulumi will see my-old-bucket-name as a resource that’s no longer defined and my-new-bucket-resource as a brand new resource. It will try to delete your existing bucket and create a new one. This is often undesirable, especially for stateful resources like S3 buckets, as it would lead to data loss.

This is where Aliases come in. You can tell Pulumi that my-new-bucket-resource is actually an alias for the same underlying resource that was previously known as my-old-bucket-name.

Here’s how you’d use an Alias:

import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";

const myBucket = new aws.s3.Bucket("my-new-bucket-resource", { // The new logical name
    bucket: "my-awesome-bucket-12345",
    // Define the alias here
    aliases: [{
        // This is the *old* logical name that Pulumi knew this resource by.
        name: "my-old-bucket-name",
        // Optionally, if the logical name *and* type changed, you'd specify the type here.
        // type: "aws:s3/bucket:Bucket",
    }],
});

export const bucketName = myBucket.bucket;

When you run pulumi up with this code, Pulumi will recognize that my-new-bucket-resource is an alias for the existing my-old-bucket-name. It sees that the underlying properties (like the actual bucket name my-awesome-bucket-12345) haven’t changed. Therefore, it will do nothing, preserving your existing infrastructure.

The aliases property is an array, allowing a resource to have multiple aliases over its lifecycle. Each alias object has a name field which specifies the previous logical name of the resource. You can also optionally specify the type if the resource type itself has changed (e.g., from aws:s3/bucket:Bucket to aws:s3/bucketV2:BucketV2).

Aliases are crucial for refactoring your Pulumi code. They allow you to rename resources, change their logical names, or even move them between modules or packages without incurring the cost of resource replacement. This is particularly important for resources that are difficult or impossible to replace, such as databases with live data, or when you want to avoid downtime.

When you rename a resource in Pulumi, Pulumi’s state file is the source of truth. Pulumi compares the desired state (your code) with the actual state (what’s in the state file and what exists in the cloud). When you change a resource’s logical name, Pulumi, by default, sees it as a deletion of the old resource and creation of a new one because the urn (Uniform Resource Name) in the state file would change. The urn is Pulumi’s unique identifier for a resource, composed of its stack, project, type, and logical name. Aliases bridge this gap by explicitly linking the new logical name to the old one, effectively telling Pulumi, "this new name refers to the same thing that had that old name."

The most surprising thing about Aliases is that they work by modifying the resource’s urn in the Pulumi state file. When you first define a resource with a logical name, Pulumi creates a urn like urn:pulumi:my-stack::my-project::aws:s3/bucket:Bucket$my-old-bucket-name. If you then change the logical name to my-new-bucket-resource and add an alias for my-old-bucket-name, Pulumi will update the urn in the state file to urn:pulumi:my-stack::my-project::aws:s3/bucket:Bucket$my-new-bucket-resource. The alias entry in the resource’s metadata within the state file is what allows Pulumi to find the old urn and perform this update instead of a destroy/create.

You’ll next want to understand how Pulumi handles resource import when dealing with existing infrastructure that has drifted from your Pulumi state, especially if you need to reconcile resources that were created outside of Pulumi or were previously managed by a different tool.