Module automation

Returns a stack name formatted with the greatest possible specificity: org/project/stack or user/project/stack Using this format avoids ambiguity in stack identity guards creating or selecting the wrong stack. Note that filestate backends (local file, S3, Azure Blob) do not support stack names in this format, and instead only use the stack name without an org/user or project to qualify it. See: https://github.com/pulumi/pulumi/issues/2522

interface GlobalOpts

interface GlobalOpts

property color

color?: "always" | "never" | "raw" | "auto";

Colorize output.

property debug

debug?: undefined | false | true;

Print detailed debugging output during resource operations

property logFlow

logFlow?: undefined | false | true;

Flow log settings to child processes (like plugins)

property logToStdErr

logToStdErr?: undefined | false | true;

Log to stderr instead of to files

property logVerbosity

logVerbosity?: undefined | number;

Enable verbose logging (e.g., v=3); anything >3 is very verbose

property tracing

tracing?: undefined | string;

Emit tracing to the specified endpoint. Use the file: scheme to write tracing data to a local file

interface InlineProgramArgs

interface InlineProgramArgs

Description of a stack backed by an inline (in process) Pulumi program.

property program

program: PulumiFn;

The inline (in process) Pulumi program to use with Update and Preview operations.

property projectName

projectName: string;

The name of the associated project

property stackName

stackName: string;

The name of the associated Stack

interface LocalProgramArgs

interface LocalProgramArgs

Description of a stack backed by pre-existing local Pulumi CLI program.

property stackName

stackName: string;

property workDir

workDir: string;

class LocalWorkspace

 implements Workspace

LocalWorkspace is a default implementation of the Workspace interface. A Workspace is the execution context containing a single Pulumi project, a program, and multiple stacks. Workspaces are used to manage the execution environment, providing various utilities such as plugin installation, environment configuration ($PULUMI_HOME), and creation, deletion, and listing of Stacks. LocalWorkspace relies on Pulumi.yaml and Pulumi..yaml as the intermediate format for Project and Stack settings. Modifying ProjectSettings will alter the Workspace Pulumi.yaml file, and setting config on a Stack will modify the Pulumi..yaml file. This is identical to the behavior of Pulumi CLI driven workspaces.

accessor pulumiVersion

public get pulumiVersion(): string;

The version of the underlying Pulumi CLI/Engine.

method create

static create(opts: LocalWorkspaceOptions): Promise<LocalWorkspace>

Creates a workspace using the specified options. Used for maximal control and customization of the underlying environment before any stacks are created or selected.

method createOrSelectStack

static createOrSelectStack(args: LocalProgramArgs, opts?: LocalWorkspaceOptions): Promise<Stack>

Creates or selects an existing Stack with a LocalWorkspace utilizing the specified inline (in process) Pulumi CLI program. This program is fully debuggable and runs in process. If no Project option is specified, default project settings will be created on behalf of the user. Similarly, unless a workDir option is specified, the working directory will default to a new temporary directory provided by the OS.

static createOrSelectStack(args: InlineProgramArgs, opts?: LocalWorkspaceOptions): Promise<Stack>

Creates or selects an existing Stack with a LocalWorkspace utilizing the specified inline Pulumi CLI program. This program is fully debuggable and runs in process. If no Project option is specified, default project settings will be created on behalf of the user. Similarly, unless a workDir option is specified, the working directory will default to a new temporary directory provided by the OS.

method createStack

createStack(stackName: string): Promise<void>

Creates and sets a new stack with the stack name, failing if one already exists.

method createStack

static createStack(args: LocalProgramArgs, opts?: LocalWorkspaceOptions): Promise<Stack>

Creates a Stack with a LocalWorkspace utilizing the local Pulumi CLI program from the specified workDir. This is a way to create drivers on top of pre-existing Pulumi programs. This Workspace will pick up any available Settings files (Pulumi.yaml, Pulumi..yaml).

static createStack(args: InlineProgramArgs, opts?: LocalWorkspaceOptions): Promise<Stack>

Creates a Stack with a LocalWorkspace utilizing the specified inline (in process) Pulumi program. This program is fully debuggable and runs in process. If no Project option is specified, default project settings will be created on behalf of the user. Similarly, unless a workDir option is specified, the working directory will default to a new temporary directory provided by the OS.

method exportStack

exportStack(stackName: string): Promise<Deployment>

exportStack exports the deployment state of the stack. This can be combined with Workspace.importStack to edit a stack’s state (such as recovery from failed deployments).

method getAllConfig

getAllConfig(stackName: string): Promise<ConfigMap>

Returns the config map for the specified stack name, scoped to the current workspace. LocalWorkspace reads this config from the matching Pulumi.stack.yaml file.

