Pulumi Cheatsheet¶

Installation¶

Platform	Command
Linux (curl)	`curl -fsSL https://get.pulumi.com \\| sh`
macOS (Homebrew)	`brew install pulumi`
Windows (Chocolatey)	`choco install pulumi`
Windows (PowerShell)	`iex ((New-Object System.Net.WebClient).DownloadString('https://get.pulumi.com/install.ps1'))`
Docker	`docker pull pulumi/pulumi`
Python SDK	`pip install pulumi`
Node.js SDK	`npm install -g @pulumi/pulumi`
Verify Installation	`pulumi version`

Language Runtime Requirements¶

Language	Minimum Version	Provider Installation
Python	3.7+	`pip install pulumi-aws pulumi-azure-native`
Node.js/TypeScript	14.x+	`npm install @pulumi/aws @pulumi/azure-native`
Go	1.18+	`go get github.com/pulumi/pulumi-aws/sdk/v6/go/aws`
.NET/C#	6.0+	`dotnet add package Pulumi.Aws`

Basic Commands¶

Project Management¶

Command	Description
`pulumi new`	Create new project interactively
`pulumi new aws-typescript`	Create project from specific template
`pulumi new --list`	List all available templates
`pulumi new aws-python --name my-infra --yes`	Create project with name, skip prompts
`pulumi new https://github.com/user/template`	Create from custom template URL

Stack Operations¶

Command	Description
`pulumi stack ls`	List all stacks in current project
`pulumi stack init dev`	Create new stack named "dev"
`pulumi stack select dev`	Switch to "dev" stack
`pulumi stack`	Show current stack information
`pulumi stack output`	Display all stack outputs
`pulumi stack output bucketName`	Get specific output value
`pulumi stack output --json`	Export outputs as JSON
`pulumi stack rm dev`	Delete "dev" stack
`pulumi stack rename new-name`	Rename current stack
`pulumi stack --show-urns`	List resources with URNs

Configuration¶

Command	Description
`pulumi config`	List all configuration values
`pulumi config set aws:region us-west-2`	Set configuration value
`pulumi config set --secret dbPassword pass123`	Set encrypted secret value
`pulumi config get aws:region`	Get configuration value
`pulumi config rm instanceType`	Remove configuration value
`pulumi config set-all --plaintext < config.json`	Set config from file
`pulumi config cp dev staging`	Copy config between stacks

Deployment¶

Command	Description
`pulumi preview`	Preview changes without applying (dry run)
`pulumi preview --diff`	Show detailed resource differences
`pulumi up`	Deploy infrastructure changes
`pulumi up --yes`	Deploy without confirmation prompt
`pulumi up --parallel 10`	Deploy with 10 parallel operations
`pulumi destroy`	Destroy all resources in stack
`pulumi destroy --yes`	Destroy without confirmation
`pulumi refresh`	Sync state with actual cloud resources
`pulumi refresh --yes`	Refresh without confirmation
`pulumi cancel`	Cancel in-progress update

Authentication¶

Command	Description
`pulumi login`	Login to Pulumi Service (SaaS)
`pulumi login --access-token pul-abc123`	Login with access token
`pulumi login s3://my-bucket`	Use S3 as state backend
`pulumi login azblob://container`	Use Azure Blob as state backend
`pulumi login file://~/.pulumi/local`	Use local filesystem backend
`pulumi logout`	Logout from current backend
`pulumi whoami`	Show current logged-in user

Advanced Usage¶

Resource Targeting¶

Command	Description
`pulumi up --target urn:pulumi:dev::project::aws:s3/bucket:Bucket::my-bucket`	Deploy only specific resource
`pulumi destroy --target urn:pulumi:dev::project::aws:ec2/instance:Instance::web`	Destroy specific resource
`pulumi preview --target-dependents`	Preview resource and its dependents
`pulumi up --replace urn:pulumi:dev::project::aws:ec2/instance:Instance::web`	Force replacement of resource

