Pulumi IaC CLI

Pulumi cheatsheet — deploy infrastructure with code. pulumi up, pulumi preview, pulumi destroy, pulumi stack, pulumi config. IaC in Python, TypeScript, Go. Full reference.

7 min read

What it is

Pulumi is an Infrastructure as Code (IaC) tool that allows you to define and manage cloud infrastructure using familiar programming languages like Python, Go, TypeScript, C#, and Java. You reach for Pulumi when you want to provision, update, and delete cloud resources programmatically, with the benefits of code versioning, testing, and reuse.

Installation

Linux

curl -fsSL https://get.pulumi.com | sh

macOS

curl -fsSL https://get.pulumi.com | sh

Windows

Set-ExecutionPolicy -Scope CurrentUser -Unrestricted; iex (New-Object System.Net.WebClient).DownloadString('https://get.pulumi.com/install.ps1')

Verifying Installation

pulumi version

Core Concepts

  • Pulumi Project: A directory containing your infrastructure code, a Pulumi.<stack-name>.yaml file, and a package.json (or equivalent for other languages) file.
  • Pulumi Stack: An isolated instance of your infrastructure. A single project can have multiple stacks (e.g., dev, staging, prod) for different environments. Each stack has its own configuration values.
  • Pulumi Program: The actual code written in a supported language that defines your infrastructure resources.
  • State File: Pulumi tracks the state of your deployed infrastructure in a state file. This allows Pulumi to understand what resources it manages and how to update them. By default, state is stored in the Pulumi Service, but can be configured to use other backends like S3, GCS, or Azure Blob Storage.

Commands / Usage

Project Management

  • Initialize a new project:

    pulumi new aws-python

    Creates a new Pulumi project with a starter template for AWS using Python. Other templates include azure-typescript, gcp-go, kubernetes-yaml, etc.

  • List available project templates:

    pulumi new --list

    Shows all available project templates for pulumi new.

  • Login to the Pulumi Service:

    pulumi login

    Logs into the Pulumi Service (default backend) using your browser. You can also specify a backend like pulumi login s3://my-bucket-name.

  • Logout from the Pulumi Service:

    pulumi logout

    Logs out of the Pulumi Service.

Stack Management

  • Select a stack:

    pulumi stack select dev

    Selects the dev stack for the current project. If the stack doesn’t exist, it will be created.

  • Create a new stack:

    pulumi stack init prod

    Creates a new stack named prod for the current project.

  • List available stacks:

    pulumi stack ls

    Lists all stacks available for the current project.

  • Remove a stack:

    pulumi stack rm staging

    Removes the staging stack. This will destroy all resources managed by that stack.

  • Export stack outputs:

    pulumi stack output

    Outputs all exported values from the current stack.

    pulumi stack output instanceId

    Outputs the specific value of the instanceId export from the current stack.

  • Set stack configuration values:

    pulumi config set aws:region us-west-2

    Sets the aws:region configuration value for the current stack to us-west-2.

    pulumi config set --secret databasePassword mysecretpassword

    Sets a secret configuration value for databasePassword. This value will be encrypted.

  • Get stack configuration values:

    pulumi config get aws:region

    Retrieves the value of the aws:region configuration.

    pulumi config get --show-secrets databasePassword

    Retrieves the decrypted value of the secret databasePassword.

  • List stack configuration:

    pulumi config

    Lists all configuration values for the current stack.

  • Remove stack configuration values:

    pulumi config rm aws:region

    Removes the aws:region configuration value.

Deployment

  • Preview infrastructure changes:

    pulumi preview

    Shows what changes Pulumi will make to your infrastructure without actually applying them.

  • Deploy infrastructure changes:

    pulumi up

    Provisions and updates your infrastructure according to your Pulumi program. It will prompt for confirmation after showing a preview.

    pulumi up --yes

    Applies the changes without prompting for confirmation.

  • Destroy infrastructure:

    pulumi destroy

    Removes all resources managed by the current stack. It will prompt for confirmation after showing a preview.

    pulumi destroy --yes

    Destroys all resources without prompting for confirmation.

  • Update specific resources:

    pulumi up --target aws:s3/bucket:Bucket my-bucket

    Updates only the specified resource (my-bucket of type aws:s3/bucket:Bucket) and its dependencies.

  • Refresh the stack’s state:

    pulumi refresh

    Updates the Pulumi state to reflect the actual current state of the cloud resources. This is useful if resources were modified outside of Pulumi.

Importing Resources

  • Import existing resources into the Pulumi state:
    pulumi import aws:s3/bucket:Bucket my-bucket arn:aws:s3:::my-existing-bucket
    Imports an existing AWS S3 bucket into the Pulumi state, aliasing it as my-bucket in your code. You must have a resource declaration for my-bucket in your Pulumi program.

