These are the essential building blocks that define and operate a Pulumi Stack effectively:

• Pulumi Program: The infrastructure as code (IaC) logic written using Pulumi-supported languages such as TypeScript, Python, Go, or .NET. Each stack runs a Pulumi program independently, which determines the resources it creates.
• Stack Configuration: Key-value pairs specific to a stack, such as region, resource limits, or credentials. These help customize the behavior of the stack without modifying the code. Sensitive data can be encrypted using the secrets manager.
• Stack State: The saved snapshot of currently deployed resources and their properties. This enables Pulumi to identify and apply only the necessary changes during updates, ensuring efficient and reliable deployments.
• Secrets Provider: Manages encryption of sensitive configuration values such as API keys or passwords. Pulumi supports multiple providers including cloud-native KMS solutions and the Pulumi Service.
• Stack Outputs: Named values exported from the Pulumi program at runtime—such as IP addresses, DNS names, or IDs. These outputs can be referenced by other stacks or consumed by CI/CD pipelines.
• Backend Provider: Determines where stack state is stored—local folder, cloud storage bucket, or the Pulumi Service. This setup dictates collaboration capabilities and backup strategies.

Stack operations are essential Pulumi CLI commands used to manage the life cycle of a stack — from creation to teardown. These operations help control your deployment environments safely and efficiently.

• pulumi stack init <name>: Initializes a new stack with its own state and configuration. This is typically done for new environments like dev, stage, or prod.
• pulumi stack select <name>: Switches between existing stacks in your current project. Useful when working on multiple environments or configurations.
• pulumi up: Applies infrastructure changes defined in your Pulumi program. It provisions, updates, or deletes cloud resources in a safe and trackable way.
• pulumi preview: Shows what changes will be made by pulumi up without actually performing them. Helps validate the intent before deploying.
• pulumi stack output [name]: Retrieves specific output values from the currently selected stack. These can be used in scripts or chained deployments.
• pulumi destroy: Deletes all resources that were provisioned by the stack, but retains the stack itself and its configuration.
• pulumi stack rm <name>: Permanently removes a stack and optionally deletes its state. Use with caution — this action is irreversible.
• pulumi refresh: Re-syncs the Pulumi state file by inspecting the actual infrastructure. This is used to correct drift caused by external changes.
• pulumi stack export / import: Allows backup or migration of stack state. export creates a JSON snapshot, and import can restore it later.

Stack Configuration allows each Pulumi stack to behave differently by passing in key-value pairs that parameterize its behavior. These values allow separation between code and environment-specific settings.

• Plain Text Values: Regular configuration options used to set parameters like cloud region, instance sizes, or feature toggles. Example:

  pulumi config set aws:region us-west-2

• Secret Values: Sensitive configuration inputs such as API keys, passwords, or tokens. These values are encrypted and decrypted automatically using a selected secrets provider.

  pulumi config set dbPassword MyS3cret123 --secret

• Configuration Files: Pulumi stores configuration in YAML files named after the stack (e.g. Pulumi.dev.yaml), making it easy to review and version control.
• CLI Commands: Common configuration management commands include:
  • pulumi config set <key> <value> – Add or update a config value
  • pulumi config get <key> – Read a config value
  • pulumi config rm <key> – Remove a config key
  • --secret – Designate a value as encrypted
• Use Case Example: You can define a different database password or Azure region per stack (e.g. dev, staging, prod) without duplicating your Pulumi code:

  pulumi config set database:password --secret

Stack outputs are runtime-exported values from a Pulumi stack. They expose important information that can be consumed by other stacks, scripts, or systems after deployment completes.

• What Are Outputs? Outputs are named values that a Pulumi program returns after the infrastructure has been provisioned. Examples include endpoint URLs, IP addresses, security group IDs, and ARNs.
• Common Use Cases:
  • Share a VPC ID from a networking stack to an app stack
  • Expose S3 bucket URLs to CI/CD pipelines
  • Reference database connection strings in deployment scripts
• How to Define Outputs: Add export statements inside your Pulumi code. Example in TypeScript:

  export const bucketUrl = myBucket.websiteEndpoint;

  Or in Python:

  pulumi.export("db_endpoint", my_db.endpoint)

• Fetching Outputs via CLI: Use the CLI command to retrieve an output value:

  pulumi stack output bucketUrl