State Management¶

Command	Description
`pulumi stack export --file backup.json`	Export stack state to file
`pulumi stack import --file backup.json`	Import stack state from file
`pulumi state delete`	Clear pending operations
`pulumi state unprotect urn:pulumi:dev::project::resource`	Remove protection from resource
`pulumi stack graph stack.dot`	Generate dependency graph (DOT format)
`pulumi history`	View stack update history

Policy as Code¶

Command	Description
`pulumi policy new aws-typescript`	Create new policy pack
`pulumi policy publish my-org/my-policy`	Publish policy pack to organization
`pulumi policy enable my-policy latest`	Enable policy pack for organization
`pulumi policy disable my-policy`	Disable policy pack
`pulumi policy ls`	List all policy packs
`pulumi up --policy-pack ./policies`	Run deployment with local policy pack
`pulumi preview --policy-pack ./policies`	Preview with policy enforcement

Logging and Debugging¶

Command	Description
`pulumi logs`	View logs from all resources
`pulumi logs --follow`	Stream logs in real-time
`pulumi logs --resource my-function`	Filter logs by resource name
`pulumi logs --since 2h`	Show logs from last 2 hours
`pulumi up --logtostderr -v=9`	Deploy with verbose debug logging
`pulumi up --suppress-outputs`	Hide sensitive output values

Secrets Management¶

Command	Description
`pulumi config set --secret apiKey sk-123`	Store encrypted secret
`pulumi config get --show-secrets`	Display decrypted secret values
`pulumi stack export --show-secrets`	Export state with decrypted secrets
`pulumi config refresh`	Re-encrypt secrets with new key

Organization Management¶

Command	Description
`pulumi org ls`	List all organizations
`pulumi org get-default`	Show default organization
`pulumi org set-default my-org`	Set default organization
`pulumi org create my-new-org`	Create new organization

Plugin Management¶

Command	Description
`pulumi plugin ls`	List installed plugins
`pulumi plugin install resource aws v5.0.0`	Install specific plugin version
`pulumi plugin rm resource aws v4.0.0`	Remove plugin version

Configuration¶

Pulumi.yaml (Project Configuration)¶

name: my-infrastructure
runtime: python
description: Production AWS infrastructure
backend:
  url: s3://my-pulumi-state-bucket

Pulumi.dev.yaml (Stack Configuration)¶

config:
  aws:region: us-west-2
  myproject:instanceType: t3.micro
  myproject:dbPassword:
    secure: AAABAHVzLXdlc3QtMg==  # Encrypted value
  myproject:environment: development
  myproject:enableMonitoring: "true"

Environment Variables¶

# Backend configuration
export PULUMI_BACKEND_URL=s3://my-bucket
export PULUMI_CONFIG_PASSPHRASE=mysecretkey

# AWS credentials
export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

# Pulumi Service
export PULUMI_ACCESS_TOKEN=pul-abc123def456

# Debugging
export PULUMI_DEBUG_COMMANDS=true
export PULUMI_DEBUG_PROMISE_LEAKS=true

.pulumi/ Directory Structure¶

.pulumi/
├── stacks/
│   ├── dev.json          # Stack-specific state
│   └── production.json
├── backups/              # Automatic state backups
└── plugins/              # Downloaded provider plugins

Common Use Cases¶

Use Case 1: Create AWS S3 Bucket with Python¶

# Initialize new project
pulumi new aws-python --name my-s3-project --yes

# Configure AWS region
pulumi config set aws:region us-east-1

# Edit __main__.py to add S3 bucket
cat > __main__.py << 'EOF'
import pulumi
import pulumi_aws as aws

bucket = aws.s3.Bucket('my-bucket',
    acl='private',
    versioning=aws.s3.BucketVersioningArgs(enabled=True),
    tags={'Environment': 'dev', 'Project': 'demo'}
)