Plugin Management

  • Install plugins:

    pulumi plugin install resource aws v4.0.0

    Manually installs the AWS provider plugin version 4.0.0. Pulumi usually installs these automatically.

  • List installed plugins:

    pulumi plugin ls

    Lists all Pulumi plugins installed on your system.

  • Update plugins:

    pulumi plugin update

    Checks for and installs newer versions of installed plugins.

Other Utilities

  • Get Pulumi CLI version:

    pulumi version

    Displays the current version of the Pulumi CLI.

  • Get Pulumi version and provider versions:

    pulumi about

    Shows detailed information about your Pulumi CLI version, installed plugins, and project configuration.

  • Login to a different backend:

    pulumi login file://~/.pulumi/backups

    Configures Pulumi to use a local directory as the state backend. Other options include s3://, gs://, azure://.

  • Set the state backend:

    pulumi backend set s3://my-state-bucket/my-project-state

    Configures the current project to use the specified S3 bucket as its state backend.

Common Patterns

  • Setting up a new project and deploying:

    pulumi new aws-python  # Choose your preferred cloud and language
cd my-aws-python-project
pulumi stack init dev
pulumi config set aws:region us-east-1
pulumi up

    Initializes a new project, sets the region, and deploys it.

  • Deploying to multiple environments:

    # In the 'prod' stack
pulumi stack select prod
pulumi config set aws:region us-west-2
pulumi up --yes

# In the 'staging' stack
pulumi stack select staging
pulumi config set aws:region us-east-1
pulumi up --yes

    Manages separate environments using different stacks and configurations.

  • Exporting and using outputs in another stack or script: In my-app/Pulumi.yaml:

    # ... resource definitions ...
pulumi.export('instance_id', my_instance.id)
pulumi.export('instance_public_ip', my_instance.public_ip)

    In another script or stack:

    # Get the instance ID from the 'dev' stack
DEV_INSTANCE_ID=$(pulumi stack output --stack dev instance_id)
echo "The instance ID for dev is: $DEV_INSTANCE_ID"

    Allows sharing infrastructure outputs between different parts of your infrastructure or external scripts.

  • Destroying specific resources and their dependencies:

    pulumi preview --target-dependents aws:ec2/instance:Instance my-instance
pulumi destroy --target aws:ec2/instance:Instance my-instance

    Destroys a specific resource and any resources that depend on it.

  • Using Pulumi with CI/CD (e.g., GitHub Actions):

    - name: Pulumi Deploy
  uses: pulumi/actions@v3
  with:
    command: up

{% raw %} stack-name: ${{ secrets.PULUMI_STACK_NAME }} {% endraw %} # Requires PULUMI_ACCESS_TOKEN to be set in secrets ``` Integrates Pulumi deployments into automated pipelines.

  • Managing secrets securely:
    pulumi config set --secret db.password "my-super-secret-password"
# This password is now encrypted in the Pulumi state file.
    Ensures sensitive configuration values are encrypted at rest.

Gotchas

  • State File Management: Losing your Pulumi state file means Pulumi can no longer manage your infrastructure. Ensure your state backend is configured correctly and is durable (e.g., S3 with versioning, GCS bucket).
  • Resource Drift: If infrastructure resources are modified outside of Pulumi (manually or by other tools), the Pulumi state will be out of sync. Running pulumi refresh can help, but manual intervention might be needed.
  • Provider Versions: Ensure your provider versions (e.g., aws, azure, kubernetes) are compatible. Mismatched versions can lead to unexpected behavior or deployment failures. Use pulumi about to check versions.
  • Secret Management: While pulumi config set --secret encrypts values in the state file, the decryption key is often managed by the Pulumi Service or requires access to the Pulumi CLI environment. For highly sensitive secrets, consider integrating with dedicated secret managers (e.g., AWS Secrets Manager, HashiCorp Vault) and referencing those secrets in your Pulumi code.
  • pulumi up --yes in Production: Be extremely cautious when using --yes in production environments. Always review pulumi preview output before applying changes to critical infrastructure.
  • Stack Configuration Inheritance: Stack configuration is hierarchical. Values set at the stack level override project-level defaults. Be mindful of where configuration is set.
  • Resource Aliasing: When renaming or moving resources within your Pulumi code, use aliasing to ensure Pulumi doesn’t destroy and recreate the resource.
    old_name_resource = aws.s3.Bucket("oldName", ...)
new_name_resource = aws.s3.Bucket("newName", ...,
    opts=pulumi.ResourceOptions(aliases=[aws.s3.Bucket("oldName")]))