What is Stack in Pulumi?

• A stack is an isolated, independently configurable instance of a Pulumi program
• A single instance of all of your cloud resources you defined in your Pulumi program
• Stacks are commonly used to denote different “phases of development” / “environments” (Dev, QA, Staging, Prod))
• When pulumi up command is run from within project directory, a stack is created with the current stack name (similar to git commit in current branch)
• Each project is a collection of code, and that each stack is a unit of deployment
• A project can have as many stacks as you need
• More details: https://www.pulumi.com/docs/intro/concepts/stack/

Stack Naming

• The stack name must be unique within a project
• Allowed character in Stack name:
  • alphanumeric characters
  • hyphens
  • underscores
  • periods
• Fully-qualified Stack naming format: <orgName>/<projectName>/<stackName>
  • Fully-qualified format is required in some contexts
  • In most contexts the shorthands <orgName>/<stackName> or <stackName> are valid and use the default organization and the current project context

Default Stack
While creating new project with ‘pulumi new’ command, if you do not specify stack name, default stack name ‘dev’ will be selected.

Stack naming limitation when using local or cloud backend

• Recommended naming convention “<orgName>/<projectName>/<stackName>“ will not work for local and cloud backend (i.e. Azure blod container)
• See: Troubleshooting - error: stack names may not contain slashes

Stack Configuration File

• Each Stack is accompanied by a file named “Pulumi.<stackName>.yaml” that contains the configuration specific to this stack.
• Stack configuration file typically resides in the root of the project directory
• “pulumi stack init ...” command does not create Stack configuration file
  • Manually create Stack specific configuration (yaml) files
  • Manage configurations manually of using “pulumi config” CLI commands
• See Stack Configuration Details

Creating Stack

• pulumi stack init <stackName>
  • Creates an empty stack
  • Sets it as the active stack
• The project that “the newly created stack will be associated with” is determined by finding the nearest Pulumi.yaml file

#
# cd pulumi/project/root-folder (in which Pulumi.yaml file is located)
#
#
pulumi stack init <stackName>
pulumi stack init <projName>/dev-test
pulumi stack init <orgName>/pulumi-renshu/dev-test

Secrets Provider

• By default, a stack created using the pulumi.com backend will use the pulumi.com secrets provider
• A stack created using the local or cloud object storage backend will use the passphrase secrets provider
• A different secrets provider can be selected by passing the –secrets-provider flag

pulumi stack init QA # pulumi.com backend


# local or cloud backend with passphrase (key) for Pulumi secrets
pulumi stack init QA --secrets-provider=passphrase 


# Azure blob container backend with Azure KeyVault key for Pulumi secrets
# pulumi login azblob://pulumi-backend-container
# pulumi stack init QA --secrets-provider="azurekeyvault://mykeyvaultname.vault.azure.net/keys/mykeyname"
pulumi stack init dev --secrets-provider="azurekeyvault://xxx-pulumibackend-kv.vault.azure.net/keys/pulumi-secret-key"

See: https://www.pulumi.com/docs/reference/cli/pulumi_stack_init/

Current Stack and Selecting Target Stack

• Current Stack is similar to current Git branch
• pulumi stack select <stackName> (Fully qualified stack name: pulumi stack select <orgName/projectName/stackName>):
  • Sets “stackName” as current stack
  • If selected stack does not exist yet:
    • pulumi stack select <stackName> --create
    • pulumi stack select <stackName> -c
• Stack name when using “pulumi up” command:
  • pulumi up: uses current stack (since stack name is not mentioned explicitly)
  • Selecting target stack (by explicitly mentioning stack name):
    • pulumi up --stack <stackName>
    • pulumi up -s <stackName>
  • As a best practice, always use “-s” or “--stack” flag to explicitly menion target stack name (to avoid mistakes)

Stack State

• What is Stack State? : Pulumi stores metadata about infrastructure so that it can manage the corresponding cloud resources. This metadata is called State (Stack State)
• Each stack has its own state, and state is how Pulumi knows when and how to create, read, delete, or update cloud resources.
• Pulumi stores Stack State in a backend (Pulumi Service, Azure Storage Blob Container, local filesystem etc.)

Satck State Backend

See Stack State Backend Details

Deploying Stack (Deploying a Project)

• Use pulumi up <orgName/projectName/stackName> command
• Compiles code updates target stack state
• Uses the latest configuration values for the target stack

Listing Stacks

• pulumi stack ls: only stacks with the same project name as the current workspace will be returned
• pulumi stack ls --all : all stacks you have access to will be listed.
• See: https://www.pulumi.com/docs/reference/cli/pulumi_stack_ls/#options

View Stack Resources

Use “pulumi stack” with no arguments

• Displays the metadata and resources
• Displays output properties associated with the stack

Stack Tags

• Stacks have associated metadata in the form of tags (each tag consisting of a name and value)
• Stack tags are only supported with the Pulumi Service as “Stack State Backend”
• A set of built-in tags (i.e. pulumi:project, pulumi:runtime) are automatically assigned and updated each time a stack is updated
• Custom tags can be assigned to a stack by running “pulumi stack tag set <name> <value>” command
• To remove tag: pulumi stack tag rm <name>

Stack Outputs

https://www.pulumi.com/docs/intro/concepts/stack/#outputs

Removing Stack

• pulumi stack rm <stack-name>:
  • Removes stack and its configuration (Pulumi.<stack-name>.yaml)
  • Stack resources (infrastructure and applications) will remian in the cloud. To remove Stack resources, use “pulumi destroy ...” command
• See:
  • Stack Remove vs Pulumi Destroy
  • https://www.pulumi.com/docs/reference/cli/pulumi_stack_rm/#options