pulumi.export('bucket_name', bucket.id)
pulumi.export('bucket_arn', bucket.arn)
EOF

# Preview and deploy
pulumi preview
pulumi up --yes

# Get bucket name
pulumi stack output bucket_name

Use Case 2: Multi-Stack Deployment (Dev/Staging/Prod)¶

# Create project
pulumi new aws-typescript --yes

# Create and configure dev stack
pulumi stack init dev
pulumi config set aws:region us-west-2
pulumi config set instanceType t3.micro
pulumi config set environment dev

# Create and configure staging stack
pulumi stack init staging
pulumi config set aws:region us-west-2
pulumi config set instanceType t3.small
pulumi config set environment staging

# Create and configure production stack
pulumi stack init production
pulumi config set aws:region us-east-1
pulumi config set instanceType t3.large
pulumi config set environment production

# Deploy to each environment
pulumi stack select dev && pulumi up --yes
pulumi stack select staging && pulumi up --yes
pulumi stack select production && pulumi up --yes

Use Case 3: Kubernetes Deployment with TypeScript¶

# Create Kubernetes project
pulumi new kubernetes-typescript --yes

# Configure kubeconfig
pulumi config set kubernetes:kubeconfig ~/.kube/config

# Create deployment (index.ts)
cat > index.ts << 'EOF'
import * as k8s from "@pulumi/kubernetes";

const appLabels = { app: "nginx" };
const deployment = new k8s.apps.v1.Deployment("nginx", {
    spec: {
        selector: { matchLabels: appLabels },
        replicas: 3,
        template: {
            metadata: { labels: appLabels },
            spec: { containers: [{ name: "nginx", image: "nginx:1.21" }] }
        }
    }
});

const service = new k8s.core.v1.Service("nginx", {
    spec: {
        type: "LoadBalancer",
        selector: appLabels,
        ports: [{ port: 80, targetPort: 80 }]
    }
});

export const serviceName = service.metadata.name;
export const serviceIP = service.status.loadBalancer.ingress[0].ip;
EOF

# Install dependencies and deploy
npm install
pulumi up --yes

Use Case 4: Infrastructure Testing¶

# Create project with testing
pulumi new aws-python --yes

# Install testing dependencies
pip install pytest pytest-mock

# Create test file (test_infrastructure.py)
cat > test_infrastructure.py << 'EOF'
import pulumi
import pytest

class MyMocks(pulumi.runtime.Mocks):
    def new_resource(self, args: pulumi.runtime.MockResourceArgs):
        return [args.name + '_id', args.inputs]
    def call(self, args: pulumi.runtime.MockCallArgs):
        return {}

pulumi.runtime.set_mocks(MyMocks())

# Import your infrastructure code
import __main__

@pulumi.runtime.test
def test_bucket_created():
    def check_bucket(args):
        assert args is not None
    return __main__.bucket.arn.apply(check_bucket)
EOF

# Run tests
pytest test_infrastructure.py

Use Case 5: State Migration Between Backends¶

# Export current state
pulumi stack export --file state-backup.json

# Login to new backend
pulumi login s3://new-state-bucket

# Create stack in new backend
pulumi stack init production

# Import state
pulumi stack import --file state-backup.json

# Verify migration
pulumi preview  # Should show no changes

# Update backend URL in Pulumi.yaml
cat > Pulumi.yaml << 'EOF'
name: my-project
runtime: python
backend:
  url: s3://new-state-bucket
EOF

Best Practices¶

