Announcing the public preview of Update Plans
Pulumi’s previews are an important part of any workflow where you want to see the changes that will be made to your infrastructure before actually making the changes (with
pulumi up). However, today there is no guarantee that the
pulumi up operation will do only what was previewed; if the program, or your infrastructure, changes between the preview and the update, the update might make additional changes to bring your infrastructure back in line with what’s defined in your program. We’ve heard from many of you that you need a strong guarantee about exactly which changes an update will make to your infrastructure, especially in critical and production environments.
Today, I’m excited to announce the public preview of Update Plans, a new Pulumi feature which guarantees that operations shown in
pulumi preview will run on
pulumi up. Update Plans also help catch any unexpected changes that might happen between when you preview a change and when you apply that change. Update Plans work by saving the results of a
pulumi preview to a plan file, which enables you to restrict subsequent
pulumi up operations to only the actions saved in the plan file. This helps you ensure that what you saw in the
pulumi preview is what will actually happen when you run
Here’s an example of Update Plans in action. In this example we’re creating a new AWS EC2 instance and associated security group. First, we plan the change with
pulumi preview --save-plan plan.json, and then we examine the plan file to see which resources the plan expects to change. Finally, we run an update that’s constrained to the plan with
pulumi up --plan plan.json.
To get started, you only need to add
--save-plan <file> to the preview command and
--plan <file> to the up command. In the video above, we demonstrated a pretty trivial example where our program did what our plan expected, so everything ran just as expected. But what if we changed our program to have a different
userData value and ran it against the same plan? If we clear the infrastructure we just created and use the same plan with the changed program, then Update Plans will return an error and block the change.
When updates fail to validate against the plan, Pulumi will print what constraint failed. In the example above, the resource
urn:pulumi:dev::aws-ts-webserver::aws:ec2/instance:Instance::web-server-www changed the value of the property
New scenario enabled by Update Plans: pull request validation workflows
Software development teams commonly use version control-based workflows to review and monitor the code that is added to a codebase. For example, many teams protect their primary branch (e.g.
trunk) from direct code pushes and instead require a pull or merge request where the changes can be reviewed and continuous integration (CI) and tests can be run.
With Update Plans, this same workflow is now possible with infrastructure managed by Pulumi. Assuming you already have CI set up for your pull/merge requests, you can run
pulumi preview --save-plan PLAN-FILENAME and output the resulting plan file as a CI artifact. Then, update the CI workflow that runs when changes are merged to run
pulumi up --plan PLAN-FILENAME.
Try Update Plans
We’re eager for you to try the public preview of Update Plans and let us know what you think. To try it out, make sure you’ve updated to Pulumi 3.24.1 then set the following environment variable in your shell:
Then, save a plan file:
pulumi preview --save-plan plan.json
Finally, pass the plan file to the
pulumi up command:
pulumi up --plan-file plan.json
PULUMI_EXPERIMENTAL is set
pulumi up will also generate a plan during it’s preview stage which will then apply to the update if an explict plan hasn’t been given via
--plan. This ensures your
up previews match what happens in the resulting operations.
We’d love to hear your thoughts on the Update Plans feature! Feel free to start discussions or ask questions using GitHub Discussions in the