Stacks
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
).
A project can have as many stacks as you need. By default, Pulumi creates a stack for you when you start a new project using the pulumi new
command.
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 Pulumi.yaml
file.
The stack name must be unique within a project. Stack names may only contain alphanumeric characters, hyphens, underscores, or periods.
$ pulumi stack init staging
The stack name is specified in one of the following formats:
stackName
: Identifies the stackstackName
in the current user account or default organization, and the project specified by the nearestPulumi.yaml
project file.orgName/stackName
: Identifies the stackstackName
in the organizationorgName
, and the project specified by the nearestPulumi.yaml
project file.orgName/projectName/stackName
: Identifies the stackstackName
in the organizationorgName
and the projectprojectName
.projectName
must match the project specified by the nearestPulumi.yaml
project file.
For self-managed backends, the orgName
portion of the stack name must always be the constant value organization
.
Additionally, backends initialized with a Pulumi CLI older than v3.61.0 support only the first format (stackName
). You can upgrade these to support the other formats with the pulumi state upgrade
command. See State > Scoping for more details.
Given the stack my-org/my-project/dev
, the following are all equivalent if the current organization is my-org
and the current project is my-project
:
my-org/my-project/dev
my-org/dev
dev
In some contexts, stack names will be presented in their fully-qualified format (orgName/projectName/stackName
) even if provided using shorthand (stackName
or orgName/stackName
) as input.
Pulumi.<stack-name>.yaml
files, these files are not created by pulumi stack init
. They are created and managed with pulumi config
. For information on how to populate your stack configuration files, see Configuration.Listing stacks
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
broomellc/test 2 weeks ago 121
Stack names in the listing will be partially qualified if they are associated with an organization or project different from the default for the context.
Select a stack
The top-level pulumi
operations config
, preview
, update
and 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
broomellc/test 2 weeks ago 121
To select a stack that is part of an organization, use the fully-qualified stack name, either orgName/stackName
or orgName/projectName/stackName
:
$ pulumi stack select mycompany/prod
$ pulumi stack ls
NAME LAST UPDATE RESOURCE COUNT
mycompany/prod* 4 hours ago 97
mycompany/staging 4 hours ago 97
dev n/a n/a
Generate an update plan
--help
if the environment variable PULUMI_EXPERIMENTAL
is set to true
.To preview an update of the currently selected stack and save that plan run pulumi preview --save-plan=plan.json
. The operation uses the latest configuration values for the active stack.
preview
and update
operations by using pulumi.runtime.isDryRun().Update a stack
To update the currently selected stack, run pulumi up
. If you saved a plan from a preview you can pass that in to constrain the update to only doing what was planned with pulumi up --plan=plan.json
. The operation uses the latest configuration values for the active stack.
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 18.218.85.197
Use `pulumi stack select` to change stack; `pulumi stack ls` lists known ones
Stack tags
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 pulumi:project
, pulumi:runtime
, pulumi:description
, gitHub:owner
, gitHub:repo
, vcs:owner
, vcs:repo
, and vcs:kind
). To view a stack’s tags, run pulumi stack tag ls
.
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 Cloud. 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 Cloud.
As a best practice, custom tags should not be prefixed with pulumi:
, gitHub:
, or 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>
.
Stack outputs
A stack can export values as stack outputs. These outputs are shown during an update, can be easily retrieved with the Pulumi CLI, and are displayed in Pulumi Cloud. They can be used for important values like resource IDs, computed IP addresses, and DNS names.
To export values from a stack, use the following definition in the top-level of the entrypoint for your project:
exports.url = resource.url;
export let url = resource.url;
pulumi.export("url", resource.url)
ctx.Export("url", resource.Url)
public class MyStack : Stack
{
public MyStack()
{
...
this.Url = resource.Url;
}
// 'url' is the output name. By default, it would take the property name 'Url'.
[Output("url")] public Output<string> Url { get; set; }
}
public class App {
public static void main(String[] args) {
Pulumi.run(App::stack);
}
public static void stack(Context ctx) {
ctx.export("url", resource.url());
}
}
outputs:
url: ${resource.url}
From the CLI, you can then use pulumi stack output url
to get the value and incorporate into other scripts or tools.
The value of a stack export can be a regular value, an Output, or a Promise
(effectively, the same as an Input). The actual values are resolved after pulumi up
completes.
Stack exports are effectively JSON serialized, though quotes are removed when exporting strings.
For example, the following statements:
exports.x = "hello"
exports.o = {num: 42}
export let x = "hello";
export let o = {num: 42};
pulumi.export("x", "hello")
pulumi.export("o", {'num': 42})
ctx.Export("x", pulumi.String("hello"))
ctx.Export("o", pulumi.Map(map[string]pulumi.Input{
"num": pulumi.Int(42),
}))
class MyStack : Stack
{
[Output] public Output<string> x { get; set; }
[Output] public Output<ImmutableDictionary<string, int>> o { get; set; }
public MyStack()
{
this.x = Output.Create("hello");
this.o = Output.Create(
new Dictionary<string, int> { { "num", 42 } }
.ToImmutableDictionary());
}
}
public static void stack(Context ctx) {
ctx.export("x", Output.of("hello"));
ctx.export("o", Output.of(Map.of(
"num", "42"
)));
}
outputs:
x: hello
o:
num: 42
produce the following stack outputs:
$ pulumi stack output x
hello
$ pulumi stack output o
{"num": 42}
The full set of outputs can be rendered as JSON by using pulumi stack output --json
:
$ pulumi stack output --json
{
"x": "hello",
"o": {
"num": 42
}
}
Stack outputs respect secret annotations and are encrypted appropriately. If a stack contains any secret values, their plaintext values will not be shown by default. Instead, they will be displayed as secret in the CLI. Pass --show-secrets
to pulumi stack output
to see the plaintext value.
Getting the current stack programmatically
The getStack
getStack
get_stack
context.Stack
Deployment.StackName
let stack = pulumi.getStack();
let stack = pulumi.getStack();
stack = pulumi.get_stack()
stack := ctx.Stack()
var stack = Deployment.Instance.StackName;
var stack = ctx.stackName();
variables:
stack: ${pulumi.stack}
Stack references
Stack references allow you to access the outputs of one stack from another stack. Inter-stack dependencies allow one stack to reference the outputs of another stack.
To reference values from another stack, create an instance of the StackReference
type using the fully qualified name of the stack as an input, and then read exported stack outputs by their name:
const pulumi = require("@pulumi/pulumi");
const other = new pulumi.StackReference("acmecorp/infra/other");
const otherOutput = other.getOutput("x");
import * as pulumi from "@pulumi/pulumi";
const other = new pulumi.StackReference("acmecorp/infra/other");
const otherOutput = other.getOutput("x");
from pulumi import StackReference
other = StackReference(f"acmecorp/infra/other")
other_output = other.get_output("x");
other, err := pulumi.NewStackReference(ctx, "acmecorp/infra/other", nil)
if err != nil {
return err
}
otherOutput := other.GetOutput(pulumi.String("x"))
var other = new StackReference("acmecorp/infra/other");
var otherOutput = other.GetOutput("x");
var other = new StackReference("acmecorp/infra/other");
var otherOutput = other.getOutput(Output.of("x"));
resources:
my-stack-reference:
type: pulumi:pulumi:StackReference
properties:
name: acmecorp/infra/other
variables:
stack_output: ${my-stack-reference.outputs["x"]}
Stack names must be fully qualified, including the organization, project, and stack name components, in the format <organization>/<project>/<stack>
. For individual accounts, use your account name for the organization component.
To expand on this further, imagine you need to define a cluster’s infrastructure in one project and consume it from another.
Perhaps one project, infra
, defines a Kubernetes cluster and another, services
, deploys
services into it. Let’s further imagine you are doing this across three distinct environments: production, staging,
and testing. In that case, you will have six distinct stacks that pair up in the following ways:
mycompany/infra/production
provides the cluster used bymycompany/services/production
mycompany/infra/staging
provides the cluster used bymycompany/services/staging
mycompany/infra/testing
provides the cluster used bymycompany/services/testing
The way Pulumi programs communicate information for external consumption is by using stack exports. For example, your infrastructure stack might export the Kubernetes configuration information needed to deploy into a cluster:
exports.kubeConfig = ... a cluster's output property ...;
export const kubeConfig = ... a cluster's output property ...;
pulumi.export("kubeConfig", ... a cluster's output property ...)
ctx.Export("kubeConfig", /*...a cluster's output property...*/)
class ClusterStack : Stack
{
[Output] public Output<string> KubeConfig { get; set; }
public ClusterStack()
{
// ... a cluster is created ...
this.KubeConfig = ... a cluster's output property ...
}
}
ctx.export("kubeConfig", /*...a cluster's output property...*/);
outputs:
kubeConfig: ... # a cluster's output property
The challenge in this scenario is that the services project needs to ingest this output during deployment so that it can connect to the Kubernetes cluster provisioned in its respective environment.
The Pulumi programming model offers a way to do this with its StackReference
resource type. For example:
const k8s = require("@pulumi/kubernetes");
const pulumi = require("@pulumi/pulumi");
const env = pulumi.getStack();
const infra = new pulumi.StackReference(`mycompany/infra/${env}`);
const provider = new k8s.Provider("k8s", { kubeconfig: infra.getOutput("kubeConfig") });
const service = new k8s.core.v1.Service(..., { provider: provider });
import * as k8s from "@pulumi/kubernetes";
import * as pulumi from "@pulumi/pulumi";
const env = pulumi.getStack();
const infra = new pulumi.StackReference(`mycompany/infra/${env}`);
const provider = new k8s.Provider("k8s", { kubeconfig: infra.getOutput("kubeConfig") });
const service = new k8s.core.v1.Service(..., { provider: provider });
from pulumi import get_stack, ResourceOptions, StackReference
from pulumi_kubernetes import Provider, core
env = get_stack()
infra = StackReference(f"mycompany/infra/{env}")
provider = Provider("k8s", kubeconfig=infra.get_output("kubeConfig"))
service = core.v1.Service(..., ResourceOptions(provider=provider))
import (
"fmt"
"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)
func main() {
pulumi.Run(func(ctx *pulumi.Context) error {
slug := fmt.Sprintf("mycompany/infra/%v", ctx.Stack())
stackRef, err := pulumi.NewStackReference(ctx, slug, nil)
kubeConfig := stackRef.GetOutput(pulumi.String("kubeConfig"))
// ...
return nil
}
}
using Pulumi;
using Pulumi.Kubernetes.Core.V1;
class AppStack : Stack
{
public AppStack()
{
var cluster = new StackReference($"mycompany/infra/{Deployment.Instance.StackName}");
var kubeConfig = cluster.RequireOutput("KubeConfig").Apply(v => v.ToString());
var provider = new Provider("k8s", new ProviderArgs { KubeConfig = kubeConfig });
var options = new ComponentResourceOptions { Provider = provider };
var service = new Service(..., ..., options);
}
}
package myproject;
import com.pulumi.Context;
import com.pulumi.Exports;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.kubernetes.Provider;
import com.pulumi.kubernetes.ProviderArgs;
import com.pulumi.kubernetes.core_v1.Service;
import com.pulumi.kubernetes.core_v1.ServiceArgs;
import com.pulumi.resources.ComponentResourceOptions;
import com.pulumi.resources.StackReference;
public class App {
public static void main(String[] args) {
Pulumi.run(App::stack);
}
public static void stack(Context ctx) {
var cluster = new StackReference(String.format("mycompany/infra/%s", ctx.stackName()));
var kubeconfig = cluster.requireOutput(Output.of("KubeConfig")).applyValue(String::valueOf);
var provider = new Provider("k8s", ProviderArgs.builder().kubeconfig(kubeconfig).build());
var options = ComponentResourceOptions.builder()
.provider(provider)
.build();
var service = new Service("app-service", ServiceArgs.builder()
...
.build(), options);
}
}
variables:
kubeConfig: ${my-stack-reference.outputs["KubeConfig"]}
resources:
my-stack-reference:
type: pulumi:pulumi:StackReference
properties:
name: mycompany/infra/${pulumi.stack}
provider:
type: pulumi:providers:kubernetes
properties:
kubeConfig: kubeConfig
service:
type: some:resource:type
properties: ...
options:
provider: ${provider}
The StackReference
constructor takes as input a string of the form <organization>/<project>/<stack>
, and lets
you access the outputs of that stack.
In the above example, you construct a stack reference to a specific stack in this project which has the same name
as your current stack (i.e. when deploying the “staging” stack of the above program, you reference the “staging” stack)
from the infra project. Once you have that resource, you can fetch the kubeConfig
output variable with the getOutput
function. From that point onwards, Pulumi understands the inter-stack dependency for scenarios like cascading updates.
Reading outputs from stack references
Stack references support two ways of reading outputs from the referenced stack:
getOutput
returns anOutput
that provides gated access to the output value. The output value can be accessed and transformed with methods likeOutput.apply
. This is useful when the output is used as an input to another resource.getOutputDetails
returns anOutputDetails
object that provides direct access to the output value. This is useful when you want to process the output directly in your code.
As a demonstration of getOutput
,
suppose that your referenced stack exports a privateIp
output.
You want to incorporate the IP address into the name of an S3 bucket object
containing logs from that machine.
const infra = new pulumi.StackReference(...);
const ip = infra.getOutput("privateIp");
const logKey = ip.apply(ip => `logs/${ip}.log`);
const logFile = new aws.s3.BucketObject("log", {
// ...
key: logKey
});
const infra: StackReference = new pulumi.StackReference(...);
const ip: Output<any> = infra.getOutput("privateIp");
const logKey: Output<string> = ip.apply(ip => `logs/${ip}.log`);
const logFile: aws.s3.BucketObject = new aws.s3.BucketObject("log", {
// ...
key: logKey
});
infra = StackReference(...)
ip = infra.get_output("privateIp")
log_key = ip.apply(lambda ip: f"logs/{ip}.log")
log_file = aws.s3.BucketObject("log", {
# ...
key: log_key
})
infra, err := pulumi.NewStackReference(ctx, ...)
if err != nil {
return err
}
ip := infra.GetOutput("privateIp")
logKey := ip.ApplyT(func(ip string) string {
return fmt.Sprintf("logs/%s.log", ip)
}).(StringOutput)
logFile := s3.NewBucketObject(ctx, "log", &s3.BucketObjectArgs{
// ...
Key: logKey,
})
var infra = new StackReference(...);
var ip = infra.GetOutput("privateIp");
var logKey = ip.Apply(ip => $"logs/{ip}.log");
var logFile = new Aws.S3.BucketObject("log", new Aws.S3.BucketObjectArgs
{
// ...
Key = logKey,
});
StackReference infra = new StackReference(...);
Output<String> ip = infra.getOutput("privateIp");
Output<String> logKey = ip.apply(ip -> String.format("logs/%s.log", ip));
BucketObject logFile = new BucketObject("log", new BucketObjectArgs.Builder()
.key(logKey)
.build());
On the other hand, as an example of using getOutputDetails
,
suppose that your referenced stack creates a VPC
and exports a list of public subnets as a JSON-serialized string,
and you want to add a bastion host to each subnet.
With getOutputDetails
, this would look something like this:
const infra = new pulumi.StackReference(...);
const subnetsJSON = await infra.getOutputDetails("subnets");
const subnets = JSON.parse(subnetsJSON.value);
for (let i = 0; i < subnets.length; i++) {
const subnet = subnets[i];
const host = new aws.ec2.Instance(`bastion-${i}`, {
// ...
subnetId: subnet.id,
});
// ...
}
Note that your Pulumi program must export a top-level async
function
to be able to use the await
operator.
export = async () => {
// ...
}
See Javascript Entrypoint for more information.
const infra: StackReference = new pulumi.StackReference(...);
const subnetsJSON: StackReferenceOutputDetails = await infra.getOutputDetails("subnets");
const subnets = JSON.parse(subnetsJSON.value);
for (let i = 0; i < subnets.length; i++) {
const subnet = subnets[i];
const host = new aws.ec2.Instance(`bastion-${i}`, {
// ...
subnetId: subnet.id,
});
// ...
}
Note that your Pulumi program must export a top-level async
function
to be able to use the await
operator.
export = async () => {
// ...
}
See Javascript Entrypoint for more information.
infra, err := pulumi.NewStackReference(ctx, ...)
if err != nil {
return err
}
subnetsJSON, err := infra.GetOutputDetails("subnets")
if err != nil {
return err
}
var subnets []struct{ ID string `json:"id"` }
if err := json.Unmarshal([]byte(subnetsJSON.Value.(string)), &subnets); err != nil {
return err
}
for i, subnet := range subnets {
host, err := ec2.NewInstance(ctx, fmt.Sprintf("bastion-%d", i), &ec2.InstanceArgs{
// ...
SubnetId: pulumi.String(subnet.ID),
})
if err != nil {
return err
}
// ...
}
var infra = new StackReference(...);
var subnetsJSON = await infra.GetOutputDetailsAsync("subnets");
var subnets = JsonConvert.DeserializeObject<Subnet[]>((string)subnetsJSON.Value);
for (int i = 0; i < subnets.Length; i++) {
var subnet = subnets[i];
var host = new Aws.Ec2.Instance($"bastion-{i}", new Aws.Ec2.InstanceArgs
{
// ...
SubnetId = subnet.Id,
});
// ...
}
Note that your Pulumi program must be inside an async
function
to be able to use the await
operator.
return await Deployment.RunAsync(async () =>
{
// ...
});
StackReferenceOutputDetails subnetsJSON = infra.outputDetails("subnets");
infra.outputDetailsAsync("subnets").thenAccept(subnetsJSON -> {
Subnet[] subnets = new Gson().fromJson((String)subnetsJSON.getValue().get(), Subnet[].class);
for (int i = 0; i < subnets.length; i++) {
Subnet subnet = subnets[i];
Instance host = new Instance(String.format("bastion-%d", i), new InstanceArgs.Builder()
// ...
.subnetId(subnet.getId())
.build());
// ...
}
})
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.
$ pulumi stack export --file stack.json
$ pulumi stack import --file stack.json
Destroy a stack
Before deleting a stack, if the 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.
pulumi destroy
may fail to delete resources as expected due to dependencies, permissions, or the resources being in a locked or protected state. For detailed steps on how to troubleshoot and resolve these issues, refer to our troubleshooting guide.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 Pulumi.<stack-name>.yaml
.
To force the deletion of a stack that still contains resources—potentially orphaning them—use pulumi stack rm --force
.
Thank you for your feedback!
If you have a question about how to use Pulumi, reach out in Community Slack.
Open an issue on GitHub to report a problem or suggest an improvement.