Pulumi Operations

External

• https://www.pulumi.com/docs/reference/cli/

Internal

• Pulumi

Global Options

--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

https://www.pulumi.com/docs/reference/cli/pulumi_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

https://www.pulumi.com/docs/reference/cli/pulumi_new/

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

https://www.pulumi.com/docs/reference/cli/pulumi_up/

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:

What Happens when Code is Applied to Platform?

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 Stacks

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 --create flag, 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:

Pulumi Resource URN

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:

Destroying vs. Deleting a Stack

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:

Destroying vs. Deleting a Stack

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:

Pulumi Stack Outputs

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.

Stack Tags

Pulumi Concepts | Tags

Display Stack Tags

https://www.pulumi.com/docs/reference/cli/pulumi_stack_tag_ls/

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

https://www.pulumi.com/docs/reference/cli/pulumi_import/

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:

Importing Infrastructure Resources into an Existing Stack

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:

Resource Type

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:

• Import an externally created Datadog Dashboard
• Import an externally created Datadog DashboardJson

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:

Pulumi Programming Model | Importing (Adopting) an Infrastructure Resource

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