How Do I Rename a Pulumi Project With a Self-Hosted Backend?

Renaming a Pulumi project involves both updating the project name in Pulumi.yaml and potentially renaming the stack. It’s important to understand that this process requires careful consideration, especially regarding resource names that might depend on the stack name.

Here are the steps to rename a Pulumi project:

1. Update the Pulumi.yaml file: Change the name field in your project’s Pulumi.yaml file.

2. Rename the stack (if needed): Use the pulumi stack rename command to rename your project by updating the fully-qualified stackname:

   pulumi stack rename <new-stack-name>
   

   You can also rename the stack with a fully-qualified name that includes the new project:

   pulumi stack rename organization/new-project-name/stack-name
   

Important Considerations

• Resource Impact: When renaming a stack, be aware that this changes the value of getStack() inside your Pulumi program. If any resource names use the stack name, the next pulumi up will attempt to delete the old resources and create new ones.

• Backend Configuration: If you’re using a self-hosted backend, the backend URL configuration in Pulumi.yaml should remain unchanged unless you specifically need to update it.

Here is an example Pulumi.yaml file before and after renaming:

Before Renaming

name: old-project-name
runtime: nodejs
description: A Pulumi project
backend:
  url: https://self-hosted-backend.example.com

After Renaming

name: new-project-name
runtime: nodejs
description: A Pulumi project
backend:
  url: https://self-hosted-backend.example.com

To avoid unintended resource recreation, carefully review your infrastructure code to identify any resources that might be using getStack() or the project name in their naming scheme. If you notice unwanted resource changes in your preview, you may need to:

1. Use resource aliases to maintain continuity
2. Update resource names to avoid dependencies on the stack name
3. Or temporarily rename the stack back to its previous name while you make the necessary adjustments

Remember that after renaming the project in Pulumi.yaml, the new project name must match the name used in any fully-qualified stack references for updates to work correctly.