method getConfig

getConfig(stackName: string, key: string): Promise<ConfigValue>

Returns the value associated with the specified stack name and key, scoped to the current workspace. LocalWorkspace reads this config from the matching Pulumi.stack.yaml file.

method getTag

getTag(stackName: string, key: string): Promise<string>

Returns the value associated with the specified stack name and key, scoped to the LocalWorkspace.

method importStack

importStack(stackName: string, state: Deployment): Promise<void>

importStack imports the specified deployment state into a pre-existing stack. This can be combined with Workspace.exportStack to edit a stack’s state (such as recovery from failed deployments).

method installPlugin

installPlugin(name: string, version: string, kind: string): Promise<void>

Installs a plugin in the Workspace, for example to use cloud providers like AWS or GCP.

method installPluginFromServer

installPluginFromServer(name: string, version: string, server: string): Promise<void>

Installs a plugin in the Workspace, from a third party server.

method listPlugins

listPlugins(): Promise<PluginInfo[]>

Returns a list of all plugins installed in the Workspace.

method listStacks

listStacks(): Promise<StackSummary[]>

Returns all Stacks created under the current Project. This queries underlying backend and may return stacks not present in the Workspace (as Pulumi..yaml files).

listTags(stackName: string): Promise<TagMap>

Returns the tag map for the specified tag name, scoped to the current LocalWorkspace.

method postCommandCallback

postCommandCallback(_: string): Promise<void>

postCommandCallback is a hook executed after every command. Called with the stack name. An extensibility point to perform workspace cleanup (CLI operations may create/modify a Pulumi.stack.yaml) LocalWorkspace does not utilize this extensibility point.

method projectSettings

projectSettings(): Promise<ProjectSettings>

Returns the settings object for the current project if any LocalWorkspace reads settings from the Pulumi.yaml in the workspace. A workspace can contain only a single project at a time.

method refreshConfig

refreshConfig(stackName: string): Promise<ConfigMap>

Gets and sets the config map used with the last update for Stack matching stack name. It will overwrite all configuration in the Pulumi..yaml file in Workspace.WorkDir().

method removeAllConfig

removeAllConfig(stackName: string, keys: string[]): Promise<void>

Removes all values in the provided key list for the specified stack name It will remove any matching values in the Pulumi..yaml file in Workspace.WorkDir().

method removeConfig

removeConfig(stackName: string, key: string): Promise<void>

Removes the specified key-value pair on the provided stack name. It will remove any matching values in the Pulumi..yaml file in Workspace.WorkDir().

method removePlugin

removePlugin(name?: undefined | string, versionRange?: undefined | string, kind: string): Promise<void>

Removes a plugin from the Workspace matching the specified name and version.

method removeStack

removeStack(stackName: string): Promise<void>

Deletes the stack and all associated configuration and history.

method removeTag

removeTag(stackName: string, key: string): Promise<void>

Removes the specified key-value pair on the provided stack name.

method saveProjectSettings

saveProjectSettings(settings: ProjectSettings): Promise<void>

Overwrites the settings object in the current project. There can only be a single project per workspace. Fails if new project name does not match old. LocalWorkspace writes this value to a Pulumi.yaml file in Workspace.WorkDir().

method saveStackSettings

saveStackSettings(stackName: string, settings: StackSettings): Promise<void>

Overwrites the settings object for the stack matching the specified stack name. LocalWorkspace writes this value to a Pulumi..yaml file in Workspace.WorkDir()

method selectStack

selectStack(stackName: string): Promise<void>

Selects and sets an existing stack matching the stack name, failing if none exists.

method selectStack

static selectStack(args: LocalProgramArgs, opts?: LocalWorkspaceOptions): Promise<Stack>

Selects a Stack with a LocalWorkspace utilizing the local Pulumi CLI program from the specified workDir. This is a way to create drivers on top of pre-existing Pulumi programs. This Workspace will pick up any available Settings files (Pulumi.yaml, Pulumi..yaml).

static selectStack(args: InlineProgramArgs, opts?: LocalWorkspaceOptions): Promise<Stack>

Selects an existing Stack with a LocalWorkspace utilizing the specified inline (in process) Pulumi program. This program is fully debuggable and runs in process. If no Project option is specified, default project settings will be created on behalf of the user. Similarly, unless a workDir option is specified, the working directory will default to a new temporary directory provided by the OS.

method serializeArgsForOp

serializeArgsForOp(_: string): Promise<string[]>

serializeArgsForOp is hook to provide additional args to every CLI commands before they are executed. Provided with stack name, returns a list of args to append to an invoked command ["–config=…", ] LocalWorkspace does not utilize this extensibility point.

