Choosing the right state backend is fundamental to how Pulumi manages your infrastructure's lifecycle, collaboration, and security. Here’s a breakdown of the main types, their characteristics, and who they’re best suited for:

• Pulumi Cloud Backend:
  
  • Fully managed SaaS solution hosted by Pulumi.
  • No infrastructure setup needed—simply sign in to app.pulumi.com with the CLI.
  • Features seamless team collaboration, built-in security, version history, audit logs, and automated checkpointing.
  • All secrets encrypted at rest and compliant with security standards.
  • Recommended for organizations, teams, and those valuing low operational overhead.
• Self-Managed (DIY) Backend:
  
  • User-controlled state storage in your preferred object store or local filesystem.
  • Supports AWS S3, Azure Blob Storage, Google Cloud Storage, Minio, and other S3-compatible services.
  • Greater control over data location, backup, access policies, and encryption (you manage it all).
  • Must set up bucket or directory structure, secrets management, and handle concurrency cautions if collaborating in teams.
  • Best for regulated industries, advanced users, or when full control is required.
• Local Filesystem Backend:
  
  • State files stored directly on your machine (with a file:// path).
  • Very fast and simple—ideal for experimentation and single-user scenarios.
  • Not recommended for teams or production due to the risk of local data loss and lack of collaboration.

The Pulumi Cloud Backend is the default and easiest way to manage Pulumi state. It is a fully managed SaaS platform hosted by Pulumi that stores your stack state remotely, securely, and with features designed for collaboration, policy enforcement, and disaster recovery.

• Easy Setup: Get started by simply running pulumi login. If no URL is specified, the CLI connects to the cloud backend at https://app.pulumi.com.
• Centralized State Management: Every update you run with pulumi up is automatically saved and versioned in the cloud. You can view history, diffs, logs, and deployments through the web console.
• Collaboration Ready: Share your projects and stacks with your team, enforce RBAC, and review deployment history for better team workflows.
• Built-in Secrets Management: Encrypts config & secrets using per-stack encryption keys. No need to manage your own KMS unless you prefer to.
• Audit and History: Complete audit logs, checkpoint versions, and rollback capabilities ensure traceability and stability.
• No Cloud Credentials Stored: Pulumi Cloud only stores your resource metadata and encrypted secrets—not your cloud provider credentials.

How to Login to Pulumi Cloud:

pulumi login

How to View Stack State in the Console:

1. Visit https://app.pulumi.com
2. Select your organization or personal account
3. Click into your project and stack

Key Benefits Include:

• Secure, encrypted state storage with no additional configuration
• Versioned checkpoint history for each deployment
• Web-based stack explorer and diff viewer
• Team access controls and stack sharing
• Support for automation APIs and CI/CD integration

This backend is ideal for teams and organizations that want a hassle-free, secure, and collaborative infrastructure automation workflow without managing the backend state infrastructure themselves.

The Self-Managed (DIY) Backend gives you full control over where and how your Pulumi state files are stored. This option lets you choose cloud object storage systems or your local filesystem, allowing you to tailor security, structure, and workflows to your organization's needs.

• Custom Storage Locations: Store Pulumi state JSON files in your choice of:
  
  • AWS S3: s3://bucket-name/path
  • Azure Blob Storage: azblob://container-name/path
  • Google Cloud Storage: gs://bucket-name/path
  • S3-Compatible: Minio, Ceph, etc. (via S3 APIs)
  • Local Filesystem: file://./directory
  • PostgreSQL: Community-supported option for advanced use cases
• Your Responsibility:
  • Set up and secure storage (IAM roles, policies, encryption-at-rest, etc.).
  • Manage backups and versioning for disaster recovery.
  • Coordinate safe collaboration—implement file-based locking or team access controls, especially to prevent concurrent state file updates.
  • Define naming convention for stacks, ideally namespacing with project identifiers to avoid conflicts.
  • Configure secrets encryption provider as desired.
• When to Use:
  • Regulated industries or enterprises with strict compliance needs.
  • Hybrid multi-cloud or air-gapped/on-premises deployments.
  • Teams desiring full control and willing to handle the operational aspects of state management.

How to Configure a Self-Managed Backend:

1. Create and secure your storage backend (e.g., S3 bucket, Azure container, or local directory).
2. Authenticate with your storage provider or ensure access permissions are set.
3. Run the appropriate login command, for example:
   • pulumi login s3://your-bucket/path
   • pulumi login azblob://your-container/path
   • pulumi login gs://your-bucket/path
   • pulumi login file://./your-directory
4. Initialize your stack, following any naming conventions required by your org:

   pulumi stack init myproject.prod

DIY Backend Pros and Cons:

A Self-Managed Backend is perfect when you want to own your data, integrate with specific enterprise workflows, or require infrastructure not handled by SaaS providers. However, you are responsible for every aspect of state protection and workflow.

The Local Backend allows you to store Pulumi state files directly on your own machine. It is a simple and fast option for experimentation, prototyping, and single-user workflows where collaboration and remote storage are not needed.

• Local State Storage: All stack state and checkpoint files are written to a specified directory on your local disk, using a file:// path. You control exactly where the data lives.
• Easy Initialization: Log in to the local backend using:
  • pulumi login --local
  • or
  • pulumi login file://./your-state-directory
  This command sets the local backend for all future Pulumi operations in the current context.
• Directory Structure: After logging in and running pulumi up or pulumi preview, Pulumi creates state files (with .json extensions) in your specified directory. Additional metadata files such as meta.yaml may also be present.
• Single-User Focused: This backend is designed for development, individual experimentation, or local CI/CD pipelines. It is not intended for use in multi-user or collaborative environments, as state sharing, locking, and backup must be managed manually.
• Security and Backups: Since state is stored only on your local machine, make sure to create your own backups and protect the directory appropriately. If your disk is lost or corrupted, your state may not be recoverable.
• Use Cases: The local backend is ideal for:
  • Quick testing and development on a laptop or workstation
  • Projects that do not require collaboration
  • Simple automation or disposable stacks in CI/CD jobs

How to Use the Local Backend:

1. Create a directory (e.g., ./state) where your Pulumi state files will be stored.
2. Log in using one of the following commands:
   • pulumi login --local
   • pulumi login file://./state
3. Run Pulumi CLI commands as usual; state is managed under your chosen directory.

Pros and Cons of the Local Backend:

The Local Backend is best when you need a lightweight, easy-to-use backend and don’t require team features, audit logging, or cloud-based recovery. Always consider making regular backups when using this mode to protect your infrastructure state.

Configuring a state backend in Pulumi determines where your infrastructure state is stored and who can access it. This process is crucial for enabling collaboration, managing security, and supporting your team's workflow. Here’s a step-by-step guide to get your backend configured for your projects.

1. Choose Your Backend Type:
   • Pulumi Cloud (default, fully-managed SaaS)
   • Self-Managed (DIY): AWS S3, Azure Blob, Google Cloud Storage, S3-compatible, or other supported platforms
   • Local Filesystem: Direct storage on your machine
2. Login to the Backend:
   • Run the pulumi login command for your chosen backend. The syntax is:
     • pulumi login   → Pulumi Cloud (default)
     • pulumi login s3://bucket-name/path   → AWS S3
     • pulumi login azblob://container/path   → Azure Blob
     • pulumi login gs://bucket/path   → Google Cloud Storage
     • pulumi login file://./state   → Local directory
     • pulumi login --local   → Default local backend
3. Verify Login:
   • The CLI will confirm your login and show which backend is active.
4. Initialize or Select a Stack:
   • To create a new stack:
     pulumi stack init myproject.prod
   • To use an existing stack:
     pulumi stack select myproject.prod
5. Advanced Configuration (Optional):
   • Set the backend URL in your project’s Pulumi.yaml file:

     backend:
       url: s3://bucket-name/path

   • Or set the PULUMI_BACKEND_URL environment variable for scripts and automation.

Best Practices:

• Choose a backend based on your organization’s ops model, team size, and compliance needs.
• For production use, enable backup and versioning on storage backends.
• Use unique stack names and avoid collisions across teams and environments.
• Ensure proper secrets encryption is configured for all non-Cloud backends.

Once configured, Pulumi will store each stack's state according to your backend selection, keeping your infrastructure state consistent and accessible where you need it.

Understanding how Pulumi stores and organizes its state files is essential for managing your infrastructure effectively—especially when using DIY or local backends. This section breaks down what happens behind the scenes and how to navigate the state files and metadata.

1. What Is in a State File?
   • A Pulumi state file contains a full snapshot of your current infrastructure, including resource names, types, inputs, outputs, and dependency graphs.
   • It also stores encrypted configuration values such as secrets—depending on the secrets provider configured.
   • The file format is JSON and is automatically updated on each successful deployment.
2. Default File Locations:
   • Pulumi Cloud: State is stored remotely in the managed backend and not written to your local disk.
   • Self-Managed / DIY: State is stored in your chosen storage backend (e.g., S3, Blob, GCS), typically under a path like:
   • s3://your-bucket-name/project-name/stack-name.json
   • Local Backend: Files are written to a local directory, such as:
   • ./state/myproject.dev.json
   • or in local default: ~/.pulumi
3. Directory Structure Example (Local Backend):

   ./state/
   ├── Pulumi.dev.yaml
   ├── myproject.dev.json
   ├── Pulumi.yaml
   └── .pulumi/
       ├── history/
       │   ├── checkpoint-1.json
       │   ├── checkpoint-2.json
       ├── meta.yaml
       └── meta.yaml.attrs

   • Pulumi.yaml – Project configuration
   • Pulumi.dev.yaml – Stack-specific configuration
   • myproject.dev.json – The actual state for the stack
   • .pulumi/meta.yaml – Metadata describing the backend and stack settings
4. Automatic Versioning:
   • Pulumi automatically saves checkpoints after every update or preview.
   • This enables you to recover from failures or roll back to previous states manually if needed (especially in local or DIY setups).
5. When to Manually Export or Import State:
   • When migrating between backends
   • When debugging corrupted stack files
   • When auditing or reviewing structure on disk

   pulumi stack export > state.json
   pulumi stack import < state.json

Key Considerations:

• Avoid manually editing state files unless necessary. Incorrect manual changes can corrupt your stack.
• Back up your state file regularly if you're using a local or DIY backend.
• Use clear naming conventions such as project.stack.json to avoid collisions.

State files are the foundation of Pulumi’s infrastructure-as-code workflow. Knowing where they live and how they work puts you in full control of deployment stability and recovery.

Switching from one Pulumi state backend to another—whether it's from Pulumi Cloud to a self-managed S3 bucket or from a local backend to Azure Blob—is fully supported and straightforward with the Pulumi CLI. This section walks you through a safe and controlled migration process, step by step.

1. Export the Current Stack State:
   Use the Pulumi CLI to export your current stack state into a local JSON file.

   pulumi stack export > stack-state.json

   This file contains the full definition of your infrastructure's state.
2. Login to the New Backend:
   Authenticate to the backend where you want to migrate your stack.
   • pulumi login s3://your-bucket/path
   • pulumi login azblob://your-container/path
   • pulumi login file://./new-state-dir
   • pulumi login (to use Pulumi Cloud)
3. Initialize or Import Your Stack into the New Backend:
   Create a new stack in the destination backend using the same name or a project-scoped version.

   pulumi stack init myproject.dev

   Or, if already initialized, just select it:

   pulumi stack select myproject.dev

4. Import the Exported State:
   Inject the JSON state file exported earlier.

   pulumi stack import < stack-state.json

   This restores your complete infrastructure snapshot into the new backend.
5. Verify and Test:
   Run a preview to ensure everything matches your expectations.

   pulumi preview

   Once confirmed, continue managing this stack using your new backend configuration.

Important Tips During Migration:

• Always backup your exported state file in a safe location before continuing with import operations.
• Avoid running pulumi up during a backend transition until you’ve confirmed the state was successfully imported.
• Migrated stacks may require reconfiguration of secrets providers depending on your backend type.
• After migration, update any automation pipelines or CI jobs to point to the new backend URL.

Stack Naming Note:

• When migrating to self-managed backends, consider using project-scoped stack names (e.g., myproject.dev) to prevent naming conflicts across backends.
• If you're not already using project-scoped stacks, you can enable it with:

  pulumi state upgrade

  Make sure this is done intentionally, as it permanently modifies the stack structure.

Migrating between backends allows you to adapt Pulumi to your team’s changing infrastructure, compliance, or workflow requirements. With a clean export and import process, it's easy to move and continue where you left off.

Successfully running Pulumi with a self-managed (DIY) backend lets you keep complete control over how state files are stored, secured, and recovered. Follow these best practices for reliable, secure, and scalable infrastructure management:

• Enable Encryption at Rest: Configure your storage backend (such as S3, Azure Blob, or GCS) to automatically encrypt state files using server-side encryption. For additional protection of secrets, set up and use a dedicated key management service (KMS, Key Vault, etc.).
• Turn on Versioning and Backups: Activate object versioning in your storage bucket or container to keep historical state copies. Regularly back up state files to another secure location to guard against accidental deletion or corruption.
• Harden Access Control: Use strict IAM roles, policies, and access-control lists to restrict who can read, modify, or delete state files. Grant only the minimum permissions necessary for users and automation systems.
• Adopt Consistent Naming Conventions: Namespace stack names with the project identifier (e.g., project-name.stack-name) to prevent collisions, especially when managing multiple projects or environments.
• Configure Locking/Concurrency Handling: Ensure only one update can happen to a stack at a time. For team environments, use file locking or serialized deployment pipelines to minimize risks of concurrent updates.
• Secure Secrets with an External Provider: Configure your stacks to use a dedicated secrets provider (like AWS KMS, Azure Key Vault, or GCP KMS) to ensure secrets are encrypted with enterprise-managed keys, not just passphrases.
• Monitor and Audit Usage: Enable audit logging on your storage backend and review access logs regularly. Integrate with SIEM solutions where appropriate.
• Automate Health Checks: Develop scripts or use monitoring solutions to regularly check the integrity and availability of state files and backups.
• Review & Rotate Keys and Credentials: Periodically rotate access keys, secrets, and service account credentials for heightened security and compliance.
• Test Disaster Recovery: Regularly simulate restores from backup to validate your recovery procedures for business continuity.

Summary Table: Essential Best Practices

By following these best practices, you'll ensure that your Pulumi self-managed backend is secure, compliant, reliable, and ready for scale or audit at any time.

At times, you may need to inspect, correct, or recover your Pulumi stack state—especially when dealing with advanced infrastructure changes or troubleshooting deployment errors. Here’s how you can safely approach editing and troubleshooting your stack state:

1. Inspecting State:
   • View the current state via the Pulumi CLI:

     pulumi stack export > stack.json

     Open stack.json in a text editor to review resources, configuration, and outputs. This helps diagnose unexpected resources or attributes.
   • For Pulumi Cloud, the web console can be used to inspect recent resource changes, deployments, and history.
2. Safely Editing State Files:
   • Manual edits to the exported stack.json may be necessary in rare circumstances, such as removing orphaned resources or correcting errors that block updates.
   • Always make a backup of your state file before editing. Invalid changes can corrupt the stack and prevent future updates.
   • Once changes are made, re-import the state:

     pulumi stack import < stack.json

   • Warning: Editing state files is recommended only for experienced users and as a last resort.
3. Common Troubleshooting Steps:
   • Orphaned or Failed Resources: If a resource shows up in state but no longer physically exists, export and edit the state to remove its entry, then re-import and re-run pulumi up.
   • Secret Decryption Errors: Double-check that you are using the correct secrets provider or passphrase. If the secrets provider changed, you may need to migrate or reconfigure it.
   • State File Conflicts: For self-managed and local backends, avoid concurrent updates. Use file-based locking or coordinate updates to prevent race conditions that corrupt state files.
   • Restore from Backups: If corruption occurs, you can roll back to a previous checkpoint by restoring an earlier state file or using built-in versioning in your storage backend.
4. Helpful CLI Commands:
   • pulumi state list — View all resources in the current state.
   • pulumi state delete urn — Remove a problematic resource by its URN.
   • pulumi state replace-provider — Swap the provider for resources in the state.

Best Practices When Editing or Troubleshooting State:

• Always review and back up existing state files before making changes.
• Use CLI commands for edits where possible, rather than hand-editing JSON.
• Thoroughly test deployments after any state edit to ensure infrastructure correctness is preserved.
• Document any manual interventions as part of your operations runbook.

If you're ever unsure, consider reaching out to your team or community support—careful state management is key to reliable and safe IaC workflows.

Pulumi is designed with a robust security model to protect your infrastructure state and sensitive information, whether you use the managed Pulumi Cloud or a self-managed backend. This section outlines the key principles and practical actions to keep your projects secure.

• State File Encryption: Pulumi encrypts secrets (such as passwords, tokens, or other sensitive config) within stack state files. With Pulumi Cloud, encryption at rest is enforced by default. For self-managed backends, encryption is available with either passphrases or external KMS solutions (like AWS KMS, Azure Key Vault, or Google Cloud KMS).
• Separation of Credentials: Pulumi never stores your cloud provider credentials in the state backend. Credentials are kept local to your machine or CI environment—outside of exported state and configuration files.
• Secure Communication: All communication between the Pulumi CLI and the backend (whether cloud or DIY) is encrypted in transit using TLS.
• Secrets Handling:
  • Mark any config you want encrypted as a secret (pulumi config set --secret MyKey MyValue).
  • Secrets are always encrypted in state and are never written out in plaintext, regardless of backend.
  • Additional control is available by integrating Pulumi with enterprise/organizational secret managers (KMS, Key Vault, etc.).
• Access Control:
  • Pulumi Cloud: Offers built-in RBAC, team permissions, and audit logging for strong access governance.
  • Self-Managed: You are responsible for securing object storage with IAM, ACLs, buckets, or directory access policies. Limit write access and monitor regularly.
• Compliance and Auditing: Pulumi Cloud undergoes third-party security audits (like SOC 2) and supports audit logging. For self-managed backends, set up backend-specific logging and review access as part of your compliance process.
• Backup and Recovery: Protect state files with versioning and regular automated backups, especially if using local or self-managed backends. Ensure backups are encrypted and stored securely.

Summary Table: Pulumi State Backend Security Features

Always protect your state backend with strong access controls, secrets management, and routine backups. For regulated or high-security environments, validate settings against your organizational security requirements, and consider periodic audits and testing of recovery procedures.