• Referencing Outputs from Another Stack: Use a StackReference to retrieve outputs between stacks. Example in Python:

  
  from pulumi import StackReference
  network_stack = StackReference("org/project/network-stack")
  vpc_id = network_stack.get_output("vpcId")
      

Stack References in Pulumi allow one stack to programmatically access the outputs of another stack. This mechanism is useful to create dependencies between stacks, enabling modular and reusable infrastructure across separate projects or environments.

• What is a Stack Reference? A Stack Reference is a Pulumi construct that lets a stack read exported output values from another stack by specifying the fully qualified stack name (including organization, project, and stack).
• Usage Scenario: When you have multiple related stacks—such as one managing networking and another deploying applications—you can have the application stack reference outputs like VPC IDs or subnet IDs from the networking stack.
• Creating a Stack Reference: To create a reference to another stack, instantiate a StackReference by passing the full stack name:

  // TypeScript or JavaScript
  const network = new pulumi.StackReference("org/project/network-stack");
  

  # Python
  from pulumi import StackReference
  network = StackReference("org/project/network-stack")
  

• Accessing Outputs: Use the getOutput method to retrieve specific output values:

  // TypeScript
  const vpcId = network.getOutput("vpcId");
  

  # Python
  vpc_id = network.get_output("vpcId")
  

• Benefits:
  • Enables clean separation of infrastructure into modular stacks
  • Supports environment-specific configurations via isolated stack names
  • Allows cascading updates between dependent layers (e.g. networking → apps)
• Best Practices:
  • Reference only the outputs you need to reduce tight coupling
  • Use stack configuration to dynamically pass in the name of referenced stacks
  • Keep stacks small, reusable, and environment-aware
• Example Usage in Python:

  
  from pulumi import StackReference
  
  network_stack = StackReference("org/project/network-stack")
  vpc_id = network_stack.get_output("vpcId")
  
  # Use vpc_id in your Pulumi program for dependent resources
  

Working with multiple stacks and environments sometimes leads to errors or unexpected behavior. Below are common issues and how to troubleshoot them effectively.

• Stack Already Exists: This occurs when trying to create a stack that has already been initialized. Use:

  pulumi stack select <stack-name>

  to switch to the existing stack instead of creating a new one.
• Secrets Not Decryptable: If Pulumi can't decrypt secrets (e.g., after moving to a new machine), ensure you're using the correct secrets provider configuration or passphrase. You may need to restore access to the original encryption key or provider.
• Corrupted or Missing State: When the state file becomes invalid or deleted, try restoring it from a backup using:

  pulumi stack import --file state.json

  If using the Pulumi Service backend, history may offer a rollback option.
• Stack Drift: When someone modifies infrastructure outside of Pulumi, the Pulumi state becomes out of sync. To reconcile the internal state with reality, run:

  pulumi refresh

• Locked State File: A failed or interrupted update can leave the stack's state locked. Wait a few minutes or remove the lock through your backend provider if applicable.
• Unexpected Preview Changes: If pulumi preview shows changes you weren’t expecting, double-check config values, state versions, and inline logic that may differ between environments.
• Invalid Configuration Keys: Misspelled or missing config values can lead to runtime errors. View all current settings using:

  pulumi config

  Or inspect the config YAML file for accuracy.

This section provides a quick-reference summary of the most commonly used Pulumi stack commands for managing infrastructure deployments.

• pulumi stack init <name>: Initializes a new stack with its own configuration and state file.
• pulumi stack select <name>: Switches the current working context to the specified stack.
• pulumi stack ls: Lists all stacks for the current project, along with their associated backend and default status.
• pulumi up: Creates or updates cloud infrastructure as defined in your Pulumi program.
• pulumi preview: Displays a preview of the changes that pulumi up would apply—useful for review before execution.
• pulumi destroy: Tears down all resources managed by the selected stack but retains stack metadata.
• pulumi stack output [name]: Retrieves the value of a specific output defined in your Pulumi program.
• pulumi config: Displays or updates stack configuration values. Add --secret to store encrypted secrets.
• pulumi refresh: Syncs the Pulumi state with the actual cloud resources by performing a read-only check.
• pulumi stack rm <name>: Permanently deletes the specified stack and optionally its state file. Irreversible.