method setAllConfig

setAllConfig(stackName: string, config: ConfigMap): Promise<void>

Sets all values in the provided config map for the specified stack name. LocalWorkspace writes the config to the matching Pulumi..yaml file in Workspace.WorkDir().

method setConfig

setConfig(stackName: string, key: string, value: ConfigValue): Promise<void>

Sets the specified key-value pair on the provided stack name. LocalWorkspace writes this value to the matching Pulumi..yaml file in Workspace.WorkDir().

method setTag

setTag(stackName: string, key: string, value: string): Promise<void>

Sets the specified key-value pair on the provided stack name.

method stack

stack(): Promise<StackSummary | undefined>

Returns a summary of the currently selected stack, if any.

method stackOutputs

stackOutputs(stackName: string): Promise<OutputMap>

Gets the current set of Stack outputs from the last Stack.up().

method stackSettings

stackSettings(stackName: string): Promise<StackSettings>

Returns the settings object for the stack matching the specified stack name if any. LocalWorkspace reads this from a Pulumi..yaml file in Workspace.WorkDir().

method whoAmI

whoAmI(): Promise<WhoAmIResult>

Returns the currently authenticated user.

property envVars

envVars: {[key: string]: string};

Environment values scoped to the current workspace. These will be supplied to every Pulumi command.

property program

program?: PulumiFn;

The inline program PulumiFn to be used for Preview/Update operations if any. If none is specified, the stack will refer to ProjectSettings for this information.

property pulumiHome

pulumiHome?: undefined | string;

The directory override for CLI metadata if set. This customizes the location of $PULUMI_HOME where metadata is stored and plugins are installed.

property secretsProvider

secretsProvider?: undefined | string;

The secrets provider to use for encryption and decryption of stack secrets. See: https://www.pulumi.com/docs/intro/concepts/secrets/#available-encryption-providers

property workDir

workDir: string;

The working directory to run Pulumi CLI commands

interface LocalWorkspaceOptions

interface LocalWorkspaceOptions

Extensibility options to configure a LocalWorkspace; e.g: settings to seed and environment variables to pass through to every command.

property envVars

envVars?: undefined | {[key: string]: string};

Environment values scoped to the current workspace. These will be supplied to every Pulumi command.

property program

program?: PulumiFn;

The inline program PulumiFn to be used for Preview/Update operations if any. If none is specified, the stack will refer to ProjectSettings for this information.

property projectSettings

projectSettings?: ProjectSettings;

The settings object for the current project.

property pulumiHome

pulumiHome?: undefined | string;

The directory to override for CLI metadata

property secretsProvider

secretsProvider?: undefined | string;

The secrets provider to use for encryption and decryption of stack secrets. See: https://www.pulumi.com/docs/intro/concepts/secrets/#available-encryption-providers

property stackSettings

stackSettings?: undefined | {[key: string]: StackSettings};

A map of Stack names and corresponding settings objects.

property workDir

workDir?: undefined | string;

The directory to run Pulumi commands and read settings (Pulumi.yaml and Pulumi..yaml)l.

type OpMap

type OpMap = { ... };

A map of operation types and their corresponding counts.

type OpType

type OpType = "same" | "create" | "update" | "delete" | "replace" | "create-replacement" | "delete-replaced" | "read" | "read-replacement" | "refresh" | "discard" | "discard-replaced" | "remove-pending-replace" | "import" | "import-replacement";

The granular CRUD operation performed on a particular resource during an update.

type OutputMap

type OutputMap = {[key: string]: OutputValue};

interface OutputValue

interface OutputValue

property secret

secret: boolean;

property value

value: any;

interface PluginInfo

interface PluginInfo

property installTime

installTime: Date;

property kind

kind: PluginKind;

property lastUsedTime

lastUsedTime: Date;

property name

name: string;

property path

path: string;

property serverURL

serverURL: string;

property size

size: number;

property version

version?: undefined | string;

type PluginKind

type PluginKind = "analyzer" | "language" | "resource";

interface PreviewOptions

interface PreviewOptions extends GlobalOpts

Options controlling the behavior of a Stack.preview() operation.

property color

color?: "always" | "never" | "raw" | "auto";

property debug

debug?: undefined | false | true;

Print detailed debugging output during resource operations

property diff

diff?: undefined | false | true;

property expectNoChanges

expectNoChanges?: undefined | false | true;

property logFlow

logFlow?: undefined | false | true;

Flow log settings to child processes (like plugins)

property logToStdErr

logToStdErr?: undefined | false | true;

Log to stderr instead of to files

property logVerbosity

