Skip to content
Tutorials Center
My learning

Topics

Lesson 23 of 36 ยท State and Backends

Pulumi Backends and Login: Pulumi Cloud, Local Files and Object Storage

Choose where Pulumi stores state: Pulumi Cloud, local files, or your own S3, Azure Blob or Google Cloud Storage bucket. Learn pulumi login, locking, migration and secrets providers.

A backend is where Pulumi keeps stack state and, for some backends, history, locks, secrets keys and access control. You pick it with pulumi login, and the choice shapes your team workflow, your security model and your costs. You can change it later, so start with what suits you now.

The real backends need accounts and network access, so commands here are read-only. The runnable examples are stand-ins that model locking and URL parsing, the two parts that are pure logic.

The main backend types

Backend Login command State lives in Good for
Pulumi Cloud pulumi login Managed service Teams: history, RBAC, secrets, previews, Deployments
Local filesystem pulumi login --local or file://~ ~/.pulumi or a folder you choose Learning, solo work
Amazon S3 (and compatible) pulumi login s3://my-bucket Your bucket Self-managed on AWS, MinIO
Azure Blob Storage pulumi login azblob://container Your container Self-managed on Azure
Google Cloud Storage pulumi login gs://my-bucket Your bucket Self-managed on GCP
Another Pulumi Cloud URL pulumi login https://api.example.com Self-hosted service Enterprise installs

Check what you are logged in to with pulumi whoami -v. Credentials for the self-managed object-storage backends come from the usual cloud sources (AWS profile or environment variables, az login, application default credentials for GCP), so whoever can read and write the bucket can read and write state.

Terminal
pulumi login                       # Pulumi Cloud (opens browser or uses PULUMI_ACCESS_TOKEN)
pulumi login --local               # local files in ~/.pulumi
pulumi login file:///srv/pulumi    # local files in a folder you choose
pulumi login 's3://acme-pulumi-state?region=eu-central-1&awssdk=v2'
pulumi login 'azblob://pulumi-state'
pulumi login 'gs://acme-pulumi-state'
pulumi logout

Quote the URL in a shell, because ? and & have special meaning.

What the backend gives you

Pulumi Cloud (the default) adds: update history with who changed what, a console to browse resources, role-based access control, a managed secrets provider, audit logs, policy enforcement, drift detection and remote deployments. It stores state for you; a free individual tier exists.

Self-managed backends keep only the state files and lock files. You supply everything else: access control through bucket policies, backups through bucket versioning, and encryption of secrets through a passphrase or a cloud KMS key. In a self-managed bucket the layout looks like this:

TEXT
.pulumi/
  meta.yaml
  stacks/
    shop/
      dev.json
      prod.json
  backups/
  history/
  locks/

Turn on versioning for the bucket so a bad update cannot destroy the only copy of state, and give CI a role that can only touch that bucket.

Locking

Two people running pulumi up at the same time on the same stack would corrupt it. Pulumi prevents this with a lock: in Pulumi Cloud the service holds it; in object-storage backends a lock file is written under locks/. If a run is killed, the lock can be left behind and the next run reports that the stack is locked. After you are sure no update is running, pulumi cancel releases it for Pulumi Cloud; for self-managed backends the stale lock file is removed (the CLI prints which).

Node.js Stand-in: a file-lock protocol with a stale lock

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The real implementation differs (object stores have no TTL, so a stale lock file is removed by an explicit command), but the protocol is the same: one writer at a time, and a clear message for everyone else.

Secrets providers

Whatever backend you use, secrets are encrypted before they are written to state and config. The encryption key comes from the stack's secrets provider, chosen when the stack is created:

  • service (default on Pulumi Cloud): keys managed by the service.
  • passphrase: you set PULUMI_CONFIG_PASSPHRASE or PULUMI_CONFIG_PASSPHRASE_FILE. Default for local and self-managed backends.
  • Cloud KMS: awskms://alias/pulumi?region=eu-central-1, azurekeyvault://..., gcpkms://..., or hashivault://....
Terminal
pulumi stack init prod --secrets-provider="awskms://alias/pulumi?region=eu-central-1"
pulumi stack change-secrets-provider "passphrase"

Lose the passphrase or the KMS key and you lose the ability to read your secrets. Store the passphrase in a password manager and in CI secrets.

Migrating between backends

Moving from local files to Pulumi Cloud (or between buckets) uses export and import, one stack at a time:

Terminal
pulumi login --local
pulumi stack select dev
pulumi stack export --show-secrets --file dev.json   # plaintext secrets: handle with care

pulumi login                                         # new backend
pulumi stack init dev
pulumi stack import --file dev.json
pulumi preview                                       # should show no changes
rm dev.json

Alternatively, pulumi state plus a cloud console migration tool can move many stacks, and Pulumi Cloud offers a guided "migrate to Pulumi Cloud" flow. The test after any migration is the same: pulumi preview must show no changes.

Parsing a backend URL

The ? options in object-storage URLs matter (region, endpoint for S3-compatible storage such as MinIO, the AWS SDK version). This stand-in parses a backend URL into its parts, as a quick way to see what you typed.

Node.js Stand-in: reading a backend URL

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Choosing a backend

  • Solo and learning: local files; no account needed. Back up the folder.
  • Teams: Pulumi Cloud, for history, access control and secrets without building them.
  • Compliance or "no SaaS" rules: object storage with versioning, KMS secrets and bucket policies, or a self-hosted Pulumi Cloud.
  • Whatever you choose: stack names and the project name identify state, so keep them stable, and restrict who can write the state store, because write access to state means influence over your infrastructure.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command stores state in an S3 bucket?

    pulumi login with an s3:// URL selects the S3 backend.
  2. 2. What should you enable on a self-managed state bucket so a bad update cannot destroy the only copy?

    Bucket versioning keeps previous object versions, so you can restore an earlier checkpoint.
  3. 3. After migrating a stack to a new backend, what check confirms the move worked?

    If state moved correctly, the program matches it and the preview is empty.
  4. 4. You use the passphrase secrets provider and lose the passphrase. What happens?

    The passphrase derives the encryption key; without it the encrypted values are unreadable.

Summary

  • pulumi login selects the backend: Pulumi Cloud, local files, or S3, Azure Blob and GCS buckets.
  • Pulumi Cloud adds history, access control, audits and managed secrets; self-managed backends need you to supply versioning, access control and key management.
  • A lock allows one update per stack at a time; stale locks are cleared with explicit commands once you are sure nobody is running.
  • Secrets providers (service, passphrase, cloud KMS) decide who can decrypt secrets; protect the key.
  • Migrate with stack export and stack import, then confirm with an empty preview.

Next: Refresh and Drift: When the Cloud Changes Behind Pulumi's Back