Use Stack References: Share outputs between stacks with StackReference to create modular infrastructure. Example: ref = pulumi.StackReference("org/project/stack") then access ref.get_output("vpcId")
Leverage Configuration: Store environment-specific values in stack config files rather than hardcoding. Use pulumi config set for all variable values and --secret flag for sensitive data
Implement Resource Protection: Protect critical resources from accidental deletion with protect=True option. Use pulumi.ResourceOptions(protect=True) for databases, stateful resources
Version Control Everything: Commit Pulumi.yaml, stack config files, and code to git. Add .pulumi/ directory to .gitignore to exclude state and plugins
Use Component Resources: Create reusable infrastructure components by extending pulumi.ComponentResource. Package common patterns (VPC setup, EKS cluster) as components
Automate with CI/CD: Integrate Pulumi into pipelines using pulumi preview for PRs and pulumi up --yes for deployments. Use PULUMI_ACCESS_TOKEN environment variable for authentication
Tag All Resources: Apply consistent tagging strategy using tags parameter. Include environment, project, owner, cost-center for cost tracking and organization
Enable Policy as Code: Enforce organizational standards with policy packs. Validate resource configurations, naming conventions, and security requirements before deployment
Regular State Backups: Export stack state periodically with pulumi stack export. Store backups in version-controlled or secure storage separate from primary backend
Use Explicit Dependencies: When implicit dependencies aren't detected, use depends_on or pulumi.Output.all() to ensure correct resource ordering

Troubleshooting¶

Issue	Solution
Error: "no stack selected"	Run `pulumi stack select <stack-name>` or `pulumi stack init <new-stack>` to create/select a stack
Error: "conflict: Another update is currently in progress"	Run `pulumi cancel` to clear stuck update, or wait for other update to complete. Check `pulumi history` for details
Error: "failed to decrypt"	Ensure `PULUMI_CONFIG_PASSPHRASE` environment variable is set correctly. Run `pulumi config refresh` to re-encrypt with current passphrase
Provider plugin not found	Run `pulumi plugin install resource <provider> <version>` or delete `.pulumi/plugins/` and run `pulumi up` to auto-download
State file corruption	Restore from backup: `pulumi stack import --file backup.json`. Always keep recent backups with `pulumi stack export`
Resource already exists error	Import existing resource: `pulumi import <type> <name> <id>` or use `import` option in resource definition
Out of sync state	Run `pulumi refresh --yes` to sync state with actual cloud resources. Review changes before confirming
Secrets not decrypting	Verify backend access and encryption key. For Pulumi Service, check `PULUMI_ACCESS_TOKEN`. For self-managed, verify `PULUMI_CONFIG_PASSPHRASE`
Performance issues with large stacks	Increase parallelism: `pulumi up --parallel 20`. Split into multiple smaller stacks using stack references
"pulumi" command not found	Add Pulumi to PATH: `export PATH=$PATH:$HOME/.pulumi/bin` (Linux/macOS) or reinstall with package manager
TypeScript compilation errors	Run `npm install` to ensure dependencies are installed. Check `tsconfig.json` for correct configuration
Python import errors	Activate virtual environment and run `pip install -r requirements.txt`. Verify Python version is 3.7+

Quick Reference: Resource URNs¶

Resource URNs uniquely identify resources in format: urn:pulumi:<stack>::<project>::<type>::<name>

# Get URN from stack output
pulumi stack --show-urns

# Use URN for targeted operations
pulumi up --target urn:pulumi:dev::my-project::aws:s3/bucket:Bucket::my-bucket
pulumi state unprotect urn:pulumi:dev::my-project::aws:rds/instance:Instance::db

# Export specific resource details
pulumi stack export | jq '.deployment.resources[] | select(.urn | contains("my-bucket"))'

Quick Reference: Common Providers¶

Provider	Installation	Import Statement
AWS	`pip install pulumi-aws`	`import pulumi_aws as aws` (Python)
Azure	`pip install pulumi-azure-native`	`import pulumi_azure_native as azure`
GCP	`pip install pulumi-gcp`	`import pulumi_gcp as gcp`
Kubernetes	`npm install @pulumi/kubernetes`	`import * as k8s from "@pulumi/kubernetes"` (TS)
Docker	`pip install pulumi-docker`	`import pulumi_docker as docker`