logVerbosity?: undefined | number;

Enable verbose logging (e.g., v=3); anything >3 is very verbose

property message

message?: undefined | string;

property onEvent

onEvent?: undefined | (event: EngineEvent) => void;

property onOutput

onOutput?: undefined | (out: string) => void;

property parallel

parallel?: undefined | number;

property plan

plan?: undefined | string;

Plan specifies the path where the update plan should be saved.

property policyPackConfigs

policyPackConfigs?: string[];

property policyPacks

policyPacks?: string[];

property program

program?: PulumiFn;

property refresh

refresh?: undefined | false | true;

Refresh the state of the stack’s resources against the cloud provider before running preview.

property replace

replace?: string[];

property target

target?: string[];

property targetDependents

targetDependents?: undefined | false | true;

property tracing

tracing?: undefined | string;

Emit tracing to the specified endpoint. Use the file: scheme to write tracing data to a local file

property userAgent

userAgent?: undefined | string;

interface PreviewResult

interface PreviewResult

Output from running a Pulumi program preview.

property changeSummary

changeSummary: OpMap;

property stderr

stderr: string;

property stdout

stdout: string;

interface ProjectBackend

interface ProjectBackend

Configuration for the project’s Pulumi state storage backend.

property url

url?: undefined | string;

type ProjectRuntime

type ProjectRuntime = "nodejs" | "go" | "python" | "dotnet";

Supported Pulumi program language runtimes.

interface ProjectRuntimeInfo

interface ProjectRuntimeInfo

A description of the Project’s program runtime and associated metadata.

property name

name: string;

property options

options?: undefined | {[key: string]: any};

interface ProjectSettings

interface ProjectSettings

A Pulumi project manifest. It describes metadata applying to all sub-stacks created from the project.

property author

author?: undefined | string;

property backend

backend?: ProjectBackend;

property config

config?: undefined | string;

property description

description?: undefined | string;

property license

license?: undefined | string;

property main

main?: undefined | string;

property name

name: string;

property runtime

runtime: ProjectRuntimeInfo | ProjectRuntime;

property template

template?: ProjectTemplate;

property website

website?: undefined | string;

interface ProjectTemplate

interface ProjectTemplate

A template used to seed new stacks created from this project.

property config

config?: undefined | {[key: string]: ProjectTemplateConfigValue};

property description

description?: undefined | string;

property important

important?: undefined | false | true;

property quickstart

quickstart?: undefined | string;

interface ProjectTemplateConfigValue

interface ProjectTemplateConfigValue

A placeholder config value for a project template.

property default

default?: undefined | string;

property description

description?: undefined | string;

property secret

secret?: undefined | false | true;

type PulumiFn

type PulumiFn = () => Promise<Record<string, any> | void>;

A Pulumi program as an inline function (in process).

type RawJSON

type RawJSON = string;

An unstructured JSON string used for back-compat with versioned APIs (such as Deployment).

interface RefreshOptions

interface RefreshOptions extends GlobalOpts

Options controlling the behavior of a Stack.refresh() operation.

property color

color?: "always" | "never" | "raw" | "auto";

property debug

debug?: undefined | false | true;

Print detailed debugging output during resource operations

property expectNoChanges

expectNoChanges?: undefined | false | true;

property logFlow

logFlow?: undefined | false | true;

Flow log settings to child processes (like plugins)

property logToStdErr

logToStdErr?: undefined | false | true;

Log to stderr instead of to files

property logVerbosity

logVerbosity?: undefined | number;

Enable verbose logging (e.g., v=3); anything >3 is very verbose

property message

message?: undefined | string;

property onEvent

onEvent?: undefined | (event: EngineEvent) => void;

property onOutput

onOutput?: undefined | (out: string) => void;

property parallel

parallel?: undefined | number;

property showSecrets

showSecrets?: undefined | false | true;

property target

target?: string[];

property tracing

tracing?: undefined | string;

Emit tracing to the specified endpoint. Use the file: scheme to write tracing data to a local file

property userAgent

userAgent?: undefined | string;

interface RefreshResult

interface RefreshResult

Output from refreshing the resources in a given Stack.

property stderr

stderr: string;

property stdout

stdout: string;

property summary

summary: UpdateSummary;

interface RemoteDestroyOptions

interface RemoteDestroyOptions

Options controlling the behavior of a RemoteStack.destroy() operation.

property onEvent

onEvent?: undefined | (event: EngineEvent) => void;

property onOutput

onOutput?: undefined | (out: string) => void;

interface RemoteGitAuthArgs

interface RemoteGitAuthArgs

Authentication options for the repository that can be specified for a private Git repo. There are three different authentication paths:

