Module automation
APIs
- ConfigMap
- ConfigValue
- Deployment
- DestroyOptions
- DestroyResult
- fullyQualifiedStackName
- GlobalOpts
- InlineProgramArgs
- LocalProgramArgs
- LocalWorkspace
- LocalWorkspaceOptions
- OpMap
- OpType
- OutputMap
- OutputValue
- PluginInfo
- PluginKind
- PreviewOptions
- PreviewResult
- ProjectBackend
- ProjectRuntime
- ProjectRuntimeInfo
- ProjectSettings
- ProjectTemplate
- ProjectTemplateConfigValue
- PulumiFn
- RawJSON
- RefreshOptions
- RefreshResult
- RemoteDestroyOptions
- RemoteGitAuthArgs
- RemoteGitProgramArgs
- RemotePreviewOptions
- RemoteRefreshOptions
- RemoteStack
- RemoteUpOptions
- RemoteWorkspace
- RemoteWorkspaceOptions
- Stack
- StackSettings
- StackSettingsConfigValue
- StackSettingsSecureConfigValue
- StackSummary
- UpdateKind
- UpdateResult
- UpdateSummary
- UpOptions
- UpResult
- WhoAmIResult
- Workspace
APIs
type ConfigMap
type ConfigMap = {[key: string]: ConfigValue};
ConfigMap is a map of string to ConfigValue
interface ConfigValue
interface ConfigValue
ConfigValue is the input/output of a pulumi config
command.
It has a plaintext value, and an option boolean indicating secretness.
property secret
secret?: undefined | false | true;
property value
value: string;
interface Deployment
interface Deployment
Deployment encapsulates the state of a stack deployment.
property deployment
deployment: any;
The pulumi deployment.
property version
version: number;
Version indicates the schema of the encoded deployment.
interface DestroyOptions
interface DestroyOptions extends GlobalOpts
Options controlling the behavior of a Stack.destroy() operation.
property color
color?: "always" | "never" | "raw" | "auto";
property debug
debug?: undefined | false | true;
Print detailed debugging output during resource operations
property excludeProtected
excludeProtected?: undefined | false | true;
Do not destroy protected resources.
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 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 DestroyResult
interface DestroyResult
Output from destroying all resources in a Stack.
property stderr
stderr: string;
property stdout
stdout: string;
property summary
summary: UpdateSummary;
function fullyQualifiedStackName
fullyQualifiedStackName(org: string, project: string, stack: string): string
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.
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.
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.
method listTags
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.
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.
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.
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.
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.
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.
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.
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.
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.
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>
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 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>
method listTags
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.
method listTags
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>
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.
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[]>
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.
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
Thank you for your feedback!
If you have a question about how to use Pulumi, reach out in Community Slack.
Open an issue on GitHub to report a problem or suggest an improvement.