Cloud Engineering, DevOps

Managing and Safeguarding State Files in Pulumi

If you’re new to Pulumi, an infrastructure as code (IaC) tool, you’re embarking on a journey that simplifies cloud resource management and deployment. Pulumi allows you to define your infrastructure in familiar programming languages and leverages cloud provider APIs to create, update, and manage your cloud resources effortlessly.

One essential aspect of working with Pulumi is understanding and managing Pulumi State. Think of Pulumi State as a record-keeper that holds information about your cloud resources’ desired state. It tracks the configurations, relationships, and current status of your infrastructure, ensuring that Pulumi can intelligently manage changes and updates over time.

In this article, you will learn about Pulumi State and explore the significance of managing Pulumi State files, focusing on how to prevent corruption and recover functionality when issues come up.

Understanding How Pulumi State Works

Pulumi State manages your infrastructure using Pulumi. Let’s see how it works and its significance in updating, creating, and deleting cloud resources.

When you define your infrastructure using Pulumi code, you specify the desired state of your cloud resources. This includes details like the type of resources, their configurations, and any relationships between them. Pulumi takes this information and translates it into a structured format known as the Pulumi State (JSON). Pulumi uses this state to understand the desired state of your infrastructure and effectively manage updates and modifications.

Creating Infra Resources

When you deploy your infrastructure code for the first time, Pulumi uses the Pulumi State to create the specified cloud resources. It interacts with your cloud provider’s API to provision the resources and sets their configurations based on the state information. Pulumi ensures that the created resources match the desired state, bringing your infrastructure to life.

Updating Infra Resources

When you modify your infra code to reflect changes, such as updating a configuration or adding a new resource, Pulumi compares the new code with the existing Pulumi State. It identifies the differences and generates a plan to update your cloud resources accordingly. The plan outlines the necessary changes, such as creating new resources, updating existing ones, or deleting obsolete resources. Pulumi applies these changes to your cloud provider based on the created plan, ensuring that your infra matches the desired state defined in your code.

Deleting Infra Resources

If you remove a resource from your infrastructure code, Pulumi recognizes this change when you update your infrastructure. It compares the current Pulumi State with the updated code and identifies the resources that are no longer present in the code. Pulumi generates a plan to delete these resources, ensuring that your cloud environment aligns with the desired state. By leveraging the Pulumi State, resource deletions are handled gracefully, preventing any unintentional removal of resources.

Things that can corrupt your Pulumi State

There are a number of things that can corrupt your Pulumi State, but these are the four reasons that I’ve noticed are very common:

  • Multiple Simultaneous Access to State: When multiple processes (e.g. people and pipelines) try to change the same state file at the same time, problems can occur. It’s like your whole team simultaneously updating the same paragraph in a shared Google doc at the exact moment. This simultaneous access can lead to mistakes or confusion in the information stored in the state file.
  • Version Mismatches: Pulumi State files work with specific versions of your infra code. If you accidentally deploy an older version of your code that isn’t the version in sync with the state, it can cause conflicts and problems. It’s important to make sure that your code and the Pulumi tools you use are compatible and work together correctly.
  • External Factors: If there is a timeout, or there are other issues like computer crashes, power outages, or network problems during state file operations, it can cause corruption. This is because if a process is writing to the state, it wouldn’t terminate properly and it will become incomplete or unreadable.
  • Other Incomplete or Failed Operations: If something goes wrong while performing a Pulumi operation, like creating or updating a resource, it can leave the state file in an inconsistent state. This can happen due to mistakes in your code, problems with the cloud provider’s services, or issues with the connection between your computer and the cloud.

How to prevent corruption to your Pulumi State

To ensure the integrity of your Pulumi State and prevent corruption, here are some best practices you can follow:

  • Use State Locking: Pulumi has a special feature called state locking that prevent conflicts when multiple processes attempt to modify the state file simultaneously.
  • Regularly Backup State Files: Create backups of your Pulumi State files regularly. Backups serve as a safety net, allowing you to restore a known working state in case of corruption.
  • Perform Regular Validation: Periodically refresh your Pulumi State files. You can run pulumi refresh to verify the consistency of the state file against the actual cloud resources by incorporating these commands into your development workflow or CI/CD pipeline to catch any discrepancies early and rectify them promptly.
  • Automation and Infrastructure-as-Code Pipelines: Automate pulumi operations to minimize human errors. You can use bash scripts or IaC pipelines to automate your infra and backup state files. Automation makes execution of these tasks consistent, which reduces the chances of accidental modifications or corruptions caused by manual interventions.
  • Test Infrastructure Changes: Before making changes to your officially infrastructure, thoroughly test them using test stacks and validate your changes before you merge. You can also use Pulumi’s preview functionality to assess the impact of changes before actually modifying resources. With this. you will identify potential issues earlier and reduce the likelihood of corruption.

Fixing Corrupted Pulumi State: Steps for Recovery

If prevention doesn’t work and you encounter a corrupted Pulumi State file, you can still take prompt action to restore functionality. Here are steps you can follow to fix a corrupted Pulumi State:

  • Identify the Corruption: To fix the error, it’s important to know what the error is so the first step is to identify the corruption in the state file. This can manifest as errors during Pulumi operations or unexpected behavior in your infrastructure. Pay attention to any error logs that indicate potential issues with the state file.
  • Restore the Latest Backup: If you have a recent backup of the state file, restore it to a safe location. It’s crucial to ensure you don’t overwrite the corrupted state file. This backup serves as a starting point for recovery. The backup files usually have a .bak file extension and you can open them up in any text editor.
  • Analyze for differences: Compare the desired state of your infrastructure in your code with the actual state stored in the backup. Identify the differences between the corrupted state file and the backup.
  • Manual Reconciliation: To fix a corrupted Pulumi State, you need to compare the actual state of your cloud resources with what you want them to be according to your code. Carefully look at the resources in your cloud provider and see if they match what you expect based on your code. Identify what needs to be done to make the state file accurate again. This might involve creating resources that are missing, changing configurations to match your code, or getting rid of resources that are no longer needed. By doing this, you can bring the state file back to a reliable and correct state.
  • Run and Apply Changes: After fixing the state file, run a pulumi refresh to sync the states and run pulumi up to run infra updates which will align it with the actual state of your cloud resources.


Now you have a solid understanding of how to manage and protect your Pulumi State files, giving you confidence as you dive into IaC using Pulumi.

In case your state file gets corrupted, fear not! With the right approach, you can recover quickly. Just identify the problem, restore from a backup, compare and fix any differences, make the necessary changes, and thoroughly test everything. Remember, your Pulumi State is the foundation of your infrastructure projects. By following these simple steps and taking charge of your state files, you’ll be able to unleash the full power of Pulumi to effortlessly create, update, and manage your cloud resources.

There’s a lot of text (or theory) in this article because I just wanted to teach the concept. However, if you’d like to see code, let me know on Twitter and I’d make it happen. Happy coding!

Spread the love

Leave a Reply

Your email address will not be published. Required fields are marked *