Every Pulumi program is deployed to a stack. A stack is an isolated, independently configurable instance of a Pulumi program. Stacks are commonly used to denote different phases of development (such as development, staging and production) or feature branches (such as feature-x-dev, jane-feature-x-dev).
Create a stack
To create a new stack, use
pulumi stack init stackName. This creates an empty stack
stackName and sets it as the active stack. The project that the stack is associated with is determined by finding the nearest
The stack name must be unique within a project. Stack names may only contain alphanumeric characters, hyphens, underscores, or periods.
$ pulumi stack init staging
If you are using Pulumi in your organization, by default the stack will be created in your user account. To target the organization, name the stack using
$ pulumi stack init broomllc/staging
Fully qualified stack names also include the project name, in the form
orgName/projectName/stackName, and this fully-qualified format is required in some contexts. In most contexts, the shorthands
stackName are valid and use the default organization and the current project context.
Note that while stacks with applied configuration settings will often be accompanied by
Pulumi.<stack-name>.yaml files, these files are not created by
pulumi stack init. They are created and managed with
To see the list of stacks associated with the current project (the nearest
Pulumi.yaml file), use
pulumi stack ls.
$ pulumi stack ls NAME LAST UPDATE RESOURCE COUNT jane-dev 4 hours ago 97 staging* n/a n/a test 2 weeks ago 121
Select a stack
destroy operate on the active stack. To change the active stack, run
pulumi stack select.
$ pulumi stack select jane-dev $ pulumi stack ls NAME LAST UPDATE RESOURCE COUNT jane-dev* 4 hours ago 97 staging n/a n/a test 2 weeks ago 121
To select a stack that is part of an organization, use the fully-qualified stack name, either
$ pulumi stack select acmecorp/prod $ pulumi stack ls NAME LAST UPDATE RESOURCE COUNT acmecorp/prod* 4 hours ago 97 acmecorp/staging 4 hours ago 97 dev n/a n/a
Deploy a project
To deploy your project to the currently selected stack, run
pulumi up. The operation uses the latest configuration values for the active stack.
Note: Your stack can distinguish between execution for preview versus for update by using pulumi.runtime.isDryRun().
View stack resources
To view details of the currently selected stack, run
pulumi stack with no arguments. This displays the metadata, resources and output properties associated with the stack.
$ pulumi stack Current stack is jane-dev: Last updated 1 week ago (2018-03-02 10:26:09.850357 -0800 PST) Pulumi version v0.11.0 Plugin nodejs [language] version 0.11.0 Plugin aws [resource] version 0.11.0 Current stack resources (3): TYPE NAME pulumi:pulumi:Stack webserver-jane-dev aws:ec2/securityGroup:SecurityGroup web-secgrp aws:ec2/instance:Instance web-server-www Current stack outputs (2): OUTPUT VALUE publicDns ec2-18-218-85-197.us-east-2.compute.amazonaws.com publicIp 22.214.171.124 Use `pulumi stack select` to change stack; `pulumi stack ls` lists known ones
View stack outputs
exports.publicDns = ... exports.publicIp = ...
$ pulumi stack output Current stack outputs (2): OUTPUT VALUE publicDns ec2-18-218-85-197.us-east-2.compute.amazonaws.com publicIp 126.96.36.199
The values of specific properties can also be retrieved directly, which is useful when writing scripts that use these output values.
$ pulumi stack output publicIp 188.8.131.52
See also Inter-Stack Dependencies, which allow one stack to reference the outputs of another stack.
Import and export a stack deployment
A stack can be exported to see the raw data associated with the stack. This is useful when manual changes need to be applied to the stack due to changes made in the target cloud platform that Pulumi is not aware of. The modified stack can then be imported to set the current state of the stack to the new values.
Note: This is a powerful capability that subverts the usual way that Pulumi manages resources and ensures immutable and repeatable infrastructure deployments. Importing an incorrect stack specification could lead to orphaning of cloud resources or the inability to make future updates to the stack. Use care when using the import and export capabilities.
$ pulumi stack export --file stack.json $ pulumi stack import --file stack.json
Delete a stack
To delete a stack with no resources, run
pulumi stack rm. Removing the stack will remove all stack history from pulumi.com and will delete the stack configuration file
If a stack still has resources associated with it, they must first be deleted via
pulumi destroy. This command uses the latest configuration values, rather than the ones that were last used when the program was deployed.
To force the deletion of a stack that still contains resources — potentially orphaning them — use
pulumi stack rm --force.
Stacks have associated metadata in the form of tags, with each tag consisting of a name and value. A set of built-in tags are automatically assigned and updated each time a stack is updated (such as
vcs:kind). To view a stack’s tags, run
pulumi stack tag ls.
Note: Stack tags are only supported when logged into the Pulumi Service backend.
Custom tags can be assigned to a stack by running
pulumi stack tag set <name> <value> and can be used to customize the grouping of stacks in the Pulumi Console. For example, if you have many projects with separate stacks for production, staging, and testing environments, it may be useful to group stacks by environment instead of by project. To do this, you could assign a custom tag named
environment to each stack. For example, running
pulumi stack tag set environment production assigns a custom
environment tag with a value of
production to the active stack. Once you’ve assigned an
environment tag to each stack, you’ll be able to group by
Tag: environment in the Pulumi Console.
Note: As a best practice, custom tags should not be prefixed with
vcs:to avoid conflicting with built-in tags that are assigned and updated with fresh values each time a stack is updated.
Tags can be deleted by running
pulumi stack tag rm <name>.