Pulumi Operations: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
 
(76 intermediate revisions by the same user not shown)
Line 9: Line 9:
==<tt>--non-interactive</tt>==
==<tt>--non-interactive</tt>==
Disable interactive mode for all commands.
Disable interactive mode for all commands.
It seems that if used without <code>--yes</code>, it fails:
<font size=-1>
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
</font>
If both  <code>--non-interactive</code> and  <code>--yes</code> are used together, there seems to be a little less output than if <code>--yes</code> is used alone.
==<tt>--yes</tt>==
Automatically approve and perform the update after previewing it. It is sufficient to use it with <code>--non-interactive</code>.


=Authentication and Login=
=Authentication and Login=
Line 112: Line 124:


==<span id='Apply_Infrastructure'></span><span id='up'></span><span id='Apply_Stack_to_Platform'></span><span id='Project_Deployment'></span>Project Update==
==<span id='Apply_Infrastructure'></span><span id='up'></span><span id='Apply_Stack_to_Platform'></span><span id='Project_Deployment'></span>Project Update==
{{External|https://www.pulumi.com/docs/reference/cli/pulumi_up/}}
[[Pulumi_Concepts#Deploying_a_Project|Project deployment]] is initiated with:
[[Pulumi_Concepts#Deploying_a_Project|Project deployment]] is initiated with:
<syntaxhighlight lang='bash'>
<syntaxhighlight lang='bash'>
Line 189: Line 202:
A stack may be created "[[Pulumi_Concepts#Empty_Stack|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.
A stack may be created "[[Pulumi_Concepts#Empty_Stack|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|new project creation sequence]], as result of the <code>[[#pulumi_new|pulumi new]]</code> command. For an existing project, an empty stack can be create with the <code>pulumi stack init</code> command:
An '''empty stack''' can be created as part of a [[#New_Project|new project creation sequence]], as result of the <code>[[#pulumi_new|pulumi new]]</code> command. <code>[[#new|pulumi new]]</code> command creates a default empty stack, so creating additional stacks makes sense if the [[Pulumi_Concepts#Project|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 <code>pulumi stack init</code> command, described in detail below. A '''fully initialized stack''' is created as result of the <code>[[#Project_Update|pulumi up]]</code> command. Note that a project may contain multiple stacks, and of those, there is one [[Pulumi_Concepts#Current_.28Active.2C_Default.29_Stack|active stack]] at any moment.
<span id='pulumi_stack_init'></span>
<font size=-1>
pulumi_stack_init
</font>
 
A fully initialized stack is created as result of the <code>[[#Project_Update|pulumi up]]</code> command.
 
Note that a project may contain multiple stacks, and of those, there is one [[Pulumi_Concepts#Current_.28Active.2C_Default.29_Stack|active stack]] at any moment.
 
 
 
 
 
 
 
 
 


Create an empty [[Pulumi_Concepts#Stack|stacks]] with the given name, ready for updates. The stack has no resources stored in the backend, but it can become a target of a deployment initiated with the <code>[[#update|pulumi update]]</code> command. <code>[[#new|pulumi new]]</code> command creates a default empty stack, so creating additional stacks makes sense if the [[Pulumi_Concepts#Project|project]] was bootstrapped manually, so no default stack was created, or we need more than one stack in the project.  
===<tt>pulumi stack init</tt>===
<code>pulumi stack init</code> should be used when you need to create an [[Pulumi_Concepts#Empty_Stack|empty stack]] within the context of an already existing project. The name of the stack must be specified as argument:
<font size=-1>
<font size=-1>
  pulumi stack init <[[Pulumi_Concepts#Stack_Name|stack-name]]>
  pulumi stack init <[[Pulumi_Concepts#Stack_Name|stack-name]]>
</font>
</font>
If Pulumi is used within the context of an [[Pulumi_Concepts#Organization|organization]], by default the stack will be created in the user account of the user running the command. To create the stack in the organization instead, name the stack using <code><org-name>/<stack-name></code>.
⚠️ If Pulumi is used within the context of an [[Pulumi_Concepts#Organization|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 <code><org-name>/<stack-name></code> naming pattern:
<font size=-1>
<font size=-1>
  pulumi stack init <org-name>/<stack-name>
  pulumi stack init <org-name>/<stack-name>
</font>
</font>
Example:
<font size=-1>
pulumi stack init my-org/my-stack
</font>
The command runs in non-interactive mode, no stdin confirmation is required.


Stack creation means creation of a <code>Pulumi.<stack-name>.yaml</code> in the project directory and the initialization of the corresponding empty stack, devoid of resources, in the backend:
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 <code>[[#update|pulumi update]]</code> command. Stack creation also means creation of a <code>Pulumi.<stack-name>.yaml</code> in the project directory and the initialization of the corresponding empty stack, devoid of resources, in the backend:
<syntaxhighlight lang='json'>
<syntaxhighlight lang='json'>
{
{
Line 233: Line 236:
The command also initializes the [[Pulumi_Concepts#Workspace|local workspace state]], if not already initialized.
The command also initializes the [[Pulumi_Concepts#Workspace|local workspace state]], if not already initialized.


===<tt>pulumi stack select --create</tt>===
Alternatively, a stack that does not exist can be created when it is "selected", if the <code>--create</code> option is used:
Alternatively, a stack that does not exist can be created when it is "selected", if the <code>--create</code> option is used:
<syntaxhighlight lang='bash'>
<syntaxhighlight lang='bash'>
Line 247: Line 251:


<font color=darkkhaki>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 <code>pulumi up</code> 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.</font>
<font color=darkkhaki>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 <code>pulumi up</code> 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.</font>
==<span id='Export'></span>Export a Stack==
The stack metadata in a raw format (JSON) can be displayed with:
<syntaxhighlight lang='bash'>
pulumi stack export
</syntaxhighlight>
Exporting a stack is not a [[Pulumi_Concepts#Stack_Import.2FExport|standard workflow]], and it should be used with caution.
<syntaxhighlight lang='bash'>
pulumi stack export [--file stack.json] # by default will send the content to stdout
</syntaxhighlight>
==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===
<syntaxhighlight lang='bash'>
pulumi state unprotect [--stack <org>/<stack-name>] <resource-URN>
</syntaxhighlight>
Example:
<syntaxhighlight lang='bash'>
pulumi state unprotect --stack my-org/dd.test.adopted.blue 'urn:pulumi:dd.test.adopted.blue::datadog-dashboards::datadog:index/dashboardJson:DashboardJson::dashboardJson'
</syntaxhighlight>
More details about resource URN are available here: {{Internal|Pulumi_Resource#URN|Pulumi Resource URN}}
==<span id='pulumi_refresh'></span>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.
<syntaxhighlight lang='bash'>
pulumi refresh
</syntaxhighlight>
==<span id='destroy'></span>Destroy a Stack==
==<span id='destroy'></span>Destroy a Stack==
<syntaxhighlight lang='bash'>
<syntaxhighlight lang='bash'>
Line 257: Line 288:
====<tt>--non-interactive</tt>====
====<tt>--non-interactive</tt>====
Disables interactive mode. Note that <code>--yes</code> must be passed in to proceed when running in non-interactive mode.
Disables interactive mode. Note that <code>--yes</code> must be passed in to proceed when running in non-interactive mode.
====<tt>--exclude-protected</tt>====
Destroy all unprotected resources and preserve protected resources.
<syntaxhighlight lang='bash'>
pulumi destroy --exclude-protected
</syntaxhighlight>
==<span id='delete'></span>Remove (Delete) a Stack==
==<span id='delete'></span>Remove (Delete) a Stack==
Removes (deletes) a stack and the associated local [[Pulumi_Concepts#Stack_Settings_File|stack settings file]]. You should [[#Destroy_a_Stack|destroy]] the stack first. For the difference between deleting and destroying a stack, see: {{Internal|Pulumi_Concepts#Destroying_and_Deleting_a_Stack|Destroying vs. Deleting a Stack}}
Removes (deletes) a stack and the associated local [[Pulumi_Concepts#Stack_Settings_File|stack settings file]]. You should [[#Destroy_a_Stack|destroy]] the stack first. For the difference between deleting and destroying a stack, see: {{Internal|Pulumi_Concepts#Destroying_and_Deleting_a_Stack|Destroying vs. Deleting a Stack}}
Line 266: Line 303:
pulumi stack rm some_org/some_stack  --force  
pulumi stack rm some_org/some_stack  --force  
</syntaxhighlight>
</syntaxhighlight>
===Options===
===Remove (Delete) a Stack without Deleting Associated Infrastructure Resources===
====<tt>--non-interactive</tt>====
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.
<syntaxhighlight lang='bash'>
pulumi stack rm --force some_org/some_stack
</syntaxhighlight>
This command does not removes the managed infrastructure resources.
 
==Options==
===<tt>--non-interactive</tt>===
Disables interactive mode. Note that <code>--yes</code> must be passed in to proceed when running in non-interactive mode.
Disables interactive mode. Note that <code>--yes</code> must be passed in to proceed when running in non-interactive mode.
====<tt>-f|--force</tt>====
===<tt>-f|--force</tt>===
Forces deletion of the stack, leaving behind any resources managed by the stack. See [[#Forced_Deletion|forced deletion]] above.
Forces deletion of the stack, leaving behind any resources managed by the stack. See [[#Forced_Deletion|forced deletion]] above.


Line 288: Line 332:


==Stack Output Operations==
==Stack Output Operations==
The concepts behind stack outputs are described here: {{Internal|Pulumi_Concepts_Inputs_and_Outputs#Output|Pulumi Stack Outputs}}
===<span id='stack_output'></span>Show Stack Output Properties===
===<span id='stack_output'></span>Show Stack Output Properties===
Show a stack's [[Pulumi_Concepts_Inputs_and_Outputs#Output|output properties]]:
Show a stack's [[Pulumi_Concepts_Inputs_and_Outputs#Output|output properties]]:
<syntaxhighlight lang='bash'>
<syntaxhighlight lang='bash'>
pulumi stack output [--show-secrets]
pulumi stack output [--show-secrets] [--stack <org>/<stack-name>]
</syntaxhighlight>
</syntaxhighlight>
Some resource properties are considered [[Pulumi_Concepts#Secret_Values|secret]], and not displayed unless <code>--show-secrets</code> is used.
Some resource properties are considered [[Pulumi_Concepts#Secret_Values|secret]], and not displayed unless <code>--show-secrets</code> is used.
Line 299: Line 344:
pulumi stack output <property-name>
pulumi stack output <property-name>
</syntaxhighlight>
</syntaxhighlight>
===Show an Individual Output Property===
<syntaxhighlight lang='bash'>
pulumi stack output <property-key> --stack <org-name>/<stak-name>| jq
</syntaxhighlight>
===Set an Individual Output Property===
<font color=darkkhaki>It does not seem possible to do from command line, the only way to be done is through program, using <code>pulumi.export()</code> and not modifying any other resource.</font>


===Options===
===Options===
Line 328: Line 380:
pulumi stack tag rm <name>
pulumi stack tag rm <name>
</syntaxhighlight>
</syntaxhighlight>
==<span id='Import'></span><span id='Import/Export_Stack'></span><span id='Import_External_Resources_into_a_Stack'></span>Import Individual External Resources into a Stack==
{{External|https://www.pulumi.com/docs/reference/cli/pulumi_import/}}
The <code>import</code> 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 [[Pulumi_Concepts#Stack_Import.2FExport|standard workflow]], and it should be used with caution. The same command can be used to import the JSON representation of the whole stack.


=<span id='Import'></span><span id='Export'></span>Import/Export Stack=
The conceptual aspects of adopting resources are addressed here: {{Internal|Pulumi_Concepts#Importing_Infrastructure_Resources_into_an_Existing_Stack|Importing Infrastructure Resources into an Existing Stack}}
Exporting and importing a stack is not a [[Pulumi_Concepts#Stack_Import.2FExport|standard workflow]], and it should be used with caution.
 
==Import Resource into an Existing Stack==
The <code>import</code> command can be used to import external resources, not currently managed by Pulumi, into an existing stack.
 
<font color=darkkhaki>
 
 


The general form of the command is:
<syntaxhighlight lang='bash'>
<syntaxhighlight lang='bash'>
pulumi stack import --file stack.json
pulumi stack import [--protect=false] [--generate-code=false] [--out file_path]  \
<resource-type> <new-resource-name> <resource-id> [-s stack-name] [other-flags]
</syntaxhighlight>
</syntaxhighlight>
The command requires a stack to import into. If <code>-s stack-name</code> is specified, that stack will be used, otherwise the active stack to import into. The stack name must be in the "<code><org-name>/<stack-name></code>" format. <font color=darkkhaki>Does <org-name>/<project-name>/<stack-name> work?</font> An empty stack can be created with <code>[[#pulumi_stack_init|pulumi stack init]]</code> command.


To figure out how to get <code>resource-type</code>, see: {{Internal|Pulumi_Resource#Type|Resource Type}}


Import resources into an existing stack.
<code>new-resource-name</code> is the name the resource will be imported under, into the stack, not the name of existing resource.


Resources that are not managed by Pulumi can be imported into a Pulumi stack
<code>resource-id</code> is the ID of the infrastructure resource in the infrastructure platform. This is how the resource is identified.
using this command. 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. The resources are protected from deletion
by default.


Should you want to import your resource(s) without protection, you can pass
The process is by default interactive. The command will ask whether to perform the import. To automatically approve, use the <code>--yes</code> option.
`--protect=false` as an argument to the command. This will leave all resources unprotected.


A single resource may be specified in the command line arguments or a set of
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_.28Adopting.29_an_Infrastructure_Resource|Pulumi Programming Model &#124; Importing (Adopting) an Infrastructure Resource]].
resources may be specified by a JSON file. This file must contain an object
of the following form:


    {
The resources are protected from deletion by default. Should you want to import your resource(s) without protection, you can pass
        "nameTable": {
<code>--protect=false</code> as an argument to the command. This will leave all resources unprotected.
            "provider-or-parent-name-0": "provider-or-parent-urn-0",
            ...
            "provider-or-parent-name-n": "provider-or-parent-urn-n",
        },
        "resources": [
            {
                "type": "type-token",
                "name": "name",
                "id": "resource-id",
                "parent": "optional-parent-name",
                "provider": "optional-provider-name",
                "version": "optional-provider-version",
                "properties": ["optional-property-names"],
            },
            ...
            {
                ...
            }
        ]
    }


The name table maps language names to parent and provider URNs. These names are
Example:
used in the generated definitions, and should match the corresponding declarations
in the source program. This table is required if any parents or providers are
specified by the resources to import.


The resources list contains the set of resources to import. Each resource is
<syntaxhighlight lang='bash'>
specified as a triple of its type, name, and ID. The format of the ID is specific
pulumi stack import datadog:index/dashboard:Dashboard 'Adopted Dashboard' 44h-7e6-vaa
to the resource type. Each resource may specify the name of a parent or provider;
</syntaxhighlight>
these names must correspond to entries in the name table. If a resource does not
specify a provider, it will be imported using the default provider for its type. A
resource that does specify a provider may specify the version of the provider
that will be used for its import.
Each resource may specify which input properties to import with;
If a resource does not specify any properties the default behaviour is to
import using all required properties.


Usage:
Another import examples:
  pulumi import [type] [name] [id] [flags]
* [[Managing_Datadog_with_Pulumi#Importing_an_Externally_Created_Dashboard|Import an externally created Datadog Dashboard]]
* [[Managing_Datadog_with_Pulumi#Importing_an_Externally_Created_DashboardJson|Import an externally created Datadog DashboardJson]]


Flags:
The resources to be imported may be specified into a JSON file instead of command line arguments:
      --config-file string                    Use the configuration values in the specified file rather than detecting the file name
<syntaxhighlight lang='bash'>
  -d, --debug                                Print detailed debugging output during resource operations
pulumi stack import --file stack.json
      --diff                                  Display operation as a rich diff showing the overall change
</syntaxhighlight>
  -f, --file string                          The path to a JSON-encoded file containing a list of resources to import
      --generate-code                        Generate resource declaration code for the imported resources (default true)
  -h, --help                                  help for import
  -m, --message string                        Optional message to associate with the update operation
  -o, --out string                            The path to the file that will contain the generated resource declarations
  -p, --parallel int                          Allow P resource operations to run in parallel at once (1 for no parallelism). Defaults to unbounded. (default 2147483647)
      --parent string                        The name and URN of the parent resource in the format name=urn, where name is the variable name of the parent resource
      --properties strings                    The property names to use for the import in the format name1,name2
      --protect                              Allow resources to be imported with protection from deletion enabled (default true)
      --provider string                      The name and URN of the provider to use for the import in the format name=urn, where name is the variable name for the provider resource
      --skip-preview                          Do not perform a preview before performing the refresh
  -s, --stack string                          The name of the stack to operate on. Defaults to the current stack
      --suppress-outputs                      Suppress display of stack outputs (in case they contain sensitive values)
      --suppress-permalink string[="false"]  Suppress display of the state permalink
  -y, --yes                                  Automatically approve and perform the refresh after previewing it


Global Flags:
To see how import fits into the Pulumi programming model see: {{Internal|Pulumi_Programming_Model#Importing_.28Adopting.29_an_Infrastructure_Resource|Pulumi Programming Model &#124; Importing (Adopting) an Infrastructure Resource}}
      --color string                Colorize output. Choices are: always, never, raw, auto (default "auto")
 
  -C, --cwd string                  Run pulumi as if it had been started in another directory
==Import the Entire Stack as JSON==
      --disable-integrity-checking  Disable integrity checking of checkpoint files
It is possible to export a stack as JSON, edit it and the import it in bulk:
  -e, --emoji                        Enable emojis in the output (default true)
      --logflow                      Flow log settings to child processes (like plugins)
      --logtostderr                  Log to stderr instead of to files
      --non-interactive              Disable interactive mode for all commands
      --profiling string            Emit CPU and memory profiles and an execution trace to '[filename].[pid].{cpu,mem,trace}', respectively
      --tracing file:                Emit tracing to the specified endpoint. Use the file: scheme to write tracing data to a local file
  -v, --verbose int                  Enable verbose logging (e.g., v=3); anything >3 is very verbose
</font>


==Export==
<syntaxhighlight lang='bash'>
<syntaxhighlight lang='bash'>
pulumi stack export [--file stack.json] # by default will send the content to stdout
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
</syntaxhighlight>
</syntaxhighlight>


Latest revision as of 22:19, 22 April 2022

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

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.

Options

--show-secrets

--json

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:

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
Retrieved from "https://kb.novaordis.com/index.php?title=Pulumi_Operations&oldid=92307"