Personal accesstoken
SSH private key (and its optional password)
Basic auth username and password

Only one authentication path is valid.

property password

password?: undefined | string;

The password that pairs with a username or as part of an SSH Private Key.

property personalAccessToken

personalAccessToken?: undefined | string;

PersonalAccessToken is a Git personal access token in replacement of your password.

property sshPrivateKey

sshPrivateKey?: undefined | string;

The (contents) private key for access to the git repo.

property sshPrivateKeyPath

sshPrivateKeyPath?: undefined | string;

The absolute path to a private key for access to the git repo.

property username

username?: undefined | string;

Username is the username to use when authenticating to a git repository

interface RemoteGitProgramArgs

interface RemoteGitProgramArgs

Description of a stack backed by a remote Pulumi program in a Git repository.

property auth

auth?: RemoteGitAuthArgs;

Authentication options for the repository.

property branch

branch?: undefined | string;

Optional branch to checkout.

property commitHash

commitHash?: undefined | string;

Optional commit to checkout.

property projectPath

projectPath?: undefined | string;

Optional path relative to the repo root specifying location of the Pulumi program.

property stackName

stackName: string;

The name of the associated Stack

property url

url: string;

The URL of the repository.

interface RemotePreviewOptions

interface RemotePreviewOptions

Options controlling the behavior of a RemoteStack.preview() operation.

property onEvent

onEvent?: undefined | (event: EngineEvent) => void;

property onOutput

onOutput?: undefined | (out: string) => void;

interface RemoteRefreshOptions

interface RemoteRefreshOptions

Options controlling the behavior of a RemoteStack.refresh() operation.

property onEvent

onEvent?: undefined | (event: EngineEvent) => void;

property onOutput

onOutput?: undefined | (out: string) => void;

class RemoteStack

class RemoteStack

RemoteStack is an isolated, independencly configurable instance of a Pulumi program that is operated on remotely (up/preview/refresh/destroy).

accessor name

get name(): string;

The name identifying the Stack.

method cancel

cancel(): Promise<void>

Cancel stops a stack’s currently running update. It returns an error if no update is currently running. Note that this operation is very dangerous, and may leave the stack in an inconsistent state if a resource operation was pending when the update was canceled. This command is not supported for local backends.

method destroy

destroy(opts?: RemoteDestroyOptions): Promise<DestroyResult>

Destroy deletes all resources in a stack, leaving all history and configuration intact. This operation runs remotely.

method exportStack

exportStack(): Promise<Deployment>

exportStack exports the deployment state of the stack. This can be combined with Stack.importStack to edit a stack’s state (such as recovery from failed deployments).

method history

history(pageSize?: undefined | number, page?: undefined | number): Promise<UpdateSummary[]>

Returns a list summarizing all previous and current results from Stack lifecycle operations (up/preview/refresh/destroy).

method importStack

importStack(state: Deployment): Promise<void>

importStack imports the specified deployment state into a pre-existing stack. This can be combined with Stack.exportStack to edit a stack’s state (such as recovery from failed deployments).

method outputs

outputs(): Promise<OutputMap>

Gets the current set of Stack outputs from the last Stack.up().

method preview

preview(opts?: RemotePreviewOptions): Promise<PreviewResult>

Performs a dry-run update to a stack, returning pending changes. https://www.pulumi.com/docs/cli/commands/pulumi_preview/ This operation runs remotely.

method refresh

refresh(opts?: RemoteRefreshOptions): Promise<RefreshResult>

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. This operation runs remotely.

method up

up(opts?: RemoteUpOptions): Promise<UpResult>

Creates or updates the resources in a stack by executing the program in the Workspace. https://www.pulumi.com/docs/cli/commands/pulumi_up/ This operation runs remotely.

interface RemoteUpOptions

interface RemoteUpOptions

Options controlling the behavior of a RemoteStack.up() operation.

property onEvent

onEvent?: undefined | (event: EngineEvent) => void;

property onOutput

onOutput?: undefined | (out: string) => void;

class RemoteWorkspace

class RemoteWorkspace

RemoteWorkspace is the execution context containing a single remote Pulumi project.

method createOrSelectStack

static createOrSelectStack(args: RemoteGitProgramArgs, opts?: RemoteWorkspaceOptions): Promise<RemoteStack>

PREVIEW: Creates or selects an existing Stack backed by a RemoteWorkspace with source code from the specified Git repository. Pulumi operations on the stack (Preview, Update, Refresh, and Destroy) are performed remotely.

method createStack

static createStack(args: RemoteGitProgramArgs, opts?: RemoteWorkspaceOptions): Promise<RemoteStack>

PREVIEW: Creates a Stack backed by a RemoteWorkspace with source code from the specified Git repository. Pulumi operations on the stack (Preview, Update, Refresh, and Destroy) are performed remotely.

method selectStack

static selectStack(args: RemoteGitProgramArgs, opts?: RemoteWorkspaceOptions): Promise<RemoteStack>

PREVIEW: Selects an existing Stack backed by a RemoteWorkspace with source code from the specified Git repository. Pulumi operations on the stack (Preview, Update, Refresh, and Destroy) are performed remotely.

interface RemoteWorkspaceOptions

interface RemoteWorkspaceOptions

Extensibility options to configure a RemoteWorkspace.

property envVars

envVars?: undefined | {[key: string]: string | {
    secret: string;
}};

Environment values scoped to the remote workspace. These will be passed to remote operations.

property preRunCommands

preRunCommands?: string[];

An optional list of arbitrary commands to run before a remote Pulumi operation is invoked.

property skipInstallDependencies

skipInstallDependencies?: undefined | false | true;

Whether to skip the default dependency installation step. Defaults to false.

class Stack

class Stack

Stack is an isolated, independently configurable instance of a Pulumi program. Stack exposes methods for the full pulumi lifecycle (up/preview/refresh/destroy), as well as managing configuration. Multiple Stacks are commonly used to denote different phases of development (such as development, staging and production) or feature branches (such as feature-x-dev, jane-feature-x-dev).

method cancel

cancel(): Promise<void>

method create

static create(name: string, workspace: Workspace): Promise<Stack>

Creates a new stack using the given workspace, and stack name. It fails if a stack with that name already exists

method createOrSelect

static createOrSelect(name: string, workspace: Workspace): Promise<Stack>

Tries to create a new stack using the given workspace and stack name if the stack does not already exist, or falls back to selecting the existing stack. If the stack does not exist, it will be created and selected.

method destroy

destroy(opts?: DestroyOptions): Promise<DestroyResult>

Destroy deletes all resources in a stack, leaving all history and configuration intact.

method exportStack

exportStack(): Promise<Deployment>

exportStack exports the deployment state of the stack. This can be combined with Stack.importStack to edit a stack’s state (such as recovery from failed deployments).

method getAllConfig

getAllConfig(): Promise<ConfigMap>

Returns the full config map associated with the stack in the Workspace.

method getConfig

getConfig(key: string): Promise<ConfigValue>

Returns the config value associated with the specified key.

method getTag

getTag(key: string): Promise<string>

Returns the tag value associated with specified key.

method history

history(pageSize?: undefined | number, page?: undefined | number, showSecrets?: undefined | false | true): Promise<UpdateSummary[]>

Returns a list summarizing all previous and current results from Stack lifecycle operations (up/preview/refresh/destroy).

method importStack

importStack(state: Deployment): Promise<void>

importStack imports the specified deployment state into a pre-existing stack. This can be combined with Stack.exportStack to edit a stack’s state (such as recovery from failed deployments).

method info

info(showSecrets?: undefined | false | true): Promise<UpdateSummary | undefined>

listTags(): Promise<TagMap>

Returns the full tag map associated with the stack in the Workspace.

method outputs

outputs(): Promise<OutputMap>

Gets the current set of Stack outputs from the last Stack.up().

method preview

preview(opts?: PreviewOptions): Promise<PreviewResult>

Performs a dry-run update to a stack, returning pending changes. https://www.pulumi.com/docs/cli/commands/pulumi_preview/

method refresh

refresh(opts?: RefreshOptions): Promise<RefreshResult>

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.

method refreshConfig

refreshConfig(): Promise<ConfigMap>

Gets and sets the config map used with the last update.

method removeAllConfig

removeAllConfig(keys: string[]): Promise<void>

Removes the specified config keys from the Stack in the associated Workspace.

method removeConfig

removeConfig(key: string): Promise<void>

Removes the specified config key from the Stack in the associated Workspace.

method removeTag

removeTag(key: string): Promise<void>

Removes the specified tag key-value pair from the Stack in the associated Workspace.

method select

static select(name: string, workspace: Workspace): Promise<Stack>

Selects stack using the given workspace, and stack name. It returns an error if the given Stack does not exist.

method setAllConfig

setAllConfig(config: ConfigMap): Promise<void>

Sets all specified config values on the stack in the associated Workspace.

method setConfig

setConfig(key: string, value: ConfigValue): Promise<void>

Sets a config key-value pair on the Stack in the associated Workspace.

method setTag

setTag(key: string, value: string): Promise<void>

Sets a tag key-value pair on the Stack in the associated Workspace.

method up

up(opts?: UpOptions): Promise<UpResult>

Creates or updates the resources in a stack by executing the program in the Workspace. https://www.pulumi.com/docs/cli/commands/pulumi_up/

property name

name: string;

The name identifying the Stack.

property workspace

workspace: Workspace;

The Workspace the Stack was created from.

interface StackSettings

interface StackSettings

A description of the Stack’s configuration and encryption metadata.

property config

config?: undefined | {[key: string]: StackSettingsConfigValue};

property encryptedKey

encryptedKey?: undefined | string;

property encryptionSalt

encryptionSalt?: undefined | string;

property secretsProvider

secretsProvider?: undefined | string;

type StackSettingsConfigValue

type StackSettingsConfigValue = string | StackSettingsSecureConfigValue | any;

Stack configuration entry

interface StackSettingsSecureConfigValue

interface StackSettingsSecureConfigValue

A secret Stack config entry

property secure

secure: string;

interface StackSummary

interface StackSummary

A summary of the status of a given stack.

property current

current: boolean;

property lastUpdate

lastUpdate?: undefined | string;

property name

name: string;

property resourceCount

resourceCount?: undefined | number;

property updateInProgress

updateInProgress: boolean;

property url

url?: undefined | string;

type UpdateKind

type UpdateKind = "update" | "preview" | "refresh" | "rename" | "destroy" | "import";

The kind of update that was performed on the stack.

type UpdateResult

type UpdateResult = "not-started" | "in-progress" | "succeeded" | "failed";

Represents the current status of a given update.

interface UpdateSummary

interface UpdateSummary

property Deployment

Deployment?: RawJSON;

property config

config: ConfigMap;

property endTime

endTime: Date;

property environment

environment: {[key: string]: string};

property kind

kind: UpdateKind;

property message

message: string;

property resourceChanges

resourceChanges?: OpMap;

property result

result: UpdateResult;

property startTime

startTime: Date;

property version

version: number;

interface UpOptions

interface UpOptions extends GlobalOpts

Options controlling the behavior of a Stack.up() operation.

property color

color?: "always" | "never" | "raw" | "auto";

Colorize output.

property debug

debug?: undefined | false | true;

Print detailed debugging output during resource operations

property diff

diff?: undefined | false | true;

property expectNoChanges

expectNoChanges?: undefined | false | true;

property logFlow

logFlow?: undefined | false | true;

Flow log settings to child processes (like plugins)

property logToStdErr

logToStdErr?: undefined | false | true;

Log to stderr instead of to files

property logVerbosity

logVerbosity?: undefined | number;

Enable verbose logging (e.g., v=3); anything >3 is very verbose

property message

message?: undefined | string;

property onEvent

onEvent?: undefined | (event: EngineEvent) => void;

property onOutput

onOutput?: undefined | (out: string) => void;

property parallel

parallel?: undefined | number;

property plan

plan?: undefined | string;

Plan specifies the path to an update plan to use for the update.

property policyPackConfigs

policyPackConfigs?: string[];

property policyPacks

policyPacks?: string[];

property program

program?: PulumiFn;

property replace

replace?: string[];

property showSecrets

showSecrets?: undefined | false | true;

Include secrets in the UpSummary.

property target

target?: string[];

property targetDependents

targetDependents?: undefined | false | true;

property tracing

tracing?: undefined | string;

Emit tracing to the specified endpoint. Use the file: scheme to write tracing data to a local file

property userAgent

userAgent?: undefined | string;

interface UpResult

interface UpResult

The deployment output from running a Pulumi program update.

property outputs

outputs: OutputMap;

property stderr

stderr: string;

property stdout

stdout: string;

property summary

summary: UpdateSummary;

interface WhoAmIResult

interface WhoAmIResult

The currently logged-in Pulumi identity.

property organizations

organizations?: string[];

property url

url?: undefined | string;

property user

user: string;

interface Workspace

interface Workspace

Workspace is the execution context containing a single Pulumi project, a program, and multiple stacks. Workspaces are used to manage the execution environment, providing various utilities such as plugin installation, environment configuration ($PULUMI_HOME), and creation, deletion, and listing of Stacks.

method createStack

createStack(stackName: string): Promise<void>

Creates and sets a new stack with the stack name, failing if one already exists.

method exportStack

exportStack(stackName: string): Promise<Deployment>

exportStack exports the deployment state of the stack. This can be combined with Workspace.importStack to edit a stack’s state (such as recovery from failed deployments).

method getAllConfig

getAllConfig(stackName: string): Promise<ConfigMap>

Returns the config map for the specified stack name, scoped to the current Workspace.

method getConfig

