Pulumi Operations
External
Internal
Overview
Global Options
-s|--stack
--non-interactive
Disable interactive mode for all commands.
It seems that if used without --yes, it fails:
pulumi update --non-interactive --stack my-org/my-project/my-stack error: --yes must be passed in to proceed when running in non-interactive mode
If both --non-interactive and --yes are used together, there seems to be a little less output than if --yes is used alone.
--yes
Automatically approve and perform the update after previewing it. It is sufficient to use it with --non-interactive.
Authentication and Login
Identity Info
Dumps identity, backend name and URL, Open Directory groups, etc.
pulumi whoami --verbose
This reads ~/.pulumi/credentials.json.
Login
pulumi login [--cloud-url https://something.example.com]
Without argument, logs into the Pulumi-managed backend. Credentials are cached locally and can be viewed with ~/.pulumi/credentials.json.
State can be maintained in different places, as follows:
- For a "https://" URL, the command line process will access the remote backend via REST.
- For a "file://" URL, the state is managed locally.
- For a "s3://" URL, state is maintained in an S3 bucket.
- For a "gs://" URL, state is maintained in an GCP bucket.
- For a "azblob://" URL, state is maintained in an Azure blob.
Login Options
-c|--cloud-url
A cloud URL to log in to. Then, what does pulumi login https:/... mean and how is different from the same command with an extra --cloud-url?
--local
--local is a shortcut for:
pulumi login file://~
Logout
pulumi logout
pulumi logout --all
Options
--all
Logout of all backends.
Environment Info
pulumi about
displays information about the current Pulumi environment including the client version, installed plugins, current stack, backend, etc.
Log Location
Displayed in the output of pulumi about. In a location similar to /var/folders/pf/t_bwclcn4mv3kq49ks14_12c0000gn/T/ b.
Organization Operations
Organization Info
Display details for a specific organization:
pulumi org get <org-name>
List Organizations
List all organizations visible to the user:
pulumi org ls
Project Operations
Projects provide namespaces for stacks.
List Projects for a Given Organization
org=my-org; pulumi stack ls --all -C ~ | grep "^${org}" | sed -e 's/^.*\/\(.*\)\/.*$/\1/' | uniq | sort
New Project
pulumi new
Create a new project and stack from a template, initialize the local metadata and the backend state.
If no template is provided, a list of suggested templates will be presented, so they can be selected interactively.
The command must be invoked inside an empty directory. The directory will become the root of the project, and will host Pulumi.yaml, Pulumi.<stack-name>.yaml and language specific artifacts. An interactive command line loop will require the project name, which defaults to the name of the directory, description, stack name in the <org-name>/<stack-name> format, and then any configuration elements declared in the template.config subtree of the template's Pulumi.yaml file. The command creates basic scaffolding based on the cloud and language specified.
The command will create one empty stack, which will automatically become the active stack.
If Python is used, the command creates a new virtual environment and automatically downloads dependencies. The project layout is similar to this one. Full syntax:
pulumi new [template|url] [flags]
Example:
pulumi new https://github.com/some-org/pulumi-templates/tree/master/datadog-python
An AWS Python project:
pulumi new aws-python
Project Update Dry Run
pulumi preview [-s some-stack --non-interactive]
Without an -s argument, the command operates on the active stack. The Python stdout output in the program will be sent to the command stdout.
Project Update
Project deployment is initiated with:
pulumi up|update
The command operates on the active stack. The Python stdout output in the program will be sent to the command stdout.
Example:
pulumi up|update -y -s some_stack --non-interactive
The command evaluates the program and determines resource updates to make. It first does a preview, and tells the user what is going to happen, from the point of view of creating, updating or deleting resources. If choosing "details", the user can inspect individual attributes of the resource. For more details see:
Run, expecting no changes, assuming the logic is idempotent. If there are changes, the command will detect the changes, and it will fail without applying the changes.
pulumi up|update -y -s some_stack --non-interactive --expect-no-changes
Options
-s|--stack
The name of the stack to operate on. Defaults to the current stack.
-y|--yes
Automatically approve and perform the update after previewing it.
--expect-no-changes
Return an error if any changes occur during this update. The changes will not be applied.
Dry Run
See pulumi preview above.
Stack Operations
pulumi stack <command> must be run from a project directory, which is a directory that contains a Pulumi.yaml file. If it not run from a directly containing Pulumi.yaml, it will apply to the current project.
List Stacks
Display the list associated with the current project.
pulumi stack ls
⚠️ -s <stack-name> has no effect when used with pulumi stack ls.
List the Active Stack for the Project
Use pulumi stack ls. The active stack is marked with an asterisk in the command output.
ls Options
--j|--json
Emit output as JSON.
-a|--all
List all stacks instead of just stacks for the current project.
-o|--organization
Filter returned stacks to those in a specific organization.
-p|--project
Filter returned stacks to those with a specific project name.
-t|--tag
Filter returned stacks to those in a specific tag (tag-name or tag-name=tag-value)
Display Stack Resources
Brief view:
pulumi stack [-s <org>/<project>/<stack>]
JSON dump.
pulumi stack [-s <org>/<project>/<stack>] export
Switch the Workspace to a Given Stack
Select the current (active) stack for the project.
pulumi stack select
Selecting a stack allows you to use commands like config, preview, and update without needing to type the stack name each time. If no stack argument is supplied, you will be prompted to select one interactively. If operating within an organization, the stack name must be prefixed by the organization name.
pulumi stack select --create --secrets-provider=passphrase <org-name>/<stack-name>
Options:
--create: If selected stack does not exist, create it. It probably creates the "desired state" but does not apply anything yet.--secrets-provider: Use with--createflag, The type of the provider that should be used to encrypt and decrypt secrets. Possible choices: default, passphrase, awskms, azurekeyvault, gcpkms, hashivault, default "passphrase".
Create Stack
A stack may be created "empty", when no corresponding infrastructure resources have been created in the backed infrastructure platform, or fully initialized, when the backend infrastructure resources are also created at the time of stack creation.
An empty stack can be created as part of a new project creation sequence, as result of the pulumi new command. pulumi new command creates a default empty stack, so creating additional stacks makes sense if the project was bootstrapped manually and no default stack was created, or we need more than one stack in the project. For an existing project, an empty stack can be create with the pulumi stack init command, described in detail below. A fully initialized stack is created as result of the pulumi up command. Note that a project may contain multiple stacks, and of those, there is one active stack at any moment.
pulumi stack init
pulumi stack init should be used when you need to create an empty stack within the context of an already existing project. The name of the stack must be specified as argument:
pulumi stack init <stack-name>
⚠️ If Pulumi is used within the context of an organization, and without specifying additional information, the stack will be created in the user account of the user running the command. This may not be something you necessarily want. To create the stack in the organization instead, name the stack using <org-name>/<stack-name> naming pattern:
pulumi stack init <org-name>/<stack-name>
Example:
pulumi stack init my-org/my-stack
The command runs in non-interactive mode, no stdin confirmation is required.
The stack, once created, is ready for updates. As mentioned above, the stack is empty, it has no corresponding infrastructure resources stored in the backend, but it can become a target of a deployment initiated with the pulumi update command. Stack creation also means creation of a Pulumi.<stack-name>.yaml in the project directory and the initialization of the corresponding empty stack, devoid of resources, in the backend:
{
"version": 1,
"deployment": {
"manifest": {
"time": "0001-01-01T00:00:00Z",
"magic": "",
"version": ""
}
}
}
The command also initializes the local workspace state, if not already initialized.
pulumi stack select --create
Alternatively, a stack that does not exist can be created when it is "selected", if the --create option is used:
pulumi stack select --create --secrets-provider=passphrase <org-name>/<stack-name>
Rename Stack
pulumi stack rename <org>/<new-stack-name>
where the <new-stack-name> is the simple (not fully qualified) name. Renaming will change the name of the stack settings file Pulumi.<stack-name>.yaml file accordingly.
The stack project can be renamed by passing the fully-qualified stack name.
Because renaming a stack will change the value of getStack() inside a Pulumi program, if this name is used as part of a resource's name, the next pulumi up will want to delete the old resource and create a new copy. For now, if you don't want these changes to be applied, you should rename your stack back to its previous name.
Export a Stack
The stack metadata in a raw format (JSON) can be displayed with:
pulumi stack export
Exporting a stack is not a standard workflow, and it should be used with caution.
pulumi stack export [--file stack.json] # by default will send the content to stdout
Edit Stack State
Resources and be individually deleted and renamed by manipulating the stack's state. Also, protected resources can be "unprotected":
Unprotect Resource in Stack State
pulumi state unprotect [--stack <org>/<stack-name>] <resource-URN>
Example:
pulumi state unprotect --stack my-org/dd.test.adopted.blue 'urn:pulumi:dd.test.adopted.blue::datadog-dashboards::datadog:index/dashboardJson:DashboardJson::dashboardJson'
More details about resource URN are available here:
Refresh Stack State
Reads the infrastructure platform state and updates the corresponding stack state. The command compares the current stack's resource state with the state known to exist in the actual cloud provider. Any such changes are adopted into the current stack. Note that if the program text isn't updated accordingly, subsequent updates may still appear to be out of synch with respect to the cloud provider's source of truth.
pulumi refresh
Destroy a Stack
pulumi destroy
Without an -s argument, the command operates on the active stack.
For the difference between deleting and destroying a stack, see:
Options
--non-interactive
Disables interactive mode. Note that --yes must be passed in to proceed when running in non-interactive mode.
--exclude-protected
Destroy all unprotected resources and preserve protected resources.
pulumi destroy --exclude-protected
Remove (Delete) a Stack
Removes (deletes) a stack and the associated local stack settings file. You should destroy the stack first. For the difference between deleting and destroying a stack, see:
pulumi stack rm some_org/some_stack
There are situation when Pulumi will refuse to delete the stack because the stack still has resources, but an attempting to destroy the stack fails - maybe because the resources were deleted externally and the stack got out of sync. In that situation, if you are sure there are no infrastructure resources associated with the stack you can force delete the stack:
pulumi stack rm some_org/some_stack --force
Remove (Delete) a Stack without Deleting Associated Infrastructure Resources
There are situations when a stack must be deleted, but not the associated resources. This is the case when external resources are adopted, for example.
pulumi stack rm --force some_org/some_stack
This command does not removes the managed infrastructure resources.
Options
--non-interactive
Disables interactive mode. Note that --yes must be passed in to proceed when running in non-interactive mode.
-f|--force
Forces deletion of the stack, leaving behind any resources managed by the stack. See forced deletion above.
Stack Configuration Operations
pulumi config manages stack settings files. Without an -s argument, the command operates on the active stack.
List Configuration Values
Display the configuration value for the current stack. If -s <stack-name> is specified, use that stack instead.
pulumi config [-s <stack-name>]
Set a Configuration Value
pulumi config -s some-stack --non-interactive set some_key some_value
pulumi config set --path ... some_value
Stack Output Operations
The concepts behind stack outputs are described here:
Show Stack Output Properties
Show a stack's output properties:
pulumi stack output [--show-secrets] [--stack <org>/<stack-name>]
Some resource properties are considered secret, and not displayed unless --show-secrets is used.
To display a specific output:
pulumi stack output <property-name>
Show an Individual Output Property
pulumi stack output <property-key> --stack <org-name>/<stak-name>| jq
Set an Individual Output Property
It does not seem possible to do from command line, the only way to be done is through program, using pulumi.export() and not modifying any other resource.
Options
--show-secrets
--json
Stack Tags
Display Stack Tags
The command displays stack tags for the active stack:
pulumi stack tag ls
Set Custom Tags
pulumi stack tag set <name> <value>
Did not work. COME BACK TO THIS: https://www.pulumi.com/docs/intro/concepts/stack/#stack-tags
Get Specific Tags
pulumi stack tag get <name>
pulumi stack tag get gitHub:owner
Delete Tag
pulumi stack tag rm <name>
Import Individual External Resources into a Stack
The import command can be used to adopt individual external resources, not created with Pulumi, to be managed via a Pulumi stack. Importing (adopting) a resource is not a standard workflow, and it should be used with caution. The same command can be used to import the JSON representation of the whole stack.
The conceptual aspects of adopting resources are addressed here:
The general form of the command is:
pulumi stack import [--protect=false] [--generate-code=false] [--out file_path] \
<resource-type> <new-resource-name> <resource-id> [-s stack-name] [other-flags]
The command requires a stack to import into. If -s stack-name is specified, that stack will be used, otherwise the active stack to import into. The stack name must be in the "<org-name>/<stack-name>" format. Does <org-name>/<project-name>/<stack-name> work? An empty stack can be created with pulumi stack init command.
To figure out how to get resource-type, see:
new-resource-name is the name the resource will be imported under, into the stack, not the name of existing resource.
resource-id is the ID of the infrastructure resource in the infrastructure platform. This is how the resource is identified.
The process is by default interactive. The command will ask whether to perform the import. To automatically approve, use the --yes option.
A definition for each resource will be printed to stdout in the language used by the project associated with the stack. These definitions should be added to the Pulumi program. For reasons behind this, see Pulumi Programming Model | Importing (Adopting) an Infrastructure Resource.
The resources are protected from deletion by default. Should you want to import your resource(s) without protection, you can pass
--protect=false as an argument to the command. This will leave all resources unprotected.
Example:
pulumi stack import datadog:index/dashboard:Dashboard 'Adopted Dashboard' 44h-7e6-vaa
Another import examples:
The resources to be imported may be specified into a JSON file instead of command line arguments:
pulumi stack import --file stack.json
To see how import fits into the Pulumi programming model see:
Import the Entire Stack as JSON
It is possible to export a stack as JSON, edit it and the import it in bulk:
pulumi stack export --stack my-org/my-stack > ./my-stack.json
# edit ./my-stack.json
cat ./my-stack.json | pulumi stack import --stack my-org/my-stack
Plugin Operations
List
pulumi plugin ls