getConfig(stackName: string, key: string): Promise<ConfigValue>

Returns the value associated with the specified stack name and key, scoped to the Workspace.

method getTag

getTag(stackName: string, key: string): Promise<string>

Returns the value associated with the specified stack name and key, scoped to the Workspace.

method importStack

importStack(stackName: string, state: Deployment): Promise<void>

importStack imports the specified deployment state into a pre-existing stack. This can be combined with Workspace.exportStack to edit a stack’s state (such as recovery from failed deployments).

method installPlugin

installPlugin(name: string, version: string, kind?: undefined | string): Promise<void>

Installs a plugin in the Workspace from a remote server, for example a third party plugin.

method installPluginFromServer

installPluginFromServer(name: string, version: string, server: string): Promise<void>

Installs a plugin in the Workspace, for example to use cloud providers like AWS or GCP.

method listPlugins

listPlugins(): Promise<PluginInfo[]>

Returns a list of all plugins installed in the Workspace.

method listStacks

listStacks(): Promise<StackSummary[]>

Returns all Stacks created under the current Project. This queries underlying backend and may return stacks not present in the Workspace (as Pulumi..yaml files).

listTags(stackName: string): Promise<TagMap>

Returns the tag map for the specified tag name, scoped to the current Workspace.

method postCommandCallback

postCommandCallback(stackName: string): Promise<void>

method projectSettings

projectSettings(): Promise<ProjectSettings>

Returns the settings object for the current project if any.

method refreshConfig

refreshConfig(stackName: string): Promise<ConfigMap>

Gets and sets the config map used with the last update for Stack matching stack name.

method removeAllConfig

removeAllConfig(stackName: string, keys: string[]): Promise<void>

Removes all values in the provided key list for the specified stack name.

method removeConfig

removeConfig(stackName: string, key: string): Promise<void>

Removes the specified key-value pair on the provided stack name.

method removePlugin

removePlugin(name?: undefined | string, versionRange?: undefined | string, kind?: undefined | string): Promise<void>

Removes a plugin from the Workspace matching the specified name and version.

method removeStack

removeStack(stackName: string): Promise<void>

Deletes the stack and all associated configuration and history.

method removeTag

removeTag(stackName: string, key: string): Promise<void>

Removes the specified key-value pair on the provided stack name.

method saveProjectSettings

saveProjectSettings(settings: ProjectSettings): Promise<void>

Overwrites the settings object in the current project. There can only be a single project per workspace. Fails is new project name does not match old.

method saveStackSettings

saveStackSettings(stackName: string, settings: StackSettings): Promise<void>

overwrites the settings object for the stack matching the specified stack name.

method selectStack

selectStack(stackName: string): Promise<void>

Selects and sets an existing stack matching the stack name, failing if none exists.

method serializeArgsForOp

serializeArgsForOp(stackName: string): Promise<string[]>

method setAllConfig

setAllConfig(stackName: string, config: ConfigMap): Promise<void>

Sets all values in the provided config map for the specified stack name.

method setConfig

setConfig(stackName: string, key: string, value: ConfigValue): Promise<void>

Sets the specified key-value pair on the provided stack name.

method setTag

setTag(stackName: string, key: string, value: string): Promise<void>

Sets the specified key-value pair on the provided stack name.

method stack

stack(): Promise<StackSummary | undefined>

Returns a summary of the currently selected stack, if any.

method stackOutputs

stackOutputs(stackName: string): Promise<OutputMap>

Gets the current set of Stack outputs from the last Stack.up().

method stackSettings

stackSettings(stackName: string): Promise<StackSettings>

Returns the settings object for the stack matching the specified stack name if any.

method whoAmI

whoAmI(): Promise<WhoAmIResult>

Returns the currently authenticated user.

property envVars

envVars: {[key: string]: string};

Environment values scoped to the current workspace. These will be supplied to every Pulumi command.

property program

program?: PulumiFn;

The inline program PulumiFn to be used for Preview/Update operations if any. If none is specified, the stack will refer to ProjectSettings for this information.

property pulumiHome

pulumiHome?: undefined | string;

The directory override for CLI metadata if set. This customizes the location of $PULUMI_HOME where metadata is stored and plugins are installed.

property pulumiVersion

pulumiVersion: string;

The version of the underlying Pulumi CLI/Engine.

property secretsProvider

secretsProvider?: undefined | string;

The secrets provider to use for encryption and decryption of stack secrets. See: https://www.pulumi.com/docs/intro/concepts/secrets/#available-encryption-providers

property workDir

workDir: string;

The working directory to run Pulumi CLI commands

Module automation

On this page

On this page